git.saurik.com Git - apple/libc.git/blame_incremental

... / ...

Commit	Line	Data
	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.
	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
	33	.\" $FreeBSD: src/lib/libc/stdio/getc.3,v 1.21 2007/01/09 00:28:06 imp Exp $
	34	.\"
	35	.Dd January 10, 2003
	36	.Dt GETC 3
	37	.Os
	38	.Sh NAME
	39	.Nm fgetc ,
	40	.Nm getc ,
	41	.Nm getc_unlocked ,
	42	.Nm getchar ,
	43	.Nm getchar_unlocked ,
	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
	55	.Fn getc_unlocked "FILE *stream"
	56	.Ft int
	57	.Fn getchar "void"
	58	.Ft int
	59	.Fn getchar_unlocked "void"
	60	.Ft int
	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
	75	.Fn fgetc ,
	76	but is a macro that expands in-line.
	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
	88	.Vt int
	89	(if present)
	90	from the stream pointed at by
	91	.Fa stream .
	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.
	109	.Sh RETURN VALUES
	110	If successful, these routines return the next requested object
	111	from the
	112	.Fa stream .
	113	Character values are returned as an
	114	.Vt "unsigned char"
	115	converted to an
	116	.Vt int .
	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 ,
	135	.Xr flockfile 3 ,
	136	.Xr fopen 3 ,
	137	.Xr fread 3 ,
	138	.Xr getwc 3 ,
	139	.Xr putc 3 ,
	140	.Xr ungetc 3
	141	.Sh STANDARDS
	142	The
	143	.Fn fgetc ,
	144	.Fn getc ,
	145	and
	146	.Fn getchar
	147	functions
	148	conform to
	149	.St -isoC .
	150	The
	151	.Fn getc_unlocked
	152	and
	153	.Fn getchar_unlocked
	154	functions conform to
	155	.St -p1003.1-2001 .
	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
	166	.Vt int
	167	varies from one machine to another, and
	168	.Fn getw
	169	is not recommended for portable applications.
	170	.Pp