[apple/libc.git] / stdio / FreeBSD / getc.3

.\" Copyright (c) 1990, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" Chris Torek and the American National Standards Committee X3,
.\" on Information Processing Systems.
.\"
.\" 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.
.\" 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.
.\"
.\"     @(#)getc.3	8.1 (Berkeley) 6/4/93
.\" $FreeBSD: src/lib/libc/stdio/getc.3,v 1.21 2007/01/09 00:28:06 imp Exp $
.\"
.Dd January 10, 2003
.Dt GETC 3
.Os
.Sh NAME
.Nm fgetc ,
.Nm getc ,
.Nm getc_unlocked ,
.Nm getchar ,
.Nm getchar_unlocked ,
.Nm getw
.Nd get next character or word from input stream
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In stdio.h
.Ft int
.Fn fgetc "FILE *stream"
.Ft int
.Fn getc "FILE *stream"
.Ft int
.Fn getc_unlocked "FILE *stream"
.Ft int
.Fn getchar "void"
.Ft int
.Fn getchar_unlocked "void"
.Ft int
.Fn getw "FILE *stream"
.Sh DESCRIPTION
The
.Fn fgetc
function
obtains the next input character (if present) from the stream pointed at by
.Fa stream ,
or the next character pushed back on the stream via
.Xr ungetc 3 .
.Pp
The
.Fn getc
function
acts essentially identically to
.Fn fgetc ,
but is a macro that expands in-line.
.Pp
The
.Fn getchar
function
is equivalent to
.Fn getc stdin .
.Pp
The
.Fn getw
function
obtains the next
.Vt int
(if present)
from the stream pointed at by
.Fa stream .
.Pp
The
.Fn getc_unlocked
and
.Fn getchar_unlocked
functions are equivalent to
.Fn getc
and
.Fn getchar
respectively,
except that the caller is responsible for locking the stream
with
.Xr flockfile 3
before calling them.
These functions may be used to avoid the overhead of locking the stream
for each character, and to avoid input being dispersed among multiple
threads reading from the same stream.
.Sh RETURN VALUES
If successful, these routines return the next requested object
from the
.Fa stream .
Character values are returned as an
.Vt "unsigned char"
converted to an
.Vt int .
If the stream is at end-of-file or a read error occurs,
the routines return
.Dv EOF .
The routines
.Xr feof 3
and
.Xr ferror 3
must be used to distinguish between end-of-file and error.
If an error occurs, the global variable
.Va errno
is set to indicate the error.
The end-of-file condition is remembered, even on a terminal, and all
subsequent attempts to read will return
.Dv EOF
until the condition is cleared with
.Xr clearerr 3 .
.Sh SEE ALSO
.Xr ferror 3 ,
.Xr flockfile 3 ,
.Xr fopen 3 ,
.Xr fread 3 ,
.Xr getwc 3 ,
.Xr putc 3 ,
.Xr ungetc 3
.Sh STANDARDS
The
.Fn fgetc ,
.Fn getc ,
and
.Fn getchar
functions
conform to
.St -isoC .
The
.Fn getc_unlocked
and
.Fn getchar_unlocked
functions conform to
.St -p1003.1-2001 .
.Sh BUGS
Since
.Dv EOF
is a valid integer value,
.Xr feof 3
and
.Xr ferror 3
must be used to check for failure after calling
.Fn getw .
The size and byte order of an
.Vt int
varies from one machine to another, and
.Fn getw
is not recommended for portable applications.
.Pp
Commit	Line	Data
5b2abdfb A	1	.\" Copyright (c) 1990, 1991, 1993
	2	.\" The Regents of the University of California. All rights reserved.
	3	.\"
	4	.\" This code is derived from software contributed to Berkeley by
	5	.\" Chris Torek and the American National Standards Committee X3,
	6	.\" on Information Processing Systems.
	7	.\"
	8	.\" Redistribution and use in source and binary forms, with or without
	9	.\" modification, are permitted provided that the following conditions
	10	.\" are met:
	11	.\" 1. Redistributions of source code must retain the above copyright
	12	.\" notice, this list of conditions and the following disclaimer.
	13	.\" 2. Redistributions in binary form must reproduce the above copyright
	14	.\" notice, this list of conditions and the following disclaimer in the
	15	.\" documentation and/or other materials provided with the distribution.
5b2abdfb A	16	.\" 4. Neither the name of the University nor the names of its contributors
	17	.\" may be used to endorse or promote products derived from this software
	18	.\" without specific prior written permission.
	19	.\"
	20	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	21	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	22	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	23	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	24	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	25	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	26	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	27	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	28	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	29	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	30	.\" SUCH DAMAGE.
	31	.\"
	32	.\" @(#)getc.3 8.1 (Berkeley) 6/4/93
