usr/src/lib/libc/stdio/stdio.3

.\" Copyright (c) 1980 Regents of the University of California.
.\" All rights reserved.  The Berkeley software License Agreement
.\" specifies the terms and conditions for redistribution.
.\"
.\"	@(#)stdio.3	6.2 (Berkeley) %G%
.\"
.TH STDIO 3S ""
.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
.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
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.
.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
Commit	Line	Data
	1	.\" Copyright (c) 1980 Regents of the University of California.
	2	.\" All rights reserved. The Berkeley software License Agreement
	3	.\" specifies the terms and conditions for redistribution.
	4	.\"
	5	.\" @(#)stdio.3 6.2 (Berkeley) %G%
	6	.\"
	7	.TH STDIO 3S ""
	8	.UC 4
	9	.SH NAME
	10	stdio \- standard buffered input/output package
	11	.SH SYNOPSIS
	12	.B #include <stdio.h>
	13	.PP
	14	.SM
	15	.B FILE
	16	.B *stdin;
	17	.br
	18	.SM
	19	.B FILE
	20	.B *stdout;
	21	.br
	22	.SM
	23	.B FILE
	24	.B *stderr;
	25	.SH DESCRIPTION
	26	The functions described in section 3S constitute a user-level buffering
	27	scheme. The in-line macros
	28	.I getc
	29	and
	30	.IR putc (3S)
	31	handle characters quickly. The higher level routines
	32	.IR gets ,
	33	.IR fgets ,
	34	.IR scanf ,
	35	.IR fscanf ,
	36	.IR fread ,
	37	.IR puts ,
	38	.IR fputs ,
	39	.IR printf ,
	40	.IR fprintf ,
	41	.IR fwrite
	42	all use
	43	.I getc
	44	and
	45	.IR putc ;
	46	they can be freely intermixed.
	47	.PP
	48	A file with associated buffering is called a
	49	.IR stream ,
	50	and is declared to be a pointer to a defined type
	51	.SM
	52	.BR FILE .
	53	.IR Fopen (3S)
	54	creates certain descriptive data for a stream
	55	and returns a pointer to designate the stream in all further transactions.
	56	There are three normally open streams with constant pointers declared in
	57	the include file and associated with the standard open files:
	58	.TP 10n
	59	.B stdin
	60	standard input file
	61	.br
	62	.ns
	63	.TP
	64	.B stdout
	65	standard output file
	66	.br
	67	.ns
	68	.TP
	69	.B stderr
	70	standard error file
	71	.PP
	72	A constant `pointer'
	73	.SM
	74	.B NULL
	75	(0)
	76	designates no stream at all.
	77	.PP
	78	An integer constant
	79	.SM
	80	.B EOF
	81	(\-1) is returned upon end of file or error by integer functions that
	82	deal with streams.
	83	.PP
	84	Any routine that uses the standard input/output package
	85	must include the header file
	86	.RI < stdio.h >
	87	of pertinent macro definitions.
	88	The functions and constants mentioned in sections labeled 3S
	89	are declared in the include file and need no further declaration.
	90	The constants, and the following `functions' are
	91	implemented as macros; redeclaration of these names is perilous:
	92	.IR getc ,
	93	.IR getchar ,
	94	.IR putc ,
	95	.IR putchar ,
	96	.IR feof ,
	97	.IR ferror ,
	98	.IR fileno .
	99	.SH "SEE ALSO"
	100	open(2), close(2), read(2), write(2), fread(3S), fseek(3S), f*(3S)
	101	.SH DIAGNOSTICS
	102	The value
	103	.SM
	104	.B EOF
	105	is returned uniformly to indicate that a
	106	.SM
	107	.B FILE
	108	pointer has not been initialized with
	109	.IR fopen ,
	110	input (output) has been attempted on an output (input) stream, or a
	111	.SM
	112	.B FILE
	113	pointer designates corrupt or otherwise unintelligible
	114	.SM
	115	.B FILE
	116	data.
	117	.PP
	118	For purposes of efficiency, this implementation of the standard library
	119	has been changed to line buffer output to a terminal by default and attempts
	120	to do this transparently by flushing the output whenever a
	121	.IR read (2)
	122	from the standard input is necessary. This is almost always transparent,
	123	but may cause confusion or malfunctioning of programs which use
	124	standard i/o routines but use
	125	.IR read (2)
	126	themselves to read from the standard input.
	127	.PP
	128	In cases where a large amount of computation is done after printing
	129	part of a line on an output terminal, it is necessary to
	130	.IR fflush (3S)
	131	the standard output before going off and computing so that the output
	132	will appear.
	133	.SH BUGS
	134	The standard buffered functions do not interact well with certain other
	135	library and system functions, especially \fIvfork\fP and \fIabort\fP.
	136	.SH "LIST OF FUNCTIONS"
	137	.sp 2
	138	.nf
	139	.ta \w'setlinebuf'u+2n +\w'setbuf.3s'u+10n
	140	\fIName\fP \fIAppears on Page\fP \fIDescription\fP
	141	.ta \w'setlinebuf'u+4n +\w'setbuf.3s'u+4n
	142	.sp 5p
	143	clearerr ferror.3s stream status inquiries
	144	fclose fclose.3s close or flush a stream
	145	fdopen fopen.3s open a stream
	146	feof ferror.3s stream status inquiries
	147	ferror ferror.3s stream status inquiries
	148	fflush fclose.3s close or flush a stream
	149	fgetc getc.3s get character or word from stream
	150	fgets gets.3s get a string from a stream
	151	fileno ferror.3s stream status inquiries
	152	fopen fopen.3s open a stream
	153	fprintf printf.3s formatted output conversion
	154	fputc putc.3s put character or word on a stream
	155	fputs puts.3s put a string on a stream
	156	fread fread.3s buffered binary input/output
	157	freopen fopen.3s open a stream
	158	fscanf scanf.3s formatted input conversion
	159	fseek fseek.3s reposition a stream
	160	ftell fseek.3s reposition a stream
	161	fwrite fread.3s buffered binary input/output
	162	getc getc.3s get character or word from stream
	163	getchar getc.3s get character or word from stream
	164	gets gets.3s get a string from a stream
	165	getw getc.3s get character or word from stream
	166	printf printf.3s formatted output conversion
	167	putc putc.3s put character or word on a stream
	168	putchar putc.3s put character or word on a stream
	169	puts puts.3s put a string on a stream
	170	putw putc.3s put character or word on a stream
	171	rewind fseek.3s reposition a stream
	172	scanf scanf.3s formatted input conversion
	173	setbuf setbuf.3s assign buffering to a stream
	174	setbuffer setbuf.3s assign buffering to a stream
	175	setlinebuf setbuf.3s assign buffering to a stream
	176	sprintf printf.3s formatted output conversion
	177	sscanf scanf.3s formatted input conversion
	178	ungetc ungetc.3s push character back into input stream
	179	.fi