PROLOG | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | RATIONALE | FUTURE DIRECTIONS | SEE ALSO | COPYRIGHT

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

PROLOG         top

       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         top

       getc_unlocked, getchar_unlocked, putc_unlocked, putchar_unlocked —
       stdio with explicit client locking

SYNOPSIS         top

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

       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.

       If getc_unlocked() or putc_unlocked() are implemented as macros they
       may evaluate stream more than once, so the stream argument should
       never be an expression with side-effects.

RETURN VALUE         top

       See getc(3p), getchar(3p), putc(3p), and putchar(3p).

ERRORS         top

       See getc(3p), getchar(3p), putc(3p), and putchar(3p).

       The following sections are informative.

EXAMPLES         top

       None.

APPLICATION USAGE         top

       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(c,*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         top

       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         top

       None.

SEE ALSO         top

       Section 2.5, Standard I/O Streams, flockfile(3p), getc(3p),
       getchar(3p), putc(3p), putchar(3p)

       The Base Definitions volume of POSIX.1‐2008, stdio.h(0p)

COPYRIGHT         top

       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information
       Technology -- Portable Operating System Interface (POSIX), The Open
       Group Base Specifications Issue 7, Copyright (C) 2013 by the
       Institute of Electrical and Electronics Engineers, Inc and The Open
       Group.  (This is POSIX.1-2008 with the 2013 Technical Corrigendum 1
       applied.) 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.unix.org/online.html .

       Any typographical or formatting errors that appear in this page are
       most likely to have been introduced during the conversion of the
       source files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .

IEEE/The Open Group                 2013                   GETC_UNLOCKED(3P)

Pages that refer to this page: stdio.h(0p)flockfile(3p)getchar_unlocked(3p)putchar_unlocked(3p)putc_unlocked(3p)