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 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 IEEE Std 1003.1-2001, Section 3.285, 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 writers 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()  ,  putc_unlocked() , the Base Definitions volume of IEEE Std 1003.1-2001,
       <stdio.h>

COPYRIGHT

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