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
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

RETURN VALUE

37       See getc(), getchar(), putc(), and putchar().
38

ERRORS

40       See getc(), getchar(), putc(), and putchar().
41
42       The following sections are informative.
43

EXAMPLES

45       None.
46

APPLICATION USAGE

48       Since  they  may  be  implemented  as   macros,   getc_unlocked()   and
49       putc_unlocked()  may  treat  incorrectly  a  stream  argument with side
50       effects. In particular, getc_unlocked(*f++) and putc_unlocked(*f++)  do
51       not  necessarily work as expected. Therefore, use of these functions in
52       such situations should be preceded by the following statement as appro‐
53       priate:
54
55
56              #undef getc_unlocked
57              #undef putc_unlocked
58

RATIONALE

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

FUTURE DIRECTIONS

116       None.
117

SEE ALSO

119       getc(),  getchar(),  putc(),  putchar(), the Base Definitions volume of
120       IEEE Std 1003.1-2001, <stdio.h>
121
123       Portions of this text are reprinted and reproduced in  electronic  form
124       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
125       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
126       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
127       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
128       event of any discrepancy between this version and the original IEEE and
129       The Open Group Standard, the original IEEE and The Open Group  Standard
130       is  the  referee document. The original Standard can be obtained online
131       at http://www.opengroup.org/unix/online.html .
132
133
134
135IEEE/The Open Group                  2003                    GETC_UNLOCKED(3P)
Impressum