1.\" $OpenBSD: flockfile.3,v 1.6 1999/07/07 10:50:05 aaron 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. These functions can be used by a thread to delineate a sequence 28of I/O statements that are to be executed as a unit. 29.Pp 30The 31.Fn flockfile 32function is used by a thread to acquire ownership of a 33.Ft "FILE *" 34object. 35.Pp 36The 37.Fn ftrylockfile 38function is used by a thread to acquire ownership of a 39.Ft "FILE *" 40object if the object is available; 41.Fn ftrylockfile 42is a non-blocking version of 43.Fn flockfile . 44.Pp 45The 46.Fn funlockfile 47function is used to relinquish the ownership granted to the thread. 48The behaviour is undefined if a thread other than the current owner calls the 49.Fn funlockfile 50function. 51.Pp 52Logically, there is a lock count associated with each 53.Ft "FILE *" 54object. This count is implicitly intialized to zero when the 55.Ft "FILE *" 56object is created. The 57.Ft "FILE *" 58object is unlocked when the count is zero. 59When the count is positive, a single thread owns the 60.Ft "FILE *" 61object. When the 62.Fn flockfile 63function is called, if the count is zero or if the count is positive and 64the caller owns the 65.Ft "FILE *" 66object, the count is incremented. 67Otherwise, the calling thread is suspended, waiting for the count to 68return to zero. 69Each call to 70.Fn funlockfile 71decrements the count. This allows matching calls to 72.Fn flockfile 73(or successful calls to 74.Fn ftrylockfile ) 75and 76.Fn funlockfile 77to be nested. 78.Pp 79Library functions that reference 80.Ft "FILE *" 81behave as if they use 82.Fn flockfile 83and 84.Fn funlockfile 85internally to obtain ownership of these 86.Ft "FILE *" 87objects. 88.Sh RETURN VALUES 89None for 90.Fn flockfile 91and 92.Fn funlockfile . 93The function 94.Fn ftrylock 95returns zero for success and non-zero to indicate that the lock cannot 96be acquired. 97.Sh ERRORS 98None. 99.Sh SEE ALSO 100.Xr getc_unlocked 3 , 101.Xr getchar_unlocked 3 , 102.Xr pthreads 3 , 103.Xr putc_unlocked 3 , 104.Xr putchar_unlocked 3 105.Sh STANDARDS 106.Fn flockfile , 107.Fn ftrylockfile 108and 109.Fn funlockfile 110conform to ISO/IEC 9945-1 ANSI/IEEE 111.Pq Dq Tn POSIX 112Std 1003.1c/D10. 113.\" Std 1003.1 Second Edition 1996-07-12. 114