flockfile.3s (2010 09)

ManualsBrandsHP ManualsSoftwareHP-UX Manpages

ﬂockﬁle(3S) ﬂockﬁle(3S)

NAME

ﬂockﬁle( ), ftrylockﬁle( ), funlockﬁle( ) - 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 undeﬁned 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 sin-

gle 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 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.

HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1