HP-UX Reference (11i v1 00/12) - 3 Library Functions A-M (vol 6)
__________________________________________________________________________________________________________________________________________________________________________________________________
__________________________________________________________________________________________________________________________________________________________________________________________________
STANDARD Printed by: Nora Chuang [nchuang] STANDARD
/build/1111/BRICK/man3/!!!intro.3c
________________________________________________________________
___ ___
f
flockfile(3S) flockfile(3S)
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 funlock-
file()
to be nested.
All POSIX.1 and C standard functions that reference (FILE *) objects behave as if they use flock-
file()
and funlockfile() internally to obtain ownership of these
(FILE *) objects.
RETURN VALUE
None for
flockfile() and funlockfile(). The function
ftrylockfile() returns zero for suc-
cess and nonzero to indicate that the lock cannot be acquired.
Section 3−−244 − 1 − HP-UX Release 11i: December 2000
___
___