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

NAME

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

SYNOPSIS

16       #include <stdio.h>
17
18       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

DESCRIPTION

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

RATIONALE

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
76
77           flockfile(fileptr);
78           putc_unlocked('1', fileptr);
79           putc_unlocked('\n', fileptr);
80           fprintf(fileptr, "Line 2\n");
81           funlockfile(fileptr);
82
83       is permissible, and results in the text sequence:
84
85
86           1
87           Line 2
88
89       being  printed  without  being  interspersed  with  output  from  other
90       threads.
91
92       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
102       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
112       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
116       The  ungetc()  function  is  infrequently  called relative to the other
117       functions/macros so no unlocked variation is needed.
118

FUTURE DIRECTIONS

120       None.
121

SEE ALSO

123       Section 2.5, Standard  I/O  Streams,  flockfile(),  getc(),  getchar(),
124       putc(), putchar()
125
126       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
139       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 .
143
144
145
146IEEE/The Open Group                  2017                    GETC_UNLOCKED(3P)
Impressum