huschi.net

GETC_UNLOCKED(3P)          POSIX Programmer's Manual         GETC_UNLOCKED(3P)

PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
       implementation of this interface may differ (consult the  corresponding
       Linux  manual page for details of Linux behavior), or the interface may
       not be implemented on Linux.
NAME
       getc_unlocked,  getchar_unlocked,  putc_unlocked,  putchar_unlocked   -
       stdio with explicit client locking
SYNOPSIS
       #include <stdio.h>
       int getc_unlocked(FILE *stream);
       int getchar_unlocked(void);
       int putc_unlocked(int c, FILE *stream);
       int putchar_unlocked(int c);

DESCRIPTION
       Versions  of  the  functions  getc(),  getchar(), putc(), and putchar()
       respectively      named      getc_unlocked(),       getchar_unlocked(),
       putc_unlocked(),  and  putchar_unlocked()  shall  be provided which are
       functionally equivalent to the original versions,  with  the  exception
       that  they  are not required to be implemented in a thread-safe manner.
       They may only safely be used within a scope  protected  by  flockfile()
       (or  ftrylockfile())  and funlockfile().  These functions may safely be
       used in a multi-threaded program if and only if they are  called  while
       the  invoking  thread owns the ( FILE *) object, as is the case after a
       successful call to the flockfile() or ftrylockfile() functions.
RETURN VALUE
       See getc(), getchar(), putc(), and putchar().
ERRORS
       See getc(), getchar(), putc(), and putchar().
       The following sections are informative.
EXAMPLES
       None.
APPLICATION USAGE
       Since  they  may  be  implemented  as   macros,   getc_unlocked()   and
       putc_unlocked()  may  treat  incorrectly  a  stream  argument with side
       effects. In particular, getc_unlocked(*f++) and putc_unlocked(*f++)  do
       not  necessarily work as expected. Therefore, use of these functions in
       such situations should be preceded by the following statement as appro-
       priate:

              #undef getc_unlocked
              #undef putc_unlocked
RATIONALE
       Some  I/O functions are typically implemented as macros for performance
       reasons (for example, putc() and getc()). For safety, they need  to  be
       synchronized,  but  it  is  often too expensive to synchronize on every
       character. Nevertheless, it was felt that the safety concerns were more
       important;  consequently,  the getc(), getchar(), putc(), and putchar()
       functions are required to be thread-safe.  However,  unlocked  versions
       are also provided with names that clearly indicate the unsafe nature of
       their operation but can be used to exploit  their  higher  performance.
       These  unlocked  versions  can  be  safely  used only within explicitly
       locked program regions, using exported locking primitives. In  particu-
       lar, a sequence such as:

              flockfile(fileptr);
              putc_unlocked('1', fileptr);
              putc_unlocked('\n', fileptr);
              fprintf(fileptr, "Line 2\n");
              funlockfile(fileptr);
       is permissible, and results in the text sequence:

              1
              Line 2
       being  printed  without  being  interspersed  with  output  from  other
       threads.
       It would be wrong to have the standard names such  as  getc(),  putc(),
       and so on, map to the "faster, but unsafe" rather than the "slower, but
       safe'' versions. In either case, you would still want  to  inspect  all
       uses  of  getc(),  putc(),  and so on, by hand when converting existing
       code. Choosing the safe bindings as the default, at least,  results  in
       correct  code  and maintains the "atomicity at the function" invariant.
       To do otherwise would introduce gratuitous synchronization errors  into
       converted  code.  Other routines that modify the stdio ( FILE *) struc-
       tures or buffers are also safely synchronized.
       Note that there is no need for functions  of  the  form  getc_locked(),
       putc_locked(),  and  so  on, since this is the functionality of getc(),
       putc(), et al. It would be inappropriate to use a feature test macro to
       switch   a   macro  definition  of  getc()  between  getc_locked()  and
       getc_unlocked(), since the ISO C standard requires an  actual  function
       to exist, a function whose behavior could not be changed by the feature
       test macro. Also, providing both the  xxx_locked()  and  xxx_unlocked()
       forms leads to the confusion of whether the suffix describes the behav-
       ior of the function or the circumstances under which it should be used.
       Three additional routines, flockfile(),  ftrylockfile(),  and  funlock-
       file()  (which may be macros), are provided to allow the user to delin-
       eate a sequence of I/O statements that are executed synchronously.
       The ungetc() function is infrequently  called  relative  to  the  other
       functions/macros so no unlocked variation is needed.
FUTURE DIRECTIONS
       None.
SEE ALSO
       getc(),  getchar(),  putc(),  putchar(), the Base Definitions volume of
       IEEE Std 1003.1-2001, <stdio.h>
COPYRIGHT
       Portions of this text are reprinted and reproduced in  electronic  form
       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
       event of any discrepancy between this version and the original IEEE and
       The Open Group Standard, the original IEEE and The Open Group  Standard
       is  the  referee document. The original Standard can be obtained online
       at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group                  2003                    GETC_UNLOCKED(3P)