1f2f436a	33	.\" $FreeBSD: src/lib/libc/stdio/getc.3,v 1.21 2007/01/09 00:28:06 imp Exp $
5b2abdfb	34	.\"
9385eb3d	35	.Dd January 10, 2003
5b2abdfb A	36	.Dt GETC 3
	37	.Os
	38	.Sh NAME
	39	.Nm fgetc ,
	40	.Nm getc ,
9385eb3d	41	.Nm getc_unlocked ,
5b2abdfb	42	.Nm getchar ,
9385eb3d	43	.Nm getchar_unlocked ,
5b2abdfb A	44	.Nm getw
	45	.Nd get next character or word from input stream
	46	.Sh LIBRARY
	47	.Lb libc
	48	.Sh SYNOPSIS
	49	.In stdio.h
	50	.Ft int
	51	.Fn fgetc "FILE *stream"
	52	.Ft int
	53	.Fn getc "FILE *stream"
	54	.Ft int
9385eb3d A	55	.Fn getc_unlocked "FILE *stream"
9385eb3d A	56	.Ft int
ad3c9f2a	57	.Fn getchar "void"
5b2abdfb	58	.Ft int
3d9156a7	59	.Fn getchar_unlocked "void"
9385eb3d	60	.Ft int
5b2abdfb A	61	.Fn getw "FILE *stream"
	62	.Sh DESCRIPTION
	63	The
	64	.Fn fgetc
	65	function
	66	obtains the next input character (if present) from the stream pointed at by
	67	.Fa stream ,
	68	or the next character pushed back on the stream via
	69	.Xr ungetc 3 .
	70	.Pp
	71	The
	72	.Fn getc
	73	function
	74	acts essentially identically to
3d9156a7 A	75	.Fn fgetc ,
3d9156a7 A	76	but is a macro that expands in-line.
5b2abdfb A	77	.Pp
	78	The
	79	.Fn getchar
	80	function
	81	is equivalent to
	82	.Fn getc stdin .
	83	.Pp
	84	The
	85	.Fn getw
	86	function
	87	obtains the next
9385eb3d	88	.Vt int
5b2abdfb A	89	(if present)
	90	from the stream pointed at by
	91	.Fa stream .
9385eb3d A	92	.Pp
	93	The
	94	.Fn getc_unlocked
	95	and
	96	.Fn getchar_unlocked
	97	functions are equivalent to
	98	.Fn getc
	99	and
	100	.Fn getchar
	101	respectively,
	102	except that the caller is responsible for locking the stream
	103	with
	104	.Xr flockfile 3
	105	before calling them.
	106	These functions may be used to avoid the overhead of locking the stream
	107	for each character, and to avoid input being dispersed among multiple
	108	threads reading from the same stream.
5b2abdfb A	109	.Sh RETURN VALUES
	110	If successful, these routines return the next requested object
	111	from the
	112	.Fa stream .
9385eb3d A	113	Character values are returned as an
	114	.Vt "unsigned char"
	115	converted to an
	116	.Vt int .
5b2abdfb A	117	If the stream is at end-of-file or a read error occurs,
	118	the routines return
	119	.Dv EOF .
	120	The routines
	121	.Xr feof 3
	122	and
	123	.Xr ferror 3
	124	must be used to distinguish between end-of-file and error.
	125	If an error occurs, the global variable
	126	.Va errno
	127	is set to indicate the error.
	128	The end-of-file condition is remembered, even on a terminal, and all
	129	subsequent attempts to read will return
	130	.Dv EOF
	131	until the condition is cleared with
	132	.Xr clearerr 3 .
	133	.Sh SEE ALSO
	134	.Xr ferror 3 ,
9385eb3d	135	.Xr flockfile 3 ,
5b2abdfb A	136	.Xr fopen 3 ,
5b2abdfb A	137	.Xr fread 3 ,
9385eb3d	138	.Xr getwc 3 ,
5b2abdfb A	139	.Xr putc 3 ,
	140	.Xr ungetc 3
	141	.Sh STANDARDS
	142	The
	143	.Fn fgetc ,
ad3c9f2a	144	.Fn getc ,
5b2abdfb A	145	and
	146	.Fn getchar
	147	functions
	148	conform to
	149	.St -isoC .
9385eb3d A	150	The
	151	.Fn getc_unlocked
	152	and
	153	.Fn getchar_unlocked
	154	functions conform to
	155	.St -p1003.1-2001 .
5b2abdfb A	156	.Sh BUGS
	157	Since
	158	.Dv EOF
	159	is a valid integer value,
	160	.Xr feof 3
	161	and
	162	.Xr ferror 3
	163	must be used to check for failure after calling
	164	.Fn getw .
	165	The size and byte order of an
9385eb3d	166	.Vt int
5b2abdfb A	167	varies from one machine to another, and
	168	.Fn getw
	169	is not recommended for portable applications.
	170	.Pp