# flockfile

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



           flockfile, ftrylockfile, funlockfile — stdio locking functions
    


## SYNOPSIS



           #include <stdio.h>
    
           void flockfile(FILE *_file_);
           int ftrylockfile(FILE *_file_);
           void funlockfile(FILE *_file_);
    


## DESCRIPTION



           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



           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



           No errors are defined.
    
           _The following sections are informative._
    


## EXAMPLES



           None.
    


## APPLICATION USAGE



           Applications using these functions may be subject to priority
           inversion, as discussed in the Base Definitions volume of
           POSIX.1‐2017, _Section 3.291_ , _Priority Inversion_.
    
           A call to _exit_() can block until locked streams are unlocked
           because a thread having ownership of a (**FILE** *) object blocks all
           function calls that reference that (**FILE** *) object (except those
           with names ending in _unlocked) from other threads, including
           calls to _exit_().
    


## RATIONALE



           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



           None.
    


* * *