ftrylockfile()

lock stdio (FILE *)object without blocking 

Function

SYNOPSIS

#include <stdio.h>

int ftrylockfile(FILE *file);

DESCRIPTION

The ftrylockfile() function provides explicit application-level locking of stdio (FILE *) objects. This function can be used by a thread to delineate a sequence of I/O statements that are to be executed as unit. ftrylockfile() is a non-blocking version of flockfile(); on successful return, the calling thread owns file.

Logically, there is a lock count associated with each (FILE *) object. This count is implicitly initialized to zero when the object is created. The object is unlocked when the count is zero. When the count is positive, a single thread owns the object. When ftrylockfile() is called, if the count is zero or if the count is positive and the caller owns the object, the count is incremented. Otherwise, ftrylockfile() fails, and the calling thread does not own the object. Each call to funlockfile() decrements the count. This allows matching (successful) calls to ftrylockfile() and funlockfile() to be nested.

All functions that reference (FILE *) objects behave as if they use flockfile() and funlockfile() internally to obtain ownership of these objects, unless the documentation for the function explicitly indicates that the function operates on an unlocked object.

PARAMETERS

file 

Points to the file object to be locked.

RETURN VALUES

On success, ftrylockfile() returns 0. If the lock cannot be obtained, a non-zero value is returned.

CONFORMANCE

POSIX.1 (1996).

MULTITHREAD SAFETY LEVEL

MT-Safe.

PORTING ISSUES

None.

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

SEE ALSO

Functions:
fclose(), fdopen(), flockfile(), fopen(), funlockfile(), getc_unlocked(), getchar_unlocked(), putc_unlocked(), putchar_unlocked()

PTC MKS Toolkit 10.5 Documentation Build 40.