Man Pages

flockfile(3p) - phpMan flockfile(3p) - phpMan

Command: man perldoc info search(apropos)  


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



PROLOG
       This manual page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may dif-
       fer (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 func-
       tions 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  avail-
       able; 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() inter-
       nally 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_try-
       lock().

       These  locks behave as if they are the same as those used internally by stdio for thread-safety. This both pro-
       vides thread-safety of these functions without requiring a second level of internal locking  and  allows  func-
       tions 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  cer-
       tain  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, Stan-
       dard  for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifica-
       tions 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 Stan-
       dard, 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 .



IEEE/The Open Group                  2003                        FLOCKFILE(3P)