FLOCKFILE(3)               POSIX Programmer's Manual              FLOCKFILE(3)



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.

NNAAMMEE
       flockfile, ftrylockfile, funlockfile -- stdio locking functions

SSYYNNOOPPSSIISS
       #include <stdio.h>

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

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

       The _f_l_o_c_k_f_i_l_e() function shall acquire for a thread ownership of a
       (FFIILLEE **) object.

       The _f_t_r_y_l_o_c_k_f_i_l_e() function shall acquire for a thread ownership of a
       (FFIILLEE **) object if the object is available; _f_t_r_y_l_o_c_k_f_i_l_e() is a non-
       blocking version of _f_l_o_c_k_f_i_l_e().

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

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

       All functions that reference (FFIILLEE **) objects, except those with names
       ending in ___u_n_l_o_c_k_e_d, shall behave as if they use _f_l_o_c_k_f_i_l_e() and
       _f_u_n_l_o_c_k_f_i_l_e() internally to obtain ownership of these (FFIILLEE **) objects.

RREETTUURRNN VVAALLUUEE
       None for _f_l_o_c_k_f_i_l_e() and _f_u_n_l_o_c_k_f_i_l_e().

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

EERRRROORRSS
       No errors are defined.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
       None.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       Applications using these functions may be subject to priority
       inversion, as discussed in the Base Definitions volume of POSIX.1-2017,
       _S_e_c_t_i_o_n _3_._2_9_1, _P_r_i_o_r_i_t_y _I_n_v_e_r_s_i_o_n.

       A call to _e_x_i_t() can block until locked streams are unlocked because a
       thread having ownership of a (FFIILLEE*) object blocks all function calls
       that reference that (FFIILLEE*) object (except those with names ending in
       _unlocked) from other threads, including calls to _e_x_i_t().

RRAATTIIOONNAALLEE
       The _f_l_o_c_k_f_i_l_e() and _f_u_n_l_o_c_k_f_i_l_e() functions provide an orthogonal
       mutual-exclusion lock for each FFIILLEE.  The _f_t_r_y_l_o_c_k_f_i_l_e() function
       provides a non-blocking attempt to acquire a file lock, analogous to
       _p_t_h_r_e_a_d___m_u_t_e_x___t_r_y_l_o_c_k().

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

       Application developers and implementors should be aware that there are
       potential deadlock problems on FFIILLEE objects. For example, the line-
       buffered flushing semantics of _s_t_d_i_o (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 FFIILLEE, deadlock ensues.
       This type of deadlock can be avoided by acquiring FFIILLEE 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 _s_t_d_i_o streams with other threads can use
       _f_l_o_c_k_f_i_l_e() and _f_u_n_l_o_c_k_f_i_l_e() to cause sequences of I/O performed by a
       single thread to be kept bundled. The only case where the use of
       _f_l_o_c_k_f_i_l_e() and _f_u_n_l_o_c_k_f_i_l_e() is required is to provide a scope
       protecting uses of the _*___u_n_l_o_c_k_e_d functions/macros. This moves the
       cost/performance tradeoff to the optimal point.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _e_x_i_t(), _g_e_t_c___u_n_l_o_c_k_e_d()

       The Base Definitions volume of POSIX.1-2017, _S_e_c_t_i_o_n _3_._2_9_1, _P_r_i_o_r_i_t_y
       _I_n_v_e_r_s_i_o_n, <<ssttddiioo..hh>>

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1-2017, Standard for Information Technology --
       Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, 2018 Edition, Copyright (C) 2018 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 Standard, 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 .

       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                  2017                         FLOCKFILE(3)
