The Single UNIX ® Specification, Version 2
Copyright © 1997 The Open Group

 NAME

flockfile, ftrylockfile, funlockfile - stdio locking functions

 SYNOPSIS



#include <stdio.h>

void flockfile(FILE *file);
int ftrylockfile(FILE *file);
void funlockfile(FILE *file);

 DESCRIPTION

The flockfile(), ftrylockfile() and funlockfile() functions provide for explicit application-level locking of stdio ( FILE *) objects. 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 behaviour is undefined if a thread other than the current owner calls the funlockfile() function.

Logically, there is a lock count associated with each ( FILE *) object. This count is implicitly initialised to zero when the ( FILE *) object is created. The ( FILE *) object is unlocked when the count is zero. When the count is positive, a single thread owns the ( FILE *) object. When the flockfile() function is called, if the count is zero or if the count is positive and the caller owns the ( FILE *) object, 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 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 non-zero to indicate that the lock cannot be acquired.

 ERRORS

No errors are defined.

 EXAMPLES

None.

 APPLICATION USAGE

Realtime applications may encounter priority inversion when using FILE locks. The problem occurs when a high priority thread "locks" a FILE that is about to be "unlocked" by a low priority thread, but the low priority thread is preempted by a medium priority thread. This scenario leads to priority inversion; a high priority thread is blocked by lower priority threads for an unlimited period of time. During system design, realtime programmers must take into account the possibility of this kind of priority inversion. They can deal with it in a number of ways, such as by having critical sections that are guarded by FILE locks execute at a high priority, so that a thread cannot be preempted while executing in its critical section.

 FUTURE DIRECTIONS

None.

 SEE ALSO

getc_unlocked(), getchar_unlocked(), putc_unlocked(), putchar_unlocked(), <stdio.h>.

DERIVATION

Derived from the POSIX Threads Extension (1003.1c-1995)

UNIX ® is a registered Trademark of The Open Group.
Copyright © 1997 The Open Group
[ Main Index | XSH | XCU | XBD | XCURSES | XNS ]