[src/trunk]: src/lib/libc/stdio Add a manual page for flockfile(3) etc.; whil...

To: source-changes-hg%NetBSD.org@localhost
Subject: [src/trunk]: src/lib/libc/stdio Add a manual page for flockfile(3) etc.; whil...
From: kleink <kleink%NetBSD.org@localhost>
Date: Fri, 24 Jan 2020 12:37:16 +0000
details:   https://anonhg.NetBSD.org/src/rev/24ae608ccc99
branches:  trunk
changeset: 542428:24ae608ccc99
user:      kleink <kleink%NetBSD.org@localhost>
date:      Tue Jan 28 20:26:04 2003 +0000

description:
Add a manual page for flockfile(3) etc.; while here, also add *_unlocked()
to stdio(3) overview documentation.  Fixes PR lib/20096 from Jason Thorpe.

diffstat:

 lib/libc/stdio/Makefile.inc |   11 ++-
 lib/libc/stdio/flockfile.3  |  127 ++++++++++++++++++++++++++++++++++++++++++++
 lib/libc/stdio/getc.3       |    5 +-
 lib/libc/stdio/stdio.3      |   42 +++++++++++++-
 4 files changed, 175 insertions(+), 10 deletions(-)

diffs (299 lines):

diff -r 832d846a59bc -r 24ae608ccc99 lib/libc/stdio/Makefile.inc
--- a/lib/libc/stdio/Makefile.inc       Tue Jan 28 18:36:04 2003 +0000
+++ b/lib/libc/stdio/Makefile.inc       Tue Jan 28 20:26:04 2003 +0000
@@ -1,5 +1,5 @@
 #      from: @(#)Makefile.inc  5.7 (Berkeley) 6/27/91
-#      $NetBSD: Makefile.inc,v 1.23 2003/01/18 11:29:50 thorpej Exp $
+#      $NetBSD: Makefile.inc,v 1.24 2003/01/28 20:26:04 kleink Exp $
 
 # stdio sources
 .PATH: ${.CURDIR}/stdio
@@ -26,13 +26,14 @@
 # namespace purity wrappers
 SRCS+= _fseeko.c _ftello.c
 
-MAN+=  fclose.3 ferror.3 fflush.3 fgetln.3 fgets.3 fopen.3 fputs.3 \
-       fread.3 fseek.3 funopen.3 getc.3 mktemp.3 perror.3 printf.3 putc.3 \
-       remove.3 scanf.3 setbuf.3 stdio.3 tmpnam.3 ungetc.3 putwc.3 getwc.3 \
-       ungetwc.3 fwide.3 fparseln.3
+MAN+=  fclose.3 ferror.3 fflush.3 fgetln.3 fgets.3 flockfile.3 fopen.3 \
+       fputs.3 fread.3 fseek.3 funopen.3 getc.3 mktemp.3 perror.3 printf.3 \
+       putc.3 remove.3 scanf.3 setbuf.3 stdio.3 tmpnam.3 ungetc.3 putwc.3 \
+       getwc.3 ungetwc.3 fwide.3 fparseln.3
 
 MLINKS+=ferror.3 clearerr.3 ferror.3 feof.3 ferror.3 fileno.3
 MLINKS+=fflush.3 fpurge.3
+MLINKS+=flockfile.3 ftrylockfile.3 flockfile.3 funlockfile.3
 MLINKS+=fgets.3 gets.3
 MLINKS+=fopen.3 fdopen.3 fopen.3 freopen.3
 MLINKS+=fputs.3 puts.3
