4.1cBSD/usr/man/man3/intro.3s

.TH INTRO 3S  "19 January 1983"
.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
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
and
.IR putc ;
they can be freely intermixed.
.PP
A file with associated buffering is called a
.I stream,
and is declared to be a pointer to a defined type
.SM
.B 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
.BR stdin
standard input file
.br
.ns
.TP
.B stdout
standard output file
.br
.ns
.TP
.BR 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
.I 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
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)
the standard output before going off and computing so that the output
will appear.
.SH BUGS
The standard buffered functions do not interact well with certain other
library and system functions, especially \fIvfork\fP and \fIabort\fP.
.LP
.sp 2
.ce
\fIFunctions Available in the Standard I/O Library\fP
.sp
.ta 0.4i 2.5i
.nf
fclose		close a stream
	fflush	flush a stream (see fclose.3s)
.sp
feof		stream status inquiries
	ferror	stream status inquiries (see ferror.3s)
	clearerr	stream status inquiries (see ferror.3s)
	fileno	stream status inquiries (see ferror.3s)
.sp
fopen		open a stream
	freopen	reopen a stream (see fopen.3s)
	fdopen	open a stream (see fopen.3s)
.sp
fread		buffered binary input/output
	fwrite	buffered binary input/output (see fread.3s)
.sp
fseek		reposition a stream
	ftell	obtain position of a stream (see fseek.3s)
	rewind	rewind a stream (see fseek.3s)
.sp
getc		get character from stream
	getchar	get character from stream (see getc.3s)
	fgetc	get character from stream (see getc.3s)
	getw	get word from stream (see getc.3s)
.sp
gets		get a string from a stream
	fgets	get a string from a stream (see gets.3s)
.sp
popen		initiate I/O to/from a process
	pclose	terminate I/O to/from a process (see popen.3s)
.sp
printf		formatted output conversion
	fprintf	formatted output conversion (see printf.3s)
	sprintf	formatted output conversion (see printf.3s)
.sp
putc		put character on a stream
	putchar	put character on a stream (see putc.3s)
	fputc	put character on a stream (see putc.3s)
	putw	put word on a stream (see putc.3s)
.sp
puts		put a string on a stream
	fputs	put a string on a stream (see puts.3s)
.sp
scanf		formatted input conversion
	fscanf	formatted input conversion (see scanf.3s)
	sscanf	formatted input conversion (see scanf.3s)
.sp
setbuf		assign buffering to a stream
	setbuffer	assign buffering to a stream (see setbuf.3s)
.sp
stdio		standard buffered input/output package
ungetc		push character back into input stream
.fi