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	.\" Redistribution and use in source and binary forms, with or without
	5	.\" modification, are permitted provided that the following conditions
	6	.\" are met:
	7	.\" 1. Redistributions of source code must retain the above copyright
	8	.\" notice, this list of conditions and the following disclaimer.
	9	.\" 2. Redistributions in binary form must reproduce the above copyright
	10	.\" notice, this list of conditions and the following disclaimer in the
	11	.\" documentation and/or other materials provided with the distribution.
	12	.\" 4. Neither the name of the University nor the names of its contributors
	13	.\" may be used to endorse or promote products derived from this software
	14	.\" without specific prior written permission.
	15	.\"
	16	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	17	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	18	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	19	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	20	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	21	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	22	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	23	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	24	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	25	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	26	.\" SUCH DAMAGE.
	27	.\"
	28	.\" @(#)fgetln.3 8.3 (Berkeley) 4/19/94
	29	.\" $FreeBSD: src/lib/libc/stdio/fgetln.3,v 1.10 2009/02/28 06:00:58 das Exp $
	30	.\"
	31	.Dd April 19, 1994
	32	.Dt FGETLN 3
	33	.Os
	34	.Sh NAME
	35	.Nm fgetln
	36	.Nd get a line from a stream
	37	.Sh LIBRARY
	38	.Lb libc
	39	.Sh SYNOPSIS
	40	.In stdio.h
	41	.Ft char *
	42	.Fn fgetln "FILE stream" "size_t len"
	43	.Sh DESCRIPTION
	44	The
	45	.Fn fgetln
	46	function
	47	returns a pointer to the next line from the stream referenced by
	48	.Fa stream .
	49	This line is
	50	.Em not
	51	a C string as it does not end with a terminating
	52	.Dv NUL
	53	character.
	54	The length of the line, including the final newline,
	55	is stored in the memory location to which
	56	.Fa len
	57	points.
	58	(Note, however, that if the line is the last
	59	in a file that does not end in a newline,
	60	the returned text will not contain a newline.)
	61	.Sh RETURN VALUES
	62	Upon successful completion a pointer is returned;
	63	this pointer becomes invalid after the next
	64	.Tn I/O
	65	operation on
	66	.Fa stream
	67	(whether successful or not)
	68	or as soon as the stream is closed.
	69	Otherwise,
	70	.Dv NULL
	71	is returned.
	72	The
	73	.Fn fgetln
	74	function
	75	does not distinguish between end-of-file and error; the routines
	76	.Xr feof 3
	77	and
	78	.Xr ferror 3
	79	must be used
	80	to determine which occurred.
	81	If an error occurs, the global variable
	82	.Va errno
	83	is set to indicate the error.
	84	The end-of-file condition is remembered, even on a terminal, and all
	85	subsequent attempts to read will return
	86	.Dv NULL
	87	until the condition is
	88	cleared with
	89	.Xr clearerr 3 .
	90	.Pp
	91	The text to which the returned pointer points may be modified,
	92	provided that no changes are made beyond the returned size.
	93	These changes are lost as soon as the pointer becomes invalid.
	94	.Sh ERRORS
	95	.Bl -tag -width Er
	96	.It Bq Er EBADF
	97	The argument
	98	.Fa stream
	99	is not a stream open for reading.
	100	.It Bq Er ENOMEM
	101	The internal line buffer could not be expanded due to lack of available memory,
	102	or because it would need to expand beyond INT_MAX in size.
	103	.El
	104	.Pp
	105	The
	106	.Fn fgetln
	107	function
	108	may also fail and set
	109	.Va errno
	110	for any of the errors specified for the routines
	111	.Xr fflush 3 ,
	112	.Xr malloc 3 ,
	113	.Xr read 2 ,
	114	.Xr stat 2 ,
	115	or
	116	.Xr realloc 3 .
	117	.Sh SEE ALSO
	118	.Xr ferror 3 ,
	119	.Xr fgets 3 ,
	120	.Xr fgetwln 3 ,
	121	.Xr fopen 3 ,
	122	.Xr getline 3 ,
	123	.Xr putc 3
	124	.Sh HISTORY
	125	The
	126	.Fn fgetln
	127	function first appeared in
	128	.Bx 4.4 .