Man Pages

getchar_unlocked(3p) - phpMan getchar_unlocked(3p) - phpMan

Command: man perldoc info search(apropos)  


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 dif-
       fer (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 man-
       ner. They may only safely be used within a scope protected by  flockfile()  (or  ftrylockfile())  and  funlock-
       file().   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 char-
       acter. 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, Stan-
       dard  for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifica-
       tions 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 Stan-
       dard, 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)