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‐2008, Section 3.287, Priority Inversion.

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.

SEE ALSO

       getc_unlocked()

       The Base Definitions volume of POSIX.1‐2008, Section 3.287, Priority Inversion, <stdio.h>

COPYRIGHT

       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 .