# getc_unlocked

## 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 fully
           thread-safe manner. They shall be thread-safe when used within a
           scope protected by _flockfile_() (or _ftrylockfile_()) and
           _funlockfile_().  These functions can 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



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


## ERRORS



           See getc(3p), getchar(3p), putc(3p), and putchar(3p).
    
           _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_(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



           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.
    


* * *