BSD 4.4 Lite Lib Sources

1 files changed, 287 insertions, 0 deletions

diff --git a/lib/libc/stdio/stdio.3 b/lib/libc/stdio/stdio.3
new file mode 100644
index 0000000..572df8c
--- /dev/null
+++ b/lib/libc/stdio/stdio.3
@@ -0,0 +1,287 @@
+.\" Copyright (c) 1990, 1991, 1993
+.\"	The Regents of the University of California.  All rights reserved.
+.\"
+.\" 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.
+.\"
+.\" 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.7 (Berkeley) 4/19/94
+.\"
+.Dd April 19, 1994
+.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 appended 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 transferred
+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
+This implementation needs and makes
+no distinction between
+.Dq text
+and
+.Dq binary
+streams.
+In effect, all streams are binary.
+No translation is performed and no extra padding appears on any stream.
+.Pp
+At program startup, three streams are predefined and need not be
+opened explicitly:
+.Bl -bullet -compact -offset indent
+.It
+.Em standard input 
+(for reading conventional input),
+.It
+.Em standard output 
+(for writing conventional input), and
+.It
+.Em standard error
+(for writing diagnostic output).
+.El
+These streams are abbreviated
+.Em stdin , stdout
+and
+.Em stderr .
+Initially, the standard error stream
+is unbuffered; the standard input and output streams are
+fully buffered if and only if the streams do not refer to
+an interactive or
+.Dq terminal
+device, as determined by the
+.Xr isatty 3
+function.
+In fact,
+.Em all
+freshly-opened streams that refer to terminal devices
+default to line buffering, and
+pending output to such streams is written automatically
+whenever an such an input stream is read.
+Note that this applies only to
+.Dq "true reads" ;
+if the read request can be satisfied by existing buffered data,
+no automatic flush will occur.
+In these cases,
+or when a large amount of computation is done after printing
+part of a line on an output terminal, it is necessary to
+.Xr fflush 3
+the standard output before going off and computing so that the output
+will appear.
+Alternatively, these defaults may be modified via the
+.Xr setvbuf 3
+function.
+.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 freopen ,
+.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
+.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
+mkstemp	create unique temporary file
+mktemp	create unique temporary file
+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