flockfile, ftrylockfile, funlockfile - functions for locking standard input/output

Syntax	#include <stdio.h> void flockfile(FILE *file); int ftrylockfile(FILE *file); void funlockfile(FILE *file);
Description	The flockfile() and ftrylockfile() functions allow for the explicit locking of (FILE*) objects at the application level. The lock can be eliminated with funlockfile(). These functions can be used by a thread to represent a series of I/O statements that are to be executed as a unit. The flockfile() function is used by a thread to obtain access permission for a (FILE*) object. The ftrylockfile() function is used by a thread to obtain access permission for a (FILE*) object if the object is available; ftrylockfile() is a version of flockfile() that does not block the object. The funlockfile() function is used by a thread to give up the access permission it obtained. funlockfile() is ignored if the calling thread is not the owner of the (FILE*) object. It is logical to assign every (FILE*) object a lock counter. This counter is implicitly initialized to 0 when the (FILE*) object is created. The lock for the (FILE*) object is removed when the counter has the value 0. When the counter value is positive, then a single thread is the owner of the (FILE*) object. If the flockfile() function is called when the counter is 0 or contains a positive value and the caller is the owner of the (FILE*) object then the counter is incremented. Otherwise the calling thread is interrupted and waits until the counter is 0 again. Every funlockfile() call decrements the counter. This allows for nested flockfile() calls [or successful ftrylockfile() calls] and funlockfile() calls. All functions that point to (FILE*) objects behave as if they used flockfile() and funlockfile() to obtain access permission for these (FILE*) objects.
Return val.	flockfile() and funlockfile(): no return value ftrylock():
	0 !=0	if successful. if no lock can be activated.
Notes	In real time applications the use of FILE locks can result in the reversal of priorities. This problem arises when a thread with higher priority “locks” a FILE object that was just “unlocked” by a thread of lower priority, but the thread of lower priority is prematurely stopped by a thread of medium priority. This situation leads to a reversal of the priorities; a thread of higher priority is blocked by a thread of lower priority for an indefinite amount of time. Developers of real time applications must take the possibility of such reversals of priority into account when designing a system. They could take a series of actions to counteract such situations by having critical sections of code that are protected by FILE locks execute with a higher priority so that a thread cannot be stopped prematurely while executing a critical sections of code.
See also	getc_unlocked(), pthread_intro(), stdio().