trusty (3) ftrylockfile.3posix.gz

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 .