1.\" $OpenBSD: flockfile.3,v 1.8 2003/02/18 13:14:43 jmc Exp $ 2.\" David Leonard <d@openbsd.org>, 1998. Public domain. 3.Dd August 20, 1998 4.Dt FLOCKFILE 3 5.Os 6.Sh NAME 7.Nm flockfile , 8.Nm ftrylockfile , 9.Nm funlockfile 10.Nd application level locking of stdio files 11.Sh SYNOPSIS 12.Fd #include <stdio.h> 13.Ft void 14.Fn flockfile "FILE *file" 15.Ft int 16.Fn ftrylockfile "FILE *file" 17.Ft void 18.Fn funlockfile "FILE *file" 19.Sh DESCRIPTION 20The 21.Fn flockfile , 22.Fn ftrylockfile , 23and 24.Fn funlockfile 25functions provide for explicit application-level locking of stdio 26.Ft "FILE *" 27objects. 28These functions can be used by a thread to delineate a sequence 29of I/O statements that are to be executed as a unit. 30.Pp 31The 32.Fn flockfile 33function is used by a thread to acquire ownership of a 34.Ft "FILE *" 35object. 36.Pp 37The 38.Fn ftrylockfile 39function is used by a thread to acquire ownership of a 40.Ft "FILE *" 41object if the object is available; 42.Fn ftrylockfile 43is a non-blocking version of 44.Fn flockfile . 45.Pp 46The 47.Fn funlockfile 48function is used to relinquish the ownership granted to the thread. 49The behaviour is undefined if a thread other than the current owner calls the 50.Fn funlockfile 51function. 52.Pp 53Logically, there is a lock count associated with each 54.Ft "FILE *" 55object. 56This count is implicitly initialized to zero when the 57.Ft "FILE *" 58object is created. 59The 60.Ft "FILE *" 61object is unlocked when the count is zero. 62When the count is positive, a single thread owns the 63.Ft "FILE *" 64object. 65When the 66.Fn flockfile 67function is called, if the count is zero or if the count is positive and 68the caller owns the 69.Ft "FILE *" 70object, the count is incremented. 71Otherwise, the calling thread is suspended, waiting for the count to 72return to zero. 73Each call to 74.Fn funlockfile 75decrements the count. 76This allows matching calls to 77.Fn flockfile 78(or successful calls to 79.Fn ftrylockfile ) 80and 81.Fn funlockfile 82to be nested. 83.Pp 84Library functions that reference 85.Ft "FILE *" 86behave as if they use 87.Fn flockfile 88and 89.Fn funlockfile 90internally to obtain ownership of these 91.Ft "FILE *" 92objects. 93.Sh RETURN VALUES 94None for 95.Fn flockfile 96and 97.Fn funlockfile . 98The function 99.Fn ftrylock 100returns zero for success and non-zero to indicate that the lock cannot 101be acquired. 102.Sh ERRORS 103None. 104.Sh SEE ALSO 105.Xr getc_unlocked 3 , 106.Xr getchar_unlocked 3 , 107.Xr pthreads 3 , 108.Xr putc_unlocked 3 , 109.Xr putchar_unlocked 3 110.Sh STANDARDS 111.Fn flockfile , 112.Fn ftrylockfile 113and 114.Fn funlockfile 115conform to ISO/IEC 9945-1 ANSI/IEEE 116.Pq Dq Tn POSIX 117Std 1003.1c/D10. 118.\" Std 1003.1 Second Edition 1996-07-12. 119