diff -r 832d846a59bc -r 24ae608ccc99 lib/libc/stdio/flockfile.3
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/lib/libc/stdio/flockfile.3        Tue Jan 28 20:26:04 2003 +0000
@@ -0,0 +1,127 @@
+.\"    $NetBSD: flockfile.3,v 1.1 2003/01/28 20:26:04 kleink Exp $
+.\"
+.\" Copyright (c) 2003 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Klaus Klein.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"        This product includes software developed by the NetBSD
+.\"        Foundation, Inc. and its contributors.
+.\" 4. Neither the name of The NetBSD Foundation nor the names of its
+.\"    contributors may be used to endorse or promote products derived
+.\"    from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd January 28, 2003
+.Dt FLOCKFILE 3
+.Os
+.Sh NAME
+.Nm flockfile ,
+.Nm ftrylockfile ,
+.Nm funlockfile
+.Nd stdio stream locking functions
+.Sh LIBRARY
+.Lb libc
+.Sh SYNOPSIS
+.Fd #include \*[Lt]stdio.h\*[Gt]
+.Ft void
+.Fn flockfile "FILE *file"
+.Ft int
+.Fn ftrylockfile "FILE *file"
+.Ft void
+.Fn funlockfile "FILE *file"
+.Sh DESCRIPTION
+The
+.Fn flockfile ,
+.Fn ftrylockfile
+and
+.Fn funlockfile
+functions provide applications with explicit control of locking of
+stdio stream objects.
+They can be used by a thread to execute a sequence of I/O operations
+as a unit, without interference from another thread.
+.Pp
+Locks on stdio streams are recursive, and a lock count is maintained.
+stdio streams are created unlocked, with a lock count of zero.
+After successful acquisition of the lock, its count is incremented
+to one, indicating locked state of the stdio stream.
+Each subsequent relock operation performed by the owner thread
+increments the lock count by one, and each subsequent unlock
+operation performed by the owner thread decrements the lock count by one,
+allowing matching lock and unlock operations to be nested.
+After its lock count is decremented to zero, the stdio stream returns
+to unlocked state, and ownership of the stdio stream is relinquished.
+.Pp
+The
+.Fn flockfile
+function acquires the ownership of
+.Fa file
+for the calling thread.
+If
+.Fa file
+is already owned by another thread, the calling thread is suspended
+until the acquisition is possible (i.e.,
+.Fa file
+is relinquished again and the calling thread is scheduled to acquire it).
+.Pp
+The
+.Fn ftrylockfile
+function acquires the ownership of
+.Fa file
+for the calling thread only if
+.Fa file
+is available.
+.Pp
+The
+.Fn funlockfile
+function relinquishes the ownership of
+.Fa file
+previously granted to the calling thread.
+Only the current owner of
+.Fa file
+may
+.Fn funlockfile
+it.
+.Sh RETURN VALUES
+If successful, the
+.Fn ftrylockfile
+function returns 0.
+Otherwise, it returns non-zero to indicate that the lock cannot be acquired.
+.Sh SEE ALSO
+.Xr getc_unlocked 3 ,
+.Xr getchar_unlocked 3 ,
+.Xr putc_unlocked 3 ,
+.Xr putchar_unlocked 3
+.Sh STANDARDS
+The
+.Fn flockfile ,
+.Fn ftrylockfile
+and
+.Fn funlockfile
+functions conform to
+.St -p1003.1-2001 .
+.Sh BUGS
+The design of these interfaces does not allow for addressing the
+problem of priority inversion.
diff -r 832d846a59bc -r 24ae608ccc99 lib/libc/stdio/getc.3
--- a/lib/libc/stdio/getc.3     Tue Jan 28 18:36:04 2003 +0000
+++ b/lib/libc/stdio/getc.3     Tue Jan 28 20:26:04 2003 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: getc.3,v 1.9 2003/01/18 11:29:55 thorpej Exp $
+.\"    $NetBSD: getc.3,v 1.10 2003/01/28 20:26:04 kleink Exp $
 .\"
 .\" Copyright (c) 1990, 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -136,8 +136,11 @@
 .Xr clearerr 3 .
 .Sh SEE ALSO
 .Xr ferror 3 ,
+.Xr flockfile 3 ,
 .Xr fopen 3 ,
 .Xr fread 3 ,
+.Xr ftrylockfile 3 ,
+.Xr funlockfile 3 ,
 .Xr putc 3 ,
 .Xr ungetc 3
 .Sh STANDARDS
diff -r 832d846a59bc -r 24ae608ccc99 lib/libc/stdio/stdio.3
--- a/lib/libc/stdio/stdio.3    Tue Jan 28 18:36:04 2003 +0000
+++ b/lib/libc/stdio/stdio.3    Tue Jan 28 20:26:04 2003 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: stdio.3,v 1.16 2003/01/18 11:29:58 thorpej Exp $
+.\"    $NetBSD: stdio.3,v 1.17 2003/01/28 20:26:04 kleink Exp $
 .\"
 .\" Copyright (c) 1990, 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -33,7 +33,7 @@
 .\"
 .\"     @(#)stdio.3    8.7 (Berkeley) 4/19/94
 .\"
