14d844c09STim J. Robbins.\" Copyright (c) 2003 Tim J. Robbins 24d844c09STim J. Robbins.\" All rights reserved. 34d844c09STim J. Robbins.\" 44d844c09STim J. Robbins.\" Redistribution and use in source and binary forms, with or without 54d844c09STim J. Robbins.\" modification, are permitted provided that the following conditions 64d844c09STim J. Robbins.\" are met: 74d844c09STim J. Robbins.\" 1. Redistributions of source code must retain the above copyright 84d844c09STim J. Robbins.\" notice, this list of conditions and the following disclaimer. 94d844c09STim J. Robbins.\" 2. Redistributions in binary form must reproduce the above copyright 104d844c09STim J. Robbins.\" notice, this list of conditions and the following disclaimer in the 114d844c09STim J. Robbins.\" documentation and/or other materials provided with the distribution. 124d844c09STim J. Robbins.\" 134d844c09STim J. Robbins.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 144d844c09STim J. Robbins.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 154d844c09STim J. Robbins.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 164d844c09STim J. Robbins.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 174d844c09STim J. Robbins.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 184d844c09STim J. Robbins.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 194d844c09STim J. Robbins.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 204d844c09STim J. Robbins.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 214d844c09STim J. Robbins.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 224d844c09STim J. Robbins.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 234d844c09STim J. Robbins.\" SUCH DAMAGE. 244d844c09STim J. Robbins.\" 254d844c09STim J. Robbins.\" $FreeBSD$ 264d844c09STim J. Robbins.\" 274d844c09STim J. Robbins.Dd January 10, 2003 284d844c09STim J. Robbins.Dt FLOCKFILE 3 294d844c09STim J. Robbins.Os 304d844c09STim J. Robbins.Sh NAME 314d844c09STim J. Robbins.Nm flockfile , 324d844c09STim J. Robbins.Nm ftrylockfile , 334d844c09STim J. Robbins.Nm funlockfile 344d844c09STim J. Robbins.Nd "stdio locking functions" 354d844c09STim J. Robbins.Sh LIBRARY 364d844c09STim J. Robbins.Lb libc 374d844c09STim J. Robbins.Sh SYNOPSIS 384d844c09STim J. Robbins.In stdio.h 394d844c09STim J. Robbins.Ft void 404d844c09STim J. Robbins.Fn flockfile "FILE *stream" 414d844c09STim J. Robbins.Ft int 424d844c09STim J. Robbins.Fn ftrylockfile "FILE *stream" 434d844c09STim J. Robbins.Ft void 444d844c09STim J. Robbins.Fn funlockfile "FILE *stream" 454d844c09STim J. Robbins.Sh DESCRIPTION 464d844c09STim J. RobbinsThese functions provide explicit application-level locking of stdio streams. 474d844c09STim J. RobbinsThey can be used to avoid output from multiple threads being interspersed, 48d2b9b6b1SAlfred Perlsteininput being dispersed among multiple readers, and to avoid the overhead 494d844c09STim J. Robbinsof locking the stream for each operation. 504d844c09STim J. Robbins.Pp 514d844c09STim J. RobbinsThe 524d844c09STim J. Robbins.Fn flockfile 534d844c09STim J. Robbinsfunction acquires an exclusive lock on the specified stream. 544d844c09STim J. RobbinsIf another thread has already locked the stream, 554d844c09STim J. Robbins.Fn flockfile 564d844c09STim J. Robbinswill block until the lock is released. 574d844c09STim J. Robbins.Pp 584d844c09STim J. RobbinsThe 594d844c09STim J. Robbins.Fn ftrylockfile 604d844c09STim J. Robbinsfunction is a non-blocking version of 614d844c09STim J. Robbins.Fn flockfile ; 624d844c09STim J. Robbinsif the lock cannot be acquired immediately, 634d844c09STim J. Robbins.Fn ftrylockfile 644d844c09STim J. Robbinsreturns non-zero instead of blocking. 654d844c09STim J. Robbins.Pp 664d844c09STim J. RobbinsThe 674d844c09STim J. Robbins.Fn funlockfile 684d844c09STim J. Robbinsfunction releases the lock on a stream acquired by an earlier call to 694d844c09STim J. Robbins.Fn flockfile 704d844c09STim J. Robbinsor 714d844c09STim J. Robbins.Fn ftrylockfile . 724d844c09STim J. Robbins.Pp 734d844c09STim J. RobbinsThese functions behave as if there is a lock count associated 744d844c09STim J. Robbinswith each stream. 754d844c09STim J. RobbinsEach time 764d844c09STim J. Robbins.Fn flockfile 774d844c09STim J. Robbinsis called on the stream, the count is incremented, 784d844c09STim J. Robbinsand each time 794d844c09STim J. Robbins.Fn funlockfile 804d844c09STim J. Robbinsis called on the stream, the count is decremented. 814d844c09STim J. RobbinsThe lock is only actually released when the count reaches zero. 824d844c09STim J. Robbins.Sh RETURN VALUES 834d844c09STim J. RobbinsThe 844d844c09STim J. Robbins.Fn flockfile 854d844c09STim J. Robbinsand 864d844c09STim J. Robbins.Fn funlockfile 874d844c09STim J. Robbinsfunctions return no value. 884d844c09STim J. Robbins.Pp 894d844c09STim J. RobbinsThe 904d844c09STim J. Robbins.Fn ftrylockfile 9183bb3b49STim J. Robbinsfunction 924d844c09STim J. Robbinsreturns zero if the stream was successfully locked, 934d844c09STim J. Robbinsnon-zero otherwise. 944d844c09STim J. Robbins.Sh SEE ALSO 954d844c09STim J. Robbins.Xr getc_unlocked 3 , 964d844c09STim J. Robbins.Xr putc_unlocked 3 974d844c09STim J. Robbins.Sh STANDARDS 984d844c09STim J. RobbinsThe 994d844c09STim J. Robbins.Fn flockfile , 1004d844c09STim J. Robbins.Fn ftrylockfile 1014d844c09STim J. Robbinsand 1024d844c09STim J. Robbins.Fn funlockfile 1034d844c09STim J. Robbinsfunctions conform to 1044d844c09STim J. Robbins.St -p1003.1-2001 . 105