1GETC_UNLOCKED(P) POSIX Programmer's Manual GETC_UNLOCKED(P)
2
6 getc_unlocked, getchar_unlocked, putc_unlocked, putchar_unlocked -
7 stdio with explicit client locking
8
10 #include <stdio.h>
11 int getc_unlocked(FILE *stream);
13 int getchar_unlocked(void);
14 int putc_unlocked(int c, FILE *stream);
15 int putchar_unlocked(int c);
16
19 Versions of the functions getc(), getchar(), putc(), and putchar()
20 respectively named getc_unlocked(), getchar_unlocked(),
21 putc_unlocked(), and putchar_unlocked() shall be provided which are
22 functionally equivalent to the original versions, with the exception
23 that they are not required to be implemented in a thread-safe manner.
24 They may only safely be used within a scope protected by flockfile()
25 (or ftrylockfile()) and funlockfile(). These functions may safely be
26 used in a multi-threaded program if and only if they are called while
27 the invoking thread owns the ( FILE *) object, as is the case after a
28 successful call to the flockfile() or ftrylockfile() functions.
29
31 See getc() , getchar() , putc() , and putchar() .
32
34 See getc() , getchar() , putc() , and putchar() .
35 The following sections are informative.
37
39 None.
40
42 Since they may be implemented as macros, getc_unlocked() and
43 putc_unlocked() may treat incorrectly a stream argument with side
44 effects. In particular, getc_unlocked(*f++) and putc_unlocked(*f++) do
45 not necessarily work as expected. Therefore, use of these functions in
46 such situations should be preceded by the following statement as appro‐
47 priate:
48 #undef getc_unlocked
51 #undef putc_unlocked
52
54 Some I/O functions are typically implemented as macros for performance
55 reasons (for example, putc() and getc()). For safety, they need to be
56 synchronized, but it is often too expensive to synchronize on every
57 character. Nevertheless, it was felt that the safety concerns were more
58 important; consequently, the getc(), getchar(), putc(), and putchar()
59 functions are required to be thread-safe. However, unlocked versions
60 are also provided with names that clearly indicate the unsafe nature of
61 their operation but can be used to exploit their higher performance.
62 These unlocked versions can be safely used only within explicitly
63 locked program regions, using exported locking primitives. In particu‐
64 lar, a sequence such as:
65 flockfile(fileptr);
68 putc_unlocked('1', fileptr);
69 putc_unlocked('\n', fileptr);
70 fprintf(fileptr, "Line 2\n");
71 funlockfile(fileptr);
72 is permissible, and results in the text sequence:
74 1
77 Line 2
78 being printed without being interspersed with output from other
80 threads.
81 It would be wrong to have the standard names such as getc(), putc(),
83 and so on, map to the "faster, but unsafe" rather than the "slower, but
84 safe'' versions. In either case, you would still want to inspect all
85 uses of getc(), putc(), and so on, by hand when converting existing
86 code. Choosing the safe bindings as the default, at least, results in
87 correct code and maintains the "atomicity at the function" invariant.
88 To do otherwise would introduce gratuitous synchronization errors into
89 converted code. Other routines that modify the stdio ( FILE *) struc‐
90 tures or buffers are also safely synchronized.
91 Note that there is no need for functions of the form getc_locked(),
93 putc_locked(), and so on, since this is the functionality of getc(),
94 putc(), et al. It would be inappropriate to use a feature test macro to
95 switch a macro definition of getc() between getc_locked() and
96 getc_unlocked(), since the ISO C standard requires an actual function
97 to exist, a function whose behavior could not be changed by the feature
98 test macro. Also, providing both the xxx_locked() and xxx_unlocked()
99 forms leads to the confusion of whether the suffix describes the behav‐
100 ior of the function or the circumstances under which it should be used.
101 Three additional routines, flockfile(), ftrylockfile(), and funlock‐
103 file() (which may be macros), are provided to allow the user to delin‐
104 eate a sequence of I/O statements that are executed synchronously.
105 The ungetc() function is infrequently called relative to the other
107 functions/macros so no unlocked variation is needed.
108
110 None.
111
113 getc() , getchar() , putc() , putchar() , the Base Definitions volume
114 of IEEE Std 1003.1-2001, <stdio.h>
115
117 Portions of this text are reprinted and reproduced in electronic form
118 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
119 -- Portable Operating System Interface (POSIX), The Open Group Base
120 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
121 Electrical and Electronics Engineers, Inc and The Open Group. In the
122 event of any discrepancy between this version and the original IEEE and
123 The Open Group Standard, the original IEEE and The Open Group Standard
124 is the referee document. The original Standard can be obtained online
125 at http://www.opengroup.org/unix/online.html .
126IEEE/The Open Group 2003 GETC_UNLOCKED(P)