Download raw body.
flockfile.3
On 2025-07-09, Ingo Schwarze wrote: > That part is almost OK schwarze@, see below inline for multiple > things that need to be fixed and multiple optional suggestions. Another go at this. Index: Makefile.inc =================================================================== RCS file: /home/cvs/src/lib/libc/stdio/Makefile.inc,v diff -u -p -r1.31 Makefile.inc --- Makefile.inc 12 Aug 2024 20:56:55 -0000 1.31 +++ Makefile.inc 9 Jul 2025 03:14:10 -0000 @@ -22,7 +22,8 @@ SRCS+= asprintf.c clrerr.c fclose.c fdop getdelim.c getline.c dprintf.c vdprintf.c \ fpending.c freadahead.c freading.c freadptr.c fseterr.c fwriting.c -MAN+= fclose.3 ferror.3 fflush.3 fgetln.3 fgets.3 fgetwln.3 fmemopen.3 \ +MAN+= fclose.3 ferror.3 fflush.3 fgetln.3 fgets.3 fgetwln.3 \ + flockfile.3 fmemopen.3 \ fopen.3 __fpending.3 fputs.3 fread.3 fseek.3 funopen.3 getc.3 \ open_memstream.3 perror.3 printf.3 putc.3 remove.3 scanf.3 setbuf.3 \ setvbuf.3 stdio.3 tmpnam.3 ungetc.3 fgetws.3 fputws.3 fwide.3 getwc.3 \ Index: flockfile.3 =================================================================== RCS file: flockfile.3 diff -N flockfile.3 --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ flockfile.3 11 Jul 2025 03:56:12 -0000 @@ -0,0 +1,74 @@ +.\" $OpenBSD$ +.\" +.\" Copyright (c) 2025 Ted Unangst <tedu@openbsd.org> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate$ +.Dt FLOCKFILE 3 +.Os +.Sh NAME +.Nm flockfile , +.Nm ftrylockfile , +.Nm funlockfile +.Nd locking for stdio streams +.Sh SYNOPSIS +.In stdio.h +.Ft void +.Fn flockfile "FILE *file" +.Ft int +.Fn ftrylockfile "FILE *file" +.Ft void +.Fn funlockfile "FILE *file" +.Sh DESCRIPTION +These functions provide application control over the locking of stdio streams. +.Fn flockfile +and +.Fn ftrylockfile +increment the lock count associated with +.Fa file +on behalf of the calling thread. +If another thread owns the lock, +.Fn flockfile +blocks until the lock becomes available, whereas +.Fn ftrylockfile +returns immediately and indicates failure. +.Pp +When called by a thread holding the lock, +.Fn funlockfile +decrements the lock count by one. +When the lock count reaches zero, the calling thread relinquishes +ownership of the lock. +.Pp +Functions such as +.Xr fread 3 +and +.Xr fprintf 3 +are internally thread safe by default, but additional locking may be used +to coordinate sequences of multiple calls. +.Sh RETURN VALUES +.Fn ftrylockfile +returns zero for success and non-zero for failure. +.Sh SEE ALSO +.Xr getc_unlocked 3 , +.Xr putc_unlocked 3 , +.Xr pthreads 3 +.Sh STANDARDS +These functions conform to +.St -p1003.1-2024 . +.Sh HISTORY +These functions have been available since +.Ox 2.5 . +.Sh CAVEATS +Reading from one stream can flush a different buffered output stream, +leading to deadlocks. Index: getc.3 =================================================================== RCS file: /home/cvs/src/lib/libc/stdio/getc.3,v diff -u -p -r1.17 getc.3 --- getc.3 28 Sep 2023 01:51:00 -0000 1.17 +++ getc.3 11 Jul 2025 03:59:35 -0000 @@ -38,6 +38,8 @@ .Nm fgetc , .Nm getc , .Nm getchar , +.Nm getc_unlocked , +.Nm getchar_unlocked , .Nm getw .Nd get next character or word from input stream .Sh SYNOPSIS @@ -49,6 +51,10 @@ .Ft int .Fn getchar "void" .Ft int +.Fn getc_unlocked "FILE *stream" +.Ft int +.Fn getchar_unlocked "void" +.Ft int .Fn getw "FILE *stream" .Sh DESCRIPTION The @@ -73,6 +79,15 @@ with the argument .Em stdin . .Pp The +.Fn getc_unlocked +and +.Fn getchar_unlocked +functions perform the same action, but do not obtain the stream lock. +They require that the stream first be locked with +.Xr flockfile 3 +for thread safe operation. +.Pp +The .Fn getw function obtains the next .Vt int @@ -99,6 +114,7 @@ until the condition is cleared with .Xr clearerr 3 . .Sh SEE ALSO .Xr ferror 3 , +.Xr flockfile 3 , .Xr fopen 3 , .Xr fread 3 , .Xr getwc 3 , @@ -112,6 +128,12 @@ and .Fn getchar functions conform to .St -ansiC . +The +.Fn getc_unlocked +and +.Fn getchar_unlocked +functions conform to +.St -p1003.1-2024 . .Sh HISTORY The .Fn getc @@ -126,6 +148,12 @@ and .Fn fgetc in .At v7 . +The +.Fn getc_unlocked +and +.Fn getchar_unlocked +functions have been available since +.Ox 2.5 . .Sh BUGS Since .Dv EOF Index: putc.3 =================================================================== RCS file: /home/cvs/src/lib/libc/stdio/putc.3,v diff -u -p -r1.14 putc.3 --- putc.3 11 Sep 2022 06:38:11 -0000 1.14 +++ putc.3 11 Jul 2025 03:59:50 -0000 @@ -38,6 +38,8 @@ .Nm fputc , .Nm putc , .Nm putchar , +.Nm putc_unlocked , +.Nm putchar_unlocked , .Nm putw .Nd output a character or word to a stream .Sh SYNOPSIS @@ -49,6 +51,10 @@ .Ft int .Fn putchar "int c" .Ft int +.Fn putc_unlocked "int c" "FILE *stream" +.Ft int +.Fn putchar_unlocked "int c" +.Ft int .Fn putw "int w" "FILE *stream" .Sh DESCRIPTION The @@ -77,6 +83,15 @@ with an output stream of .Em stdout . .Pp The +.Fn putc_unlocked +and +.Fn putchar_unlocked +functions perform the same action, but do not obtain the stream lock. +They require that the stream first be locked with +.Xr flockfile 3 +for thread safe operation. +.Pp +The .Fn putw function writes the specified .Vt int @@ -115,6 +130,7 @@ or .Xr realloc 3 . .Sh SEE ALSO .Xr ferror 3 , +.Xr flockfile 3 , .Xr fopen 3 , .Xr getc 3 , .Xr putwc 3 , @@ -127,6 +143,12 @@ and .Fn putchar , conform to .St -ansiC . +The +.Fn putc_unlocked +and +.Fn putchar_unlocked +functions conform to +.St -p1003.1-2024 . .Sh HISTORY The .Fn putc @@ -141,6 +163,12 @@ and .Fn fputc in .At v7 . +The +.Fn putc_unlocked +and +.Fn putchar_unlocked +functions have been available since +.Ox 2.5 . .Sh BUGS Since the size and byte order of an .Vt int
flockfile.3