Open System Services Library Calls Reference Manual (G06.29+, H06.08+, J06.03+)

OSS Library Calls (e - f) ftrylockfile(3)
NAME
ftrylockfile - Allows a thread to acquire ownership of a stream if the stream is available
LIBRARY
H-series and J-series native Guardian processes: $SYSTEM.ZDLLnnn.ZCRTLDLL
32-bit H-series and J-series OSS processes: /G/system/zdllnnn/zcrtldll
64-bit H-series and J-series OSS processes: /G/system/zdllnnn/ycrtldll
SYNOPSIS
#include <stdio.h>
int ftrylockfile(
FILE ∗∗stream);
PARAMETERS
stream Points to the file structure of an open file.
DESCRIPTION
The ftrylockfile( ) function is used by a thread to acquire ownership of a stream if the stream is
available; ftrylockfile( ) is a non-blocking version of flockfile( ).
The ftrylockfile( ) function is used with the flockfile( ) and funlockfile( ) functions to provide for
explicit application-level locking of streams. These functions can be used by a thread to del-
ineate 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 stream; flockfile( ) is a
blocking version of ftrylockfile( ).
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 0
(zero) when the stream is created. The stream is unlocked when the count is 0 (zero). When the
count is positive, a single thread owns the stream. When the flockfile( ) function is called, if the
count is 0 (zero) or if the count is positive and the caller owns the stream, the count is incre-
mented. Otherwise, the calling thread is suspended while waiting for the count to return to 0
(zero). Each call to funlockfile( ) decrements the count. This behavior allows matching calls to
flockfile( ) (or successful calls to ftrylockfile( )) and funlockfile( ) to be nested.
All POSIX.1 and C standard functions that reference streams behave as if they use flockfile( ) and
funlockfile( ) internally to obtain ownership of streams.
RETURN VALUES
If successful, the ftrylockfile( ) function returns 0 (zero). If the lock cannot be acquired, a non-
zero value is returned.
RELATED INFORMATION
Functions: flockfile(3), funlockfile(3), getc_unlocked(3), getchar_unlocked(3),
putc_unlocked(3), putchar_unlocked(3).
STANDARDS CONFORMANCE
Interfaces documented on this reference page conform to the following industry standards:
• IEEE Std 1003.1-2004, POSIX System Application Program Interface
527187-017 Hewlett-Packard Company 2−199