X-Git-Url: https://git.subgeniuskitty.com/unix-history/.git/blobdiff_plain/1c15e88899094343f75aeba04122cd96a96b428e..ad7871609881e73855d0b04da49b486cd93efca7:/usr/src/lib/libc/stdio/stdio.3

diff --git a/usr/src/lib/libc/stdio/stdio.3 b/usr/src/lib/libc/stdio/stdio.3
index 1929a48211..a8f7adc726 100644
--- a/usr/src/lib/libc/stdio/stdio.3
+++ b/usr/src/lib/libc/stdio/stdio.3
@@ -1,179 +1,262 @@
-.\" Copyright (c) 1980 Regents of the University of California.
-.\" All rights reserved.  The Berkeley software License Agreement
-.\" specifies the terms and conditions for redistribution.
+.\" Copyright (c) 1990, 1991, 1993
+.\"	The Regents of the University of California.  All rights reserved.
 .\"
-.\"	@(#)stdio.3	6.2 (Berkeley) 5/13/86
+.\" 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 University of
+.\"	California, Berkeley and its contributors.
+.\" 4. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
 .\"
-.TH STDIO 3S "May 13, 1986"
-.UC 4
-.SH NAME
-stdio \- standard buffered input/output package
-.SH SYNOPSIS
-.B #include <stdio.h>
-.PP
-.SM
-.B FILE
-.B *stdin;
-.br
-.SM
-.B FILE
-.B *stdout;
-.br
-.SM
-.B FILE
-.B *stderr;
-.SH DESCRIPTION
-The functions described in section 3S constitute a user-level buffering
-scheme.  The in-line macros
-.I getc
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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.
+.\"
+.\"     @(#)stdio.3	8.1 (Berkeley) 6/4/93
+.\"
+.Dd June 4, 1993
+.Dt STDIO 3
+.Os BSD 4
+.Sh NAME
+.Nm stdio
+.Nd standard input/output library functions
+.Sh SYNOPSIS
+.Fd #include <stdio.h>
+.Fd FILE *stdin;
+.Fd FILE *stdout;
+.Fd FILE *stderr;
+.Sh DESCRIPTION
+The standard
+.Tn I/O
+library provides a simple and efficient buffered stream
+.Tn I/O
+interface.
+Input and ouput is mapped into logical data streams
+and the physical
+.Tn I/O
+characteristics are concealed. The functions and macros are listed
+below; more information is available from the individual man pages.
+.Pp
+A stream is associated with an external file (which may be a physical
+device) by
+.Em opening
+a file, which may involve creating a new file. Creating an
+existing file causes its former contents to be discarded.
+If a file can support positioning requests (such as a disk file, as opposed
+to a terminal) then a
+.Em file position indicator
+associated with the stream is positioned at the start of the file (byte
+zero), unless the file is opened with appened mode. If append mode
+is used, the position indicator will be placed the end-of-file.
+The position indicator is maintained by subsequent reads, writes
+and positioning requests. All input occurs as if the characters
+were read by successive calls to the
+.Xr fgetc 3
+function; all ouput takes place as if all characters were
+read by successive calls to the
+.Xr fputc 3
+function.
+.Pp
+A file is disassociated from a stream by
+.Em closing
+the file.
+Ouput streams are flushed (any unwritten buffer contents are transfered
+to the host environment) before the stream is disassociated from the file.
+The value of a pointer to a
+.Dv FILE
+object is indeterminate after a file is closed (garbage).
+.Pp
+A file may be subsequently reopened, by the same or another program
+execution, and its contents reclaimed or modified (if it can be repositioned
+at the start).  If the main function returns to its original caller, or
+the
+.Xr exit 3
+function is called, all open files are closed (hence all output
+streams are flushed) before program termination.  Other methods
+of program termination, such as
+.Xr abort 3
+do not bother about closing files properly.
+.Pp
+At program startup, three text streams are predefined and need not be
+opened explicitly
+\(em
+.Em standard input 
+(for reading converntional input),
+\(em
+.Em standard output 
+(for writing converntional input),
 and
-.IR  putc (3S)
-handle characters quickly.  The higher level routines
-.IR gets ,
-.IR fgets ,
-.IR scanf ,
-.IR fscanf ,
-.IR fread ,
-.IR puts ,
-.IR fputs ,
-.IR printf ,
-.IR fprintf ,
-.IR fwrite
-all use
-.I getc
+.Em standard error
+(for writing diagnostic output).
+These streams are abbreviated
+.Em stdin , stdout
 and
-.IR putc ;
-they can be freely intermixed.
-.PP
-A file with associated buffering is called a
-.IR stream ,
-and is declared to be a pointer to a defined type
-.SM
-.BR FILE .
-.IR  Fopen (3S)
-creates certain descriptive data for a stream
-and returns a pointer to designate the stream in all further transactions.
-There are three normally open streams with constant pointers declared in
-the include file and associated with the standard open files:
-.TP 10n
-.B stdin
-standard input file
-.br
-.ns
-.TP
-.B stdout
-standard output file
-.br
-.ns
-.TP
-.B stderr
-standard error file
-.PP
-A constant `pointer'
-.SM
-.B NULL
-(0)
-designates no stream at all.
-.PP
-An integer constant
-.SM
-.B EOF
-(\-1) is returned upon end of file or error by integer functions that
-deal with streams.
-.PP
-Any routine that uses the standard input/output package
-must include the header file
-.RI < stdio.h >
-of pertinent macro definitions.
-The functions and constants mentioned in sections labeled 3S
-are declared in the include file and need no further declaration.
-The constants, and the following `functions' are
-implemented as macros; redeclaration of these names is perilous:
-.IR getc ,
-.IR getchar ,
-.IR putc ,
-.IR putchar ,
-.IR feof ,
-.IR ferror ,
-.IR fileno .
-.SH "SEE ALSO"
-open(2), close(2), read(2), write(2), fread(3S), fseek(3S), f*(3S)
-.SH DIAGNOSTICS
-The value
-.SM
-.B EOF
-is returned uniformly to indicate that a
-.SM
-.B FILE
-pointer has not been initialized with
-.IR fopen ,
-input (output) has been attempted on an output (input) stream, or a
-.SM
-.B FILE
-pointer designates corrupt or otherwise unintelligible
-.SM
-.B FILE
-data.
-.PP
-For purposes of efficiency, this implementation of the standard library
-has been changed to line buffer output to a terminal by default and attempts
-to do this transparently by flushing the output whenever a 
-.IR read (2)
-from the standard input is necessary.  This is almost always transparent,
-but may cause confusion or malfunctioning of programs which use
-standard i/o routines but use
-.IR read (2)
-themselves to read from the standard input.
-.PP
+.Em stderr .
+When opened, the standard error stream
+is not fully buffered; the standard input and output streams are
+fully buffered if and only if the streams do not to refer to
+an interactive device.
+.Pp
+Output streams that refer to terminal devices
+are always line buffered by default;
+pending output to such streams is written automatically
+whenever an input stream that refers to a terminal device is read.
 In cases where a large amount of computation is done after printing
 part of a line on an output terminal, it is necessary to
-.IR fflush (3S)
+.Xr fflush 3
 the standard output before going off and computing so that the output
 will appear.
-.SH BUGS
+.Pp
+The
+.Nm stdio
+library is a part of the library
+.Xr libc
+and routines are automatically loaded as needed by the compilers
+.Xr cc 1
+and
+.Xr pc 1 .
+The
+.Tn SYNOPSIS
+sections of the following manual pages indicate which include files
+are to be used, what the compiler declaration for the function
+looks like and which external variables are of interest.
+.Pp
+The following are defined as macros;
+these names may not be re-used
+without first removing their current definitions with
+.Dv #undef :
+.Dv BUFSIZ ,
+.Dv EOF ,
+.Dv FILENAME_MAX ,
+.DV FOPEN_MAX ,
+.Dv L_cuserid ,
+.Dv L_ctermid ,
+.Dv L_tmpnam,
+.Dv NULL ,
+.Dv SEEK_END ,
+.Dv SEEK_SET ,
+.Dv SEE_CUR ,
+.Dv TMP_MAX ,
+.Dv clearerr ,
+.Dv feof ,
+.Dv ferror ,
+.Dv fileno ,
+.Dv fropen ,
+.Dv fwopen ,
+.Dv getc ,
+.Dv getchar ,
+.Dv putc ,
+.Dv putchar ,
+.Dv stderr ,
+.Dv stdin ,
+.Dv stdout .
+Function versions of the macro functions
+.Xr feof ,
+.Xr ferror ,
+.Xr clearerr ,
+.Xr fileno ,
+.Xr getc ,
+.Xr getchar ,
+.Xr putc ,
+and
+.Xr putchar
+exist and will be used if the macros
+definitions are explicitly removed.
+.Sh SEE ALSO
+.Xr open 2 ,
+.Xr close 2 ,
+.Xr read 2 ,
+.Xr write 2
+.Sh BUGS
 The standard buffered functions do not interact well with certain other
-library and system functions, especially \fIvfork\fP and \fIabort\fP.
-.SH "LIST OF FUNCTIONS"
-.sp 2
-.nf
-.ta \w'setlinebuf'u+2n +\w'setbuf.3s'u+10n
-\fIName\fP	\fIAppears on Page\fP	\fIDescription\fP
-.ta \w'setlinebuf'u+4n +\w'setbuf.3s'u+4n
-.sp 5p
-clearerr	ferror.3s	stream status inquiries
-fclose	fclose.3s	close or flush a stream
-fdopen	fopen.3s	open a stream
-feof	ferror.3s	stream status inquiries
-ferror	ferror.3s	stream status inquiries
-fflush	fclose.3s	close or flush a stream
-fgetc	getc.3s	get character or word from stream
-fgets	gets.3s	get a string from a stream
-fileno	ferror.3s	stream status inquiries
-fopen	fopen.3s	open a stream
-fprintf	printf.3s	formatted output conversion
-fputc	putc.3s	put character or word on a stream
-fputs	puts.3s	put a string on a stream
-fread	fread.3s	buffered binary input/output
-freopen	fopen.3s	open a stream
-fscanf	scanf.3s	formatted input conversion
-fseek	fseek.3s	reposition a stream
-ftell	fseek.3s	reposition a stream
-fwrite	fread.3s	buffered binary input/output
-getc	getc.3s	get character or word from stream
-getchar	getc.3s	get character or word from stream
-gets	gets.3s	get a string from a stream
-getw	getc.3s	get character or word from stream
-printf	printf.3s	formatted output conversion
-putc	putc.3s	put character or word on a stream
-putchar	putc.3s	put character or word on a stream
-puts	puts.3s	put a string on a stream
-putw	putc.3s	put character or word on a stream
-rewind	fseek.3s	reposition a stream
-scanf	scanf.3s	formatted input conversion
-setbuf	setbuf.3s	assign buffering to a stream
-setbuffer	setbuf.3s	assign buffering to a stream
-setlinebuf	setbuf.3s	assign buffering to a stream
-sprintf	printf.3s	formatted output conversion
-sscanf	scanf.3s	formatted input conversion
-ungetc	ungetc.3s	push character back into input stream
-.fi
+library and system functions, especially
+.Xr vfork
+and
+.Xr abort .
+.Sh STANDARDS
+The
+.Nm stdio
+library conforms to
+.St -ansiC .
+.Sh LIST OF FUNCTIONS
+.Bl -column "Description"
+.Sy Function	Description
+clearerr	check and reset stream status
+fclose	close a stream
+fdopen	stream open functions
+feof	check and reset stream status
+ferror	check and reset stream status
+fflush	flush a stream
+fgetc	get next character or word from input stream
+fgetline	get a line from a stream
+fgetpos	reposition a stream
+fgets	get a line from a stream
+fileno	check and reset stream status
+fopen	stream open functions
+fprintf	formatted output conversion
+fpurge	flush a stream
+fputc	output a character or word to a stream
+fputs	output a line to a stream
+fread	binary stream input/output
+freopen	stream open functions
+fropen	open a stream
+fscanf	input format conversion
+fseek	reposition a stream
+fsetpos	reposition a stream
+ftell	reposition a stream
+funopen	open a stream
+fwopen	open a stream
+fwrite	binary stream input/output
+getc	get next character or word from input stream
+getchar	get next character or word from input stream
+gets	get a line from a stream
+getw	get next character or word from input stream
+mktemp	make temporary file name (unique)
+perror	system error messages
+printf	formatted output conversion
+putc	output a character or word to a stream
+putchar	output a character or word to a stream
+puts	output a line to a stream
+putw	output a character or word to a stream
+remove	remove directory entry
+rewind	reposition a stream
+scanf	input format conversion
+setbuf	stream buffering operations
+setbuffer	stream buffering operations
+setlinebuf	stream buffering operations
+setvbuf	stream buffering operations
+snprintf	formatted output conversion
+sprintf	formatted output conversion
+sscanf	input format conversion
+strerror	system error messages
+sys_errlist	system error messages
+sys_nerr	system error messages
+tempnam	temporary file routines
+tmpfile	temporary file routines
+tmpnam	temporary file routines
+ungetc	un-get character from input stream
+vfprintf	formatted output conversion
+vfscanf	input format conversion
+vprintf	formatted output conversion
+vscanf	input format conversion
+vsnprintf	formatted output conversion
+vsprintf	formatted output conversion
+vsscanf	input format conversion
+.El