NAME
flockfile(), ftrylockfile(), funlockfile() — explicit locking of streams within a multithread application
SYNOPSIS
#include <stdio.h>
void flockfile(FILE *stream);
int ftrylockfile(FILE *stream);
void funlockfile(FILE *stream);
DESCRIPTION
The
flockfile(),
ftrylockfile(),
and
funlockfile()
functions provide for explicit
application-level locking of streams.
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 behavior is undefined if a thread other than
the current owner calls the
funlockfile()
function.
Logically, there is a count associated with each stream.
This count is implicitly initialized to zero when the stream
is created.
The stream is unlocked when the count is zero.
When the count is positive, a single thread owns the stream.
When the
flockfile()
function is called, if the count is zero or if the count
is positive and the caller owns the stream, 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.
All POSIX.1 and C standard functions that reference
(FILE *)
objects
behave as if they use
flockfile()
and
funlockfile()
internally to obtain ownership of these
(FILE *)
objects.
RETURN VALUE
None for
flockfile()
and
funlockfile().
The function
ftrylockfile()
returns zero for success and nonzero to indicate that the lock cannot
be acquired.
Printable version
