jcs.org
jcs's openbsd hax
openbsd
1.\" $OpenBSD: flockfile.3,v 1.1 2025/07/25 18:27:57 tedu Exp $
2.\"
3.\" Copyright (c) 2025 Ted Unangst <tedu@openbsd.org>
4.\"
5.\" Permission to use, copy, modify, and distribute this software for any
6.\" purpose with or without fee is hereby granted, provided that the above
7.\" copyright notice and this permission notice appear in all copies.
8.\"
9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16.\"
17.Dd $Mdocdate: July 25 2025 $
18.Dt FLOCKFILE 3
19.Os
20.Sh NAME
21.Nm flockfile ,
22.Nm ftrylockfile ,
23.Nm funlockfile
24.Nd locking for stdio streams
25.Sh SYNOPSIS
26.In stdio.h
27.Ft void
28.Fn flockfile "FILE *file"
29.Ft int
30.Fn ftrylockfile "FILE *file"
31.Ft void
32.Fn funlockfile "FILE *file"
33.Sh DESCRIPTION
34These functions provide application control over the locking of stdio streams.
35.Fn flockfile
36and
37.Fn ftrylockfile
38increment the lock count associated with
39.Fa file
40on behalf of the calling thread.
41If another thread owns the lock,
42.Fn flockfile
43blocks until the lock becomes available, whereas
44.Fn ftrylockfile
45returns immediately and indicates failure.
46.Pp
47When called by a thread holding the lock,
48.Fn funlockfile
49decrements the lock count by one.
50When the lock count reaches zero, the calling thread relinquishes
51ownership of the lock.
52.Pp
53Functions such as
54.Xr fread 3
55and
56.Xr fprintf 3
57are internally thread safe by default, but additional locking may be used
58to coordinate sequences of multiple calls.
59.Sh RETURN VALUES
60.Fn ftrylockfile
61returns zero for success and non-zero for failure.
62.Sh SEE ALSO
63.Xr getc_unlocked 3 ,
64.Xr pthreads 3 ,
65.Xr putc_unlocked 3
66.Sh STANDARDS
67These functions conform to
68.St -p1003.1-2024 .
69.Sh HISTORY
70These functions have been available since
71.Ox 2.5 .
72.Sh CAVEATS
73Reading from one stream can flush a different buffered output stream,
74leading to deadlocks.