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

.\" Copyright (c) 1990, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" 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.
.\"
.\"     @(#)fgetln.3	8.3 (Berkeley) 4/19/94
.\" $FreeBSD: src/lib/libc/stdio/fgetln.3,v 1.10 2009/02/28 06:00:58 das Exp $
.\"
.Dd April 19, 1994
.Dt FGETLN 3
.Os
.Sh NAME
.Nm fgetln
.Nd get a line from a stream
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In stdio.h
.Ft char *
.Fn fgetln "FILE *stream" "size_t *len"
.Sh DESCRIPTION
The
.Fn fgetln
function
returns a pointer to the next line from the stream referenced by
.Fa stream .
This line is
.Em not
a C string as it does not end with a terminating
.Dv NUL
character.
The length of the line, including the final newline,
is stored in the memory location to which
.Fa len
points.
(Note, however, that if the line is the last
in a file that does not end in a newline,
the returned text will not contain a newline.)
.Sh RETURN VALUES
Upon successful completion a pointer is returned;
this pointer becomes invalid after the next
.Tn I/O
operation on
.Fa stream
(whether successful or not)
or as soon as the stream is closed.
Otherwise,
.Dv NULL
is returned.
The
.Fn fgetln
function
does not distinguish between end-of-file and error; the routines
.Xr feof 3
and
.Xr ferror 3
must be used
to determine which occurred.
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 NULL
until the condition is
cleared with
.Xr clearerr 3 .
.Pp
The text to which the returned pointer points may be modified,
provided that no changes are made beyond the returned size.
These changes are lost as soon as the pointer becomes invalid.
.Sh ERRORS
.Bl -tag -width Er
.It Bq Er EBADF
The argument
.Fa stream
is not a stream open for reading.
.It Bq Er ENOMEM
The internal line buffer could not be expanded due to lack of available memory,
or because it would need to expand beyond INT_MAX in size.
.El
.Pp
The
.Fn fgetln
function
may also fail and set
.Va errno
for any of the errors specified for the routines
.Xr fflush 3 ,
.Xr malloc 3 ,
.Xr read 2 ,
.Xr stat 2 ,
or
.Xr realloc 3 .
.Sh SEE ALSO
.Xr ferror 3 ,
.Xr fgets 3 ,
.Xr fgetwln 3 ,
.Xr fopen 3 ,
.Xr getline 3 ,
.Xr putc 3
.Sh HISTORY
The
.Fn fgetln
function first appeared in
.Bx 4.4 .
Commit	Line	Data
5b2abdfb	1	.\" Copyright (c) 1990, 1991, 1993
e9ce8d39 A	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.
e9ce8d39 A	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	.\"
5b2abdfb	28	.\" @(#)fgetln.3 8.3 (Berkeley) 4/19/94
1f2f436a	29	.\" $FreeBSD: src/lib/libc/stdio/fgetln.3,v 1.10 2009/02/28 06:00:58 das Exp $
e9ce8d39	30	.\"
5b2abdfb A	31	.Dd April 19, 1994
5b2abdfb A	32	.Dt FGETLN 3
e9ce8d39 A	33	.Os
e9ce8d39 A	34	.Sh NAME
5b2abdfb A	35	.Nm fgetln
5b2abdfb A	36	.Nd get a line from a stream
e9ce8d39 A	37	.Sh LIBRARY
	38	.Lb libc
	39	.Sh SYNOPSIS
5b2abdfb A	40	.In stdio.h
	41	.Ft char *
	42	.Fn fgetln "FILE stream" "size_t len"
e9ce8d39 A	43	.Sh DESCRIPTION
e9ce8d39 A	44	The
5b2abdfb A	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
e9ce8d39	56	.Fa len
5b2abdfb A	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.)
e9ce8d39	61	.Sh RETURN VALUES
5b2abdfb A	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.
e9ce8d39	94	.Sh ERRORS
e9ce8d39	95	.Bl -tag -width Er
5b2abdfb A	96	.It Bq Er EBADF
	97	The argument
	98	.Fa stream
	99	is not a stream open for reading.
ad3c9f2a A	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.
5b2abdfb A	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 .
e9ce8d39	117	.Sh SEE ALSO
5b2abdfb A	118	.Xr ferror 3 ,
5b2abdfb A	119	.Xr fgets 3 ,
3d9156a7	120	.Xr fgetwln 3 ,
5b2abdfb	121	.Xr fopen 3 ,
1f2f436a	122	.Xr getline 3 ,
5b2abdfb	123	.Xr putc 3
e9ce8d39 A	124	.Sh HISTORY
e9ce8d39 A	125	The
5b2abdfb	126	.Fn fgetln
e9ce8d39 A	127	function first appeared in
e9ce8d39 A	128	.Bx 4.4 .