ftrylockfile man page on RedHat

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

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 differ (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 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(3P)
[top]

List of man pages available for RedHat

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