NAME    [Toc]    [Back]

     flockfile, ftrylockfile,  funlockfile  -  application  level
locking of stdio
     files

SYNOPSIS    [Toc]    [Back]

     #include <stdio.h>

     void
     flockfile(FILE *file);

     int
     ftrylockfile(FILE *file);

     void
     funlockfile(FILE *file);

DESCRIPTION    [Toc]    [Back]

     The flockfile(), ftrylockfile(), and funlockfile() functions
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 to be executed as a unit.

     The flockfile() function is used by a thread to acquire ownership of a
     FILE * object.

     The  ftrylockfile()  function is used by a thread to acquire
ownership of a
     FILE * object if the object is available; ftrylockfile()  is
a non-blocking
 version of flockfile().

     The  funlockfile() function is used to relinquish the ownership granted to
     the thread.  The behaviour is undefined if  a  thread  other
than the current
 owner calls the funlockfile() function.

     Logically, 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 is
incremented.
     Otherwise,  the calling thread is suspended, waiting for the
count to return
 to zero.  Each call  to  funlockfile()  decrements  the
count.  This allows
 matching calls to flockfile() (or successful calls to
     ftrylockfile()) and funlockfile() to be nested.

     Library  functions  that  reference FILE * behave as if they
use flockfile()
     and funlockfile() internally to obtain  ownership  of  these
FILE * objects.

RETURN VALUES    [Toc]    [Back]

     None   for  flockfile()  and  funlockfile().   The  function
ftrylock() returns
     zero for success and non-zero to indicate that the lock cannot be acquired.

ERRORS    [Toc]    [Back]

     None.

SEE ALSO    [Toc]    [Back]

     getc_unlocked(3), getchar_unlocked(3), pthreads(3), putc_unlocked(3),
     putchar_unlocked(3)

STANDARDS    [Toc]    [Back]

     flockfile(), ftrylockfile()  and  funlockfile()  conform  to
ISO/IEC 9945-1
     ANSI/IEEE (``POSIX'') Std 1003.1c/D10.

OpenBSD      3.6                          August     20,     1998