[src/trunk]: src/lib/libc/stdio Document getc_unlocked(3), getchar_unlocked(3...

[kleink <kleink%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/92c15518e5ba
branches:  trunk
changeset: 509066:92c15518e5ba
user:      kleink <kleink%NetBSD.org@localhost>
date:      Wed Apr 25 22:06:53 2001 +0000

description:
Document getc_unlocked(3), getchar_unlocked(3), putc_unlocked(3) and
putchar_unlocked(3); fixes PR lib/11340.

diffstat:

 lib/libc/stdio/Makefile.inc |   8 +++++---
 lib/libc/stdio/getc.3       |  36 ++++++++++++++++++++++++++++++++++--
 lib/libc/stdio/putc.3       |  36 ++++++++++++++++++++++++++++++++++--
 3 files changed, 73 insertions(+), 7 deletions(-)

diffs (181 lines):

diff -r eb74efd19acf -r 92c15518e5ba lib/libc/stdio/Makefile.inc
--- a/lib/libc/stdio/Makefile.inc       Wed Apr 25 18:32:10 2001 +0000
+++ b/lib/libc/stdio/Makefile.inc       Wed Apr 25 22:06:53 2001 +0000
@@ -1,5 +1,5 @@
 #      from: @(#)Makefile.inc  5.7 (Berkeley) 6/27/91
-#      $NetBSD: Makefile.inc,v 1.19 2000/07/08 13:46:35 kleink Exp $
+#      $NetBSD: Makefile.inc,v 1.20 2001/04/25 22:06:53 kleink Exp $
 
 # stdio sources
 .PATH: ${.CURDIR}/stdio
@@ -37,12 +37,14 @@
 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+=mktemp.3 mkdtemp.3 mktemp.3 mkstemp.3
 MLINKS+=printf.3 asprintf.3 printf.3 fprintf.3 printf.3 snprintf.3 \
        printf.3 sprintf.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+=scanf.3 fscanf.3 scanf.3 sscanf.3 scanf.3 vfscanf.3 scanf.3 vscanf.3 \
        scanf.3 vsscanf.3
 MLINKS+=setbuf.3 setbuffer.3 setbuf.3 setlinebuf.3 setbuf.3 setvbuf.3
diff -r eb74efd19acf -r 92c15518e5ba lib/libc/stdio/getc.3
--- a/lib/libc/stdio/getc.3     Wed Apr 25 18:32:10 2001 +0000
+++ b/lib/libc/stdio/getc.3     Wed Apr 25 22:06:53 2001 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: getc.3,v 1.5 1998/04/28 20:58:01 fair Exp $
+.\"    $NetBSD: getc.3,v 1.6 2001/04/25 22:06:54 kleink Exp $
 .\"
 .\" Copyright (c) 1990, 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -37,13 +37,15 @@
 .\"
 .\"     @(#)getc.3     8.1 (Berkeley) 6/4/93
 .\"
-.Dd June 4, 1993
+.Dd April 25, 2001
 .Dt GETC 3
 .Os
 .Sh NAME
 .Nm fgetc ,
 .Nm getc ,
 .Nm getchar ,
+.Nm getc_unlocked ,
+.Nm getchar_unlocked ,
 .Nm getw
 .Nd get next character or word from input stream
 .Sh LIBRARY
@@ -57,6 +59,10 @@
 .Ft int
 .Fn getchar
 .Ft int
+.Fn getc_unlocked "FILE *stream"
+.Ft int
+.Fn getchar_unlocked
+.Ft int
 .Fn getw "FILE *stream"
 .Sh DESCRIPTION
 The
@@ -81,6 +87,26 @@
 getc with the argument stdin.
 .Pp
 The
+.Fn getc_unlocked
+and
+.Fn getchar_unlocked
+functions provide functionality identical to that of
+.Fn getc
+and
+.Fn getchar ,
+respectively, but do not perform implicit locking of the streams they
+operate on.
+In multi-threaded programs they may be used
+.Em only
+within a scope in which the stream
+has been successfully locked by the calling thread using either
+.Xr flockfile 3
+or
+.Xr ftrylockfile 3 ,
+and may later be released using
+.Xr funlockfile 3 .
+.Pp
+The
 .Fn getw
 function
 obtains the next
@@ -123,6 +149,12 @@
 functions
 conform to
 .St -ansiC .
+The
+.Fn getc_unlocked
+and
+.Fn getchar_unlocked
+functions conform to
+.St -p1003.1-96 .
 .Sh BUGS
 Since
 .Dv EOF
diff -r eb74efd19acf -r 92c15518e5ba lib/libc/stdio/putc.3
--- a/lib/libc/stdio/putc.3     Wed Apr 25 18:32:10 2001 +0000
+++ b/lib/libc/stdio/putc.3     Wed Apr 25 22:06:53 2001 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: putc.3,v 1.5 1998/08/29 08:32:34 lukem Exp $
+.\"    $NetBSD: putc.3,v 1.6 2001/04/25 22:06:54 kleink Exp $
 .\"
 .\" Copyright (c) 1990, 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -37,13 +37,15 @@
 .\"
 .\"     @(#)putc.3     8.1 (Berkeley) 6/4/93
 .\"
-.Dd June 4, 1993
+.Dd April 25, 2001
 .Dt PUTC 3
 .Os
 .Sh NAME
 .Nm fputc ,
 .Nm putc ,
 .Nm putchar ,
+.Nm putc_unlocked ,
+.Nm putchar_unlocked ,
 .Nm putw
 .Nd output a character or word to a stream
 .Sh LIBRARY
@@ -57,6 +59,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
@@ -84,6 +90,26 @@
 .Em stdout .
 .Pp
 The
+.Fn putc_unlocked
+and
+.Fn putchar_unlocked
+functions provide functionality identical to that of
+.Fn putc
+and
+.Fn putchar ,
+respectively, but do not perform implicit locking of the streams they
+operate on.
+In multi-threaded programs they may be used
+.Em only
+within a scope in which the stream
+has been successfully locked by the calling thread using either
+.Xr flockfile 3
+or
+.Xr ftrylockfile 3 ,
+and may later be released using
+.Xr funlockfile 3 .
+.Pp
+The
 .Fn putw
 function
 writes the specified
@@ -121,6 +147,12 @@
 .Fn putchar ,
 conform to
 .St -ansiC .
+The functions
+.Fn putc_unlocked
+and
+.Fn putchar_unlocked
+conform to
+.St -p1003.1-96 .
 A function
 .Fn putw
 function appeared in