Hello Ted,

Ted Unangst wrote on Tue, Jul 08, 2025 at 11:30:44PM -0400:

> Here's a new man page for flockfile.3 to be placed in libc/stdio.

That part is almost OK schwarze@, see below inline for multiple
things that need to be fixed and multiple optional suggestions.

Don't forget removing flockfile.3 from libpthread/man/Makefile.inc
at the same time as adding flockfile.3 to libc/stdio/Makefile.inc,
and removing getc_unlocked.3 and putc_unlocked.3
from libpthread/man/Makefile.inc at the same time as adding them
to getc.3 and putc.3.

> Also, a diff for the getc.3 and putc.3 for the unlocked functions.

This part is not yet OK; you forgot the NAME sections, somewhat like

 .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

and similarly for putc.3.

If you want, you can add a sentence to HISTORY:

  .Pp
  .Fn getc_unlocked
  and
  .Fn getchar_unlocked
  have been avaolable since
  .Ox 2.5 .

and similarly for putc.3.

Yours,
  Ingo


> .\" $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
> increments the lock count associated with
> .Fa file ,
> blocking until the lock is available.
> .Fn ftrylockfile
> does the same but will not block if another thread owns the lock.

I think a more direct wording is possible, like so:

.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.

This is merely a suggestion, your wording is OK, too.

> .Pp
> .Fn funlockfile
> decrements the lock count by one.

I think this is not quite correct: if the calling thread does not own
the lock, nothing is decremented.  I think something like this is
needed:

If
.Fa file
is locked by the calling thread,
.Fn funlockfile
decrements the lock count by one; otherwise, it has no effect.
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 ERRORS
> None.

I think the whole ERRORS section should be deleted.
We normally document what a function does, not what it does not do.

> .Sh SEE ALSO
> .Xr getc_unlocked ,
> .Xr putc_unlocked ,

On these two lines, you have to add  s/,$/3 ,/ .

> .Xr pthreads 3

And then you also have to sort alphabetically, i.e. pthreads before putc.

> .Sh STANDARDS
> These functions conform to
> .St -p1003.1-2024 .

I suggest adding something like the following here:

.Pp
.Fn funlockfile
having no effect when the calling thread does not own the lock
is an extension to the standard.

If you want, you can be even more explicit and add another sentence:

In that case, the standard permits undefined behaviour.

These are suggestions, not conditions.

> .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: 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: 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	9 Jul 2025 03:25:14 -0000
> @@ -49,6 +49,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 +77,14 @@ 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

That statement seems too strong to me.  Shouldn't this read:

  If more than one thread uses the stream, they require...

A scenario of a multi-threaded application where a certain file
in only accessed by a certain thread seems realistic to me,
and in that case, the difference matters.

> +.Xr flockfile 3 .
> +.Pp
> +The
>  .Fn getw
>  function obtains the next
>  .Vt int
> @@ -99,6 +111,7 @@ until the condition is cleared with
>  .Xr clearerr 3 .
>  .Sh SEE ALSO
>  .Xr ferror 3 ,
> +.Xr flockfile ,

Again, s/,$/3 ,/ .

>  .Xr fopen 3 ,
>  .Xr fread 3 ,
>  .Xr getwc 3 ,
> @@ -112,6 +125,12 @@ and
>  .Fn getchar
>  functions conform to
>  .St -ansiC .
> +The
> +.Fn getc_unlocked
> +and
> +.Fn getchar_unlocked
> +conform to

A word is missing here:

  functions conform to

> +.St -p1003.1-2024 .
>  .Sh HISTORY
>  The
>  .Fn getc
> 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	9 Jul 2025 03:24:34 -0000
> @@ -49,6 +49,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 +81,14 @@ 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

Again, seems too strong to me.

> +.Xr flockfile 3 .
> +.Pp
> +The
>  .Fn putw
>  function writes the specified
>  .Vt int
> @@ -115,6 +127,7 @@ or
>  .Xr realloc 3 .
>  .Sh SEE ALSO
>  .Xr ferror 3 ,
> +.Xr flockfile ,

Again, s/,$/3 ,/ .

>  .Xr fopen 3 ,
>  .Xr getc 3 ,
>  .Xr putwc 3 ,
> @@ -127,6 +140,12 @@ and
>  .Fn putchar ,
>  conform to
>  .St -ansiC .
> +The
> +.Fn putc_unlocked
> +and
> +.Fn putchar_unlocked
> +conform to

Again,

  functions conform to

> +.St -p1003.1-2024 .
>  .Sh HISTORY
>  The
>  .Fn putc