Unix/Linux Go Back    


Linux 2.6 - man page for flockfile (linux section 3posix)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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

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 funlock-
       file() 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 fun-
       lockfile() 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 orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003				     FLOCKFILE(P)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 08:30 AM.