NAME
flockfile,
ftrylockfile, funlockfile
— application level locking of
stdio files
SYNOPSIS
#include
<stdio.h>
void
flockfile(FILE
*file);
int
ftrylockfile(FILE
*file);
void
funlockfile(FILE
*file);
DESCRIPTION
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
None for flockfile() and
funlockfile(). The function
ftrylockfile() returns zero for success and non-zero
to indicate that the lock cannot be acquired.
ERRORS
None.
SEE ALSO
getc_unlocked(3), getchar_unlocked(3), pthreads(3), putc_unlocked(3), putchar_unlocked(3)
STANDARDS
flockfile(),
ftrylockfile() and
funlockfile() conform to ISO/IEC 9945-1 ANSI/IEEE
(“POSIX”) Std 1003.1c/D10.