ftrylockfile man page on YellowDog

Man page or keyword search:  
man Server   18644 pages
apropos Keyword Search (all sections)
Output format
YellowDog logo
[printable version]

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 cur‐
       rent 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 inver‐
       sion,   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  pro‐
       vides  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  con‐
       sistent	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  pro‐
       tecting	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 .

IEEE/The Open Group		     2003			  FLOCKFILE(P)
[top]

List of man pages available for YellowDog

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net