summaryrefslogtreecommitdiffstats
path: root/lib/libc/stdio/stdio.3
diff options
context:
space:
mode:
Diffstat (limited to 'lib/libc/stdio/stdio.3')
-rw-r--r--lib/libc/stdio/stdio.3287
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
OpenPOWER on IntegriCloud