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

              #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 particular, 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 *) structures 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 behavior of the function or the circumstances under which it should be used.

       Three  additional  routines,  flockfile(),  ftrylockfile(),  and funlockfile() (which may be macros), are
       provided to allow the user to delineate 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(P)