From cbee408df14fe0f5540442d4fbbc2b2cd4c8df9d Mon Sep 17 00:00:00 2001
From: "Tim J. Robbins" <tjr@FreeBSD.org>
Date: Fri, 10 Jan 2003 04:56:20 +0000
Subject: [PATCH] Document getc_unlocked(), getchar_unlocked(),
 putc_unlocked(), and putchar_unlocked().

---
 lib/libc/stdio/Makefile.inc |  6 ++++--
 lib/libc/stdio/getc.3       | 32 ++++++++++++++++++++++++++++++-
 lib/libc/stdio/putc.3       | 38 +++++++++++++++++++++++++++++++++----
 3 files changed, 69 insertions(+), 7 deletions(-)

diff --git a/lib/libc/stdio/Makefile.inc b/lib/libc/stdio/Makefile.inc
index 204c52ee336f..74db5e31a722 100644
--- a/lib/libc/stdio/Makefile.inc
+++ b/lib/libc/stdio/Makefile.inc
@@ -36,7 +36,8 @@ MLINKS+=fread.3 fwrite.3
 MLINKS+=fseek.3 fgetpos.3 fseek.3 fseeko.3 fseek.3 fsetpos.3 fseek.3 ftell.3 \
 	fseek.3 ftello.3 fseek.3 rewind.3
 MLINKS+=funopen.3 fropen.3 funopen.3 fwopen.3
-MLINKS+=getc.3 fgetc.3 getc.3 getchar.3 getc.3 getw.3
+MLINKS+=getc.3 fgetc.3 getc.3 getc_unlocked.3 getc.3 getchar.3 \
+	getc.3 getchar_unlocked.3 getc.3 getw.3
 MLINKS+=getwc.3 fgetwc.3 getwc.3 getwchar.3
 MLINKS+=mktemp.3 mkdtemp.3 mktemp.3 mkstemp.3 mktemp.3 mkstemps.3
 MLINKS+=printf.3 asprintf.3 printf.3 fprintf.3 \
@@ -44,7 +45,8 @@ MLINKS+=printf.3 asprintf.3 printf.3 fprintf.3 \
 	printf.3 vasprintf.3 \
 	printf.3 vfprintf.3 printf.3 vprintf.3 printf.3 vsnprintf.3 \
 	printf.3 vsprintf.3
-MLINKS+=putc.3 fputc.3 putc.3 putchar.3 putc.3 putw.3
+MLINKS+=putc.3 fputc.3 putc.3 putc_unlocked.3 putc.3 putchar.3 \
+	putc.3 putchar_unlocked.3 putc.3 putw.3
 MLINKS+=putwc.3 fputwc.3 putwc.3 putwchar.3
 MLINKS+=scanf.3 fscanf.3 scanf.3 sscanf.3 scanf.3 vfscanf.3 scanf.3 vscanf.3 \
 	scanf.3 vsscanf.3
diff --git a/lib/libc/stdio/getc.3 b/lib/libc/stdio/getc.3
index a3549fd3b0ee..89cc6de34633 100644
--- a/lib/libc/stdio/getc.3
+++ b/lib/libc/stdio/getc.3
@@ -36,13 +36,15 @@
 .\"     @(#)getc.3	8.1 (Berkeley) 6/4/93
 .\" $FreeBSD$
 .\"
-.Dd June 4, 1993
+.Dd January 10, 2003
 .Dt GETC 3
 .Os
 .Sh NAME
 .Nm fgetc ,
 .Nm getc ,
+.Nm getc_unlocked
 .Nm getchar ,
+.Nm getchar_unlocked
 .Nm getw
 .Nd get next character or word from input stream
 .Sh LIBRARY
@@ -54,8 +56,12 @@
 .Ft int
 .Fn getc "FILE *stream"
 .Ft int
+.Fn getc_unlocked "FILE *stream"
+.Ft int
 .Fn getchar
 .Ft int
+.Fn getchar_unlocked "FILE *stream"
+.Ft int
 .Fn getw "FILE *stream"
 .Sh DESCRIPTION
 The
@@ -87,6 +93,23 @@ obtains the next
 (if present)
 from the stream pointed at by
 .Fa stream .
+.Pp
+The
+.Fn getc_unlocked
+and
+.Fn getchar_unlocked
+functions are equivalent to
+.Fn getc
+and
+.Fn getchar
+respectively,
+except that the caller is responsible for locking the stream
+with
+.Fn flockfile
+before calling them.
+These functions may be used to avoid the overhead of locking the stream
+for each character, and to avoid input being dispersed among multiple
+threads reading from the same stream.
 .Sh RETURN VALUES
 If successful, these routines return the next requested object
 from the
@@ -113,6 +136,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 ,
@@ -127,6 +151,12 @@ and
 functions
 conform to
 .St -isoC .
+The
+.Fn getc_unlocked
+and
+.Fn getchar_unlocked
+functions conform to
+.St -p1003.1-2001 .
 .Sh BUGS
 Since
 .Dv EOF
diff --git a/lib/libc/stdio/putc.3 b/lib/libc/stdio/putc.3
index 8018fd483cdc..2223a47058ac 100644
--- a/lib/libc/stdio/putc.3
+++ b/lib/libc/stdio/putc.3
@@ -36,7 +36,7 @@
 .\"     @(#)putc.3	8.1 (Berkeley) 6/4/93
 .\" $FreeBSD$
 .\"
-.Dd June 4, 1993
+.Dd January 10, 2003
 .Dt PUTC 3
 .Os
 .Sh NAME
@@ -54,8 +54,12 @@
 .Ft int
 .Fn putc "int c" "FILE *stream"
 .Ft int
+.Fn putc_unlocked "int c" "FILE *stream"
+.Ft int
 .Fn putchar "int c"
 .Ft int
+.Fn putchar_unlocked "int c"
+.Ft int
 .Fn putw "int w" "FILE *stream"
 .Sh DESCRIPTION
 The
@@ -93,12 +97,31 @@ writes the specified
 .Vt int
 to the named output
 .Fa stream .
-.Sh RETURN VALUES
-The functions,
-.Fn fputc ,
+.Pp
+The
+.Fn putc_unlocked
+and
+.Fn putchar_unlocked
+functions are equivalent to
 .Fn putc
 and
 .Fn putchar
+respectively,
+except that the caller is responsible for locking the stream
+with
+.Fn flockfile
+before calling them.
+These functions may be used to avoid the overhead of locking the stream
+for each character, and to avoid output being interspersed from multiple
+threads writing to the same stream.
+.Sh RETURN VALUES
+The functions,
+.Fn fputc ,
+.Fn putc ,
+.Fn putchar ,
+.Fn putc_unlocked
+and
+.Fn putchar_unlocked
 return the character written.
 If an error occurs, the value
 .Dv EOF
@@ -113,6 +136,7 @@ a write error occurs,
 or if an attempt is made to write a read-only stream.
 .Sh SEE ALSO
 .Xr ferror 3 ,
+.Xr flockfile 3 ,
 .Xr fopen 3 ,
 .Xr getc 3 ,
 .Xr putwc 3 ,
@@ -125,6 +149,12 @@ and
 .Fn putchar ,
 conform to
 .St -isoC .
+The
+.Fn putc_unlocked
+and
+.Fn putchar_unlocked
+functions conform to
+.St -p1003.1-2001 .
 A function
 .Fn putw
 function appeared in