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

FLOCKFILE(3P)             POSIX Programmer's Manual            FLOCKFILE(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

       flockfile, ftrylockfile, funlockfile — stdio locking functions

SYNOPSIS         top

       #include <stdio.h>

       void flockfile(FILE *file);
       int ftrylockfile(FILE *file);
       void funlockfile(FILE *file);

DESCRIPTION         top

       These functions shall provide for explicit application-level locking
       of stdio (FILE *) objects. These functions can be used by a thread to
       delineate a sequence of I/O statements that are executed as a unit.

       The flockfile() function shall acquire for a thread ownership of a
       (FILE *) object.

       The ftrylockfile() function shall acquire for a thread ownership of a
       (FILE *) object if the object is available; ftrylockfile() is a non-
       blocking version of flockfile().

       The funlockfile() function shall relinquish the ownership granted to
       the thread.  The behavior is undefined if a thread other than the
       current owner calls the funlockfile() function.

       The functions shall behave as if there is a lock count associated
       with each (FILE *) object. This count is implicitly initialized to
       zero when the (FILE *) object is created. The (FILE *) object is
       unlocked when the count is zero. When the count is positive, a single
       thread owns the (FILE *) object. When the flockfile() function is
       called, if the count is zero or if the count is positive and the
       caller owns the (FILE *) object, the count shall be incremented.
       Otherwise, the calling thread shall be suspended, waiting for the
       count to return to zero. Each call to funlockfile() shall decrement
       the count. This allows matching calls to flockfile() (or successful
       calls to ftrylockfile()) and funlockfile() to be nested.

       All functions that reference (FILE *) objects, except those with
       names ending in _unlocked, shall behave as if they use flockfile()
       and funlockfile() internally to obtain ownership of these (FILE *)
       objects.

RETURN VALUE         top

       None for flockfile() and funlockfile().

       The ftrylockfile() function shall return zero for success and non-
       zero to indicate that the lock cannot be acquired.

ERRORS         top

       No errors are defined.

       The following sections are informative.

EXAMPLES         top

       None.

APPLICATION USAGE         top

       Applications using these functions may be subject to priority
       inversion, as discussed in the Base Definitions volume of
       POSIX.1‐2008, Section 3.287, Priority Inversion.

RATIONALE         top

       The flockfile() and funlockfile() functions provide an orthogonal
       mutual-exclusion lock for each FILE.  The ftrylockfile() function
       provides a non-blocking attempt to acquire a file lock, analogous to
       pthread_mutex_trylock().

       These locks behave as if they are the same as those used internally
       by stdio for thread-safety.  This both provides thread-safety of
       these functions without requiring a second level of internal locking
       and allows functions in stdio to be implemented in terms of other
       stdio functions.

       Application developers and implementors should be aware that there
       are potential deadlock problems on FILE objects. For example, the
       line-buffered flushing semantics of stdio (requested via {_IOLBF})
       require that certain input operations sometimes cause the buffered
       contents of implementation-defined line-buffered output streams to be
       flushed. If two threads each hold the lock on the other's FILE,
       deadlock ensues. This type of deadlock can be avoided by acquiring
       FILE locks in a consistent order. In particular, the line-buffered
       output stream deadlock can typically be avoided by acquiring locks on
       input streams before locks on output streams if a thread would be
       acquiring both.

       In summary, threads sharing stdio streams with other threads can use
       flockfile() and funlockfile() to cause sequences of I/O performed by
       a single thread to be kept bundled. The only case where the use of
       flockfile() and funlockfile() is required is to provide a scope
       protecting uses of the *_unlocked functions/macros. This moves the
       cost/performance tradeoff to the optimal point.

FUTURE DIRECTIONS         top

       None.

SEE ALSO         top

       getc_unlocked(3p)

       The Base Definitions volume of POSIX.1‐2008, Section 3.287, Priority
       Inversion, 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                       FLOCKFILE(3P)

Pages that refer to this page: stdio.h(0p)ftrylockfile(3p)funlockfile(3p)getc_unlocked(3p)