-.Dd April 19, 1994
+.Dd January 28, 2003
 .Dt STDIO 3
 .Os
 .Sh NAME
@@ -168,6 +168,21 @@
 are to be used, what the compiler declaration for the function
 looks like and which external variables are of interest.
 .Pp
+In multi-threaded applications, operations on streams perform implicit
+locking, except for the
+.Fa getc_unlocked ,
+.Fa getchar_unlocked ,
+.Fa putc_unlocked ,
+and
+.Fa putchar_unlocked
+functions.
+Explicit control of stream locking is available through the
+.Fa flockfile ,
+.Fa ftrylockfile ,
+and
+.Fa funlockfile
+functions .
+.Pp
 The following are defined as macros; these names may not be re-used
 without first removing their current definitions with
 .Dv #undef :
@@ -190,9 +205,13 @@
 .Fn freopen ,
 .Fn fwopen ,
 .Fn getc ,
+.Fn getc_unlocked ,
 .Fn getchar ,
+.Fn getchar_unlocked ,
 .Fn putc ,
+.Fn putc_unlocked ,
 .Fn putchar ,
+.Fn putchar_unlocked ,
 .Dv stderr ,
 .Dv stdin ,
 .Dv stdout .
@@ -202,10 +221,14 @@
 .Fn clearerr ,
 .Fn fileno ,
 .Fn getc ,
+.Fn getc_unlocked ,
 .Fn getchar ,
+.Fn getchar_unlocked ,
 .Fn putc ,
+.Fn putc_unlocked ,
+.Fn putchar ,
 and
-.Fn putchar
+.Fn putchar_unlocked
 exist and will be used if the macros definitions are explicitly removed.
 .Sh SEE ALSO
 .Xr close 2 ,
@@ -218,7 +241,7 @@
 library conforms to
 .St -ansiC .
 .Sh LIST OF FUNCTIONS
-.Bl -column "Description"
+.Bl -column "Functionxxxxxxxx" "Description"
 .Sy Function   Description
 clearerr       check and reset stream status
 fclose close a stream
@@ -232,6 +255,7 @@
 fgets  get a line from a stream
 fgetwc get next wide character from input stream
 fileno check and reset stream status
+flockfile      lock a stream
 fopen  stream open functions
 fprintf        formatted output conversion
 fpurge flush a stream
@@ -245,12 +269,18 @@
 fseek  reposition a stream
 fsetpos        reposition a stream
 ftell  reposition a stream
+ftrylockfile   lock a stream (non-blocking)
+funlockfile    unlock a stream
 funopen        open a stream
 fwide  set/get orientation of a stream
 fwopen open a stream
 fwrite binary stream input/output
 getc   get next character or word from input stream
+getc_unlocked  get next character or word from input stream
+       (no implicit locking)
 getchar        get next character or word from input stream
+getchar_unlocked       get next character or word from input stream
+       (no implicit locking)
 gets   get a line from a stream
 getw   get next character or word from input stream
 getwc  get next wide character from input stream
@@ -260,7 +290,11 @@
 perror system error messages
 printf formatted output conversion
 putc   output a character or word to a stream
+putc_unlocked  output a character or word to a stream
+       (no implicit locking)
 putchar        output a character or word to a stream
+putchar_unlocked       output a character or word to a stream
+       (no implicit locking)
 puts   output a line to a stream
 putw   output a character or word to a stream
 putwc  output a wide character to a stream
Prev by Date: [src/trunk]: src/usr.sbin/dumplfs make this build on alpha after daddr_t->64bit
Next by Date: [src/trunk]: src/lib/libc/stdio a, b, and c.
Previous by Thread: [src/trunk]: src/usr.sbin/dumplfs make this build on alpha after daddr_t->64bit
Next by Thread: [src/trunk]: src/lib/libc/stdio a, b, and c.
Indexes:
Home | Main Index | Thread Index | Old Index