1GETC_UNLOCKED(3P)          POSIX Programmer's Manual         GETC_UNLOCKED(3P)
2
3
4

PROLOG

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
11

NAME

13       getc_unlocked,  getchar_unlocked,  putc_unlocked,  putchar_unlocked   —
14       stdio with explicit client locking
15

SYNOPSIS

17       #include <stdio.h>
18
19       int getc_unlocked(FILE *stream);
20       int getchar_unlocked(void);
21       int putc_unlocked(int c, FILE *stream);
22       int putchar_unlocked(int c);
23

DESCRIPTION

25       Versions  of  the  functions  getc(),  getchar(), putc(), and putchar()
26       respectively      named      getc_unlocked(),       getchar_unlocked(),
27       putc_unlocked(),  and  putchar_unlocked()  shall  be provided which are
28       functionally equivalent to the original versions,  with  the  exception
29       that  they  are not required to be implemented in a thread-safe manner.
30       They may only safely be used within a scope  protected  by  flockfile()
31       (or  ftrylockfile())  and funlockfile().  These functions may safely be
32       used in a multi-threaded program if and only if they are  called  while
33       the  invoking  thread  owns the (FILE *) object, as is the case after a
34       successful call to the flockfile() or ftrylockfile() functions.
35
36       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

RETURN VALUE

41       See getc(), getchar(), putc(), and putchar().
42

ERRORS

44       See getc(), getchar(), putc(), and putchar().
45
46       The following sections are informative.
47

EXAMPLES

49       None.
50

APPLICATION USAGE

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
59           #undef getc_unlocked
60           #undef putc_unlocked
61

RATIONALE

63       Some  I/O functions are typically implemented as macros for performance
64       reasons (for example, putc() and getc()).  For safety, they need to  be
65       synchronized,  but  it  is  often too expensive to synchronize on every
66       character. Nevertheless, it was felt that the safety concerns were more
67       important;  consequently,  the getc(), getchar(), putc(), and putchar()
68       functions are required to be thread-safe.  However,  unlocked  versions
69       are also provided with names that clearly indicate the unsafe nature of
70       their operation but can be used to exploit  their  higher  performance.
71       These  unlocked  versions  can  be  safely  used only within explicitly
72       locked program regions, using exported locking primitives. In  particu‐
73       lar, a sequence such as:
74
75           flockfile(fileptr);
76           putc_unlocked('1', fileptr);
77           putc_unlocked('\n', fileptr);
78           fprintf(fileptr, "Line 2\n");
79           funlockfile(fileptr);
80
81       is permissible, and results in the text sequence:
82
83           1
84           Line 2
85
86       being  printed  without  being  interspersed  with  output  from  other
87       threads.
88
89       It would be wrong to have the standard names such  as  getc(),  putc(),
90       and  so on, map to the ``faster, but unsafe'' rather than the ``slower,
91       but safe'' versions. In either case, you would still  want  to  inspect
92       all uses of getc(), putc(), and so on, by hand when converting existing
93       code. Choosing the safe bindings as the default, at least,  results  in
94       correct code and maintains the ``atomicity at the function'' invariant.
95       To do otherwise would introduce gratuitous synchronization errors  into
96       converted  code.   Other routines that modify the stdio (FILE *) struc‐
97       tures or buffers are also safely synchronized.
98
99       Note that there is no need for functions  of  the  form  getc_locked(),
100       putc_locked(),  and  so  on, since this is the functionality of getc(),
101       putc(), et al.  It would be inappropriate to use a feature  test  macro
102       to  switch  a  macro  definition  of  getc()  between getc_locked() and
103       getc_unlocked(), since the ISO C standard requires an  actual  function
104       to exist, a function whose behavior could not be changed by the feature
105       test macro. Also, providing both the  xxx_locked()  and  xxx_unlocked()
106       forms leads to the confusion of whether the suffix describes the behav‐
107       ior of the function or the circumstances under which it should be used.
108
109       Three additional routines, flockfile(),  ftrylockfile(),  and  funlock‐
110       file()  (which may be macros), are provided to allow the user to delin‐
111       eate a sequence of I/O statements that are executed synchronously.
112
113       The ungetc() function is infrequently  called  relative  to  the  other
114       functions/macros so no unlocked variation is needed.
115

FUTURE DIRECTIONS

117       None.
118

SEE ALSO

120       Section  2.5,  Standard  I/O  Streams,  flockfile(), getc(), getchar(),
121       putc(), putchar()
122
123       The Base Definitions volume of POSIX.1‐2008, <stdio.h>
124
126       Portions of this text are reprinted and reproduced in  electronic  form
127       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
128       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
129       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
130       cal and Electronics Engineers,  Inc  and  The  Open  Group.   (This  is
131       POSIX.1-2008  with  the  2013  Technical Corrigendum 1 applied.) In the
132       event of any discrepancy between this version and the original IEEE and
133       The  Open Group Standard, the original IEEE and The Open Group Standard
134       is the referee document. The original Standard can be  obtained  online
135       at http://www.unix.org/online.html .
136
137       Any  typographical  or  formatting  errors that appear in this page are
138       most likely to have been introduced during the conversion of the source
139       files  to  man page format. To report such errors, see https://www.ker
140       nel.org/doc/man-pages/reporting_bugs.html .
141
142
143
144IEEE/The Open Group                  2013                    GETC_UNLOCKED(3P)
Impressum