1GETC_UNLOCKED(3P) POSIX Programmer's Manual GETC_UNLOCKED(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 getc_unlocked, getchar_unlocked, putc_unlocked, putchar_unlocked —
13 stdio with explicit client locking
14
16 #include <stdio.h>
17 int getc_unlocked(FILE *stream);
19 int getchar_unlocked(void);
20 int putc_unlocked(int c, FILE *stream);
21 int putchar_unlocked(int c);
22
24 Versions of the functions getc(), getchar(), putc(), and putchar()
25 respectively named getc_unlocked(), getchar_unlocked(),
26 putc_unlocked(), and putchar_unlocked() shall be provided which are
27 functionally equivalent to the original versions, with the exception
28 that they are not required to be implemented in a fully thread-safe
29 manner. They shall be thread-safe when used within a scope protected by
30 flockfile() (or ftrylockfile()) and funlockfile(). These functions can
31 safely be used in a multi-threaded program if and only if they are
32 called while the invoking thread owns the (FILE *) object, as is the
33 case after a successful call to the flockfile() or ftrylockfile() func‐
34 tions.
35 If getc_unlocked() or putc_unlocked() are implemented as macros they
37 may evaluate stream more than once, so the stream argument should never
38 be an expression with side-effects.
39
41 See getc(), getchar(), putc(), and putchar().
42
44 See getc(), getchar(), putc(), and putchar().
45 The following sections are informative.
47
49 None.
50
52 Since they may be implemented as macros, getc_unlocked() and
53 putc_unlocked() may treat incorrectly a stream argument with side-
54 effects. In particular, getc_unlocked(*f++) and putc_unlocked(c,*f++)
55 do not necessarily work as expected. Therefore, use of these functions
56 in such situations should be preceded by the following statement as
57 appropriate:
58 #undef getc_unlocked
61 #undef putc_unlocked
62
64 Some I/O functions are typically implemented as macros for performance
65 reasons (for example, putc() and getc()). For safety, they need to be
66 synchronized, but it is often too expensive to synchronize on every
67 character. Nevertheless, it was felt that the safety concerns were more
68 important; consequently, the getc(), getchar(), putc(), and putchar()
69 functions are required to be thread-safe. However, unlocked versions
70 are also provided with names that clearly indicate the unsafe nature of
71 their operation but can be used to exploit their higher performance.
72 These unlocked versions can be safely used only within explicitly
73 locked program regions, using exported locking primitives. In particu‐
74 lar, a sequence such as:
75 flockfile(fileptr);
78 putc_unlocked('1', fileptr);
79 putc_unlocked('\n', fileptr);
80 fprintf(fileptr, "Line 2\n");
81 funlockfile(fileptr);
82 is permissible, and results in the text sequence:
84 1
87 Line 2
88 being printed without being interspersed with output from other
90 threads.
91 It would be wrong to have the standard names such as getc(), putc(),
93 and so on, map to the ``faster, but unsafe'' rather than the ``slower,
94 but safe'' versions. In either case, you would still want to inspect
95 all uses of getc(), putc(), and so on, by hand when converting existing
96 code. Choosing the safe bindings as the default, at least, results in
97 correct code and maintains the ``atomicity at the function'' invariant.
98 To do otherwise would introduce gratuitous synchronization errors into
99 converted code. Other routines that modify the stdio (FILE *) struc‐
100 tures or buffers are also safely synchronized.
101 Note that there is no need for functions of the form getc_locked(),
103 putc_locked(), and so on, since this is the functionality of getc(),
104 putc(), et al. It would be inappropriate to use a feature test macro
105 to switch a macro definition of getc() between getc_locked() and
106 getc_unlocked(), since the ISO C standard requires an actual function
107 to exist, a function whose behavior could not be changed by the feature
108 test macro. Also, providing both the xxx_locked() and xxx_unlocked()
109 forms leads to the confusion of whether the suffix describes the behav‐
110 ior of the function or the circumstances under which it should be used.
111 Three additional routines, flockfile(), ftrylockfile(), and funlock‐
113 file() (which may be macros), are provided to allow the user to delin‐
114 eate a sequence of I/O statements that are executed synchronously.
115 The ungetc() function is infrequently called relative to the other
117 functions/macros so no unlocked variation is needed.
118
120 None.
121
123 Section 2.5, Standard I/O Streams, flockfile(), getc(), getchar(),
124 putc(), putchar()
125 The Base Definitions volume of POSIX.1‐2017, <stdio.h>
127
129 Portions of this text are reprinted and reproduced in electronic form
130 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
131 table Operating System Interface (POSIX), The Open Group Base Specifi‐
132 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
133 Electrical and Electronics Engineers, Inc and The Open Group. In the
134 event of any discrepancy between this version and the original IEEE and
135 The Open Group Standard, the original IEEE and The Open Group Standard
136 is the referee document. The original Standard can be obtained online
137 at http://www.opengroup.org/unix/online.html .
138 Any typographical or formatting errors that appear in this page are
140 most likely to have been introduced during the conversion of the source
141 files to man page format. To report such errors, see https://www.ker‐
142 nel.org/doc/man-pages/reporting_bugs.html .
143IEEE/The Open Group 2017 GETC_UNLOCKED(3P)