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

.\" Copyright (c) 2009 David Schultz <das@FreeBSD.org>
.\" 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.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 AUTHOR 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.
.\"
.\" $FreeBSD: src/lib/libc/stdio/getline.3,v 1.2 2009/04/06 13:50:04 das Exp $
.\"
.Dd March 29, 2009
.Dt GETLINE 3
.Os
.Sh NAME
.Nm getdelim ,
.Nm getline
.Nd get a line from a stream
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In stdio.h
.Ft ssize_t
.Fn getdelim "char ** restrict linep" "size_t * restrict linecapp" "int delimiter" " FILE * restrict stream"
.Ft ssize_t
.Fn getline "char ** restrict linep" "size_t * restrict linecapp" " FILE * restrict stream"
.Sh DESCRIPTION
The
.Fn getdelim
function reads a line from
.Fa stream ,
delimited by the character
.Fa delimiter .
The
.Fn getline
function is equivalent to
.Fn getdelim
with the newline character as the delimiter.
The delimiter character is included as part of the line, unless
the end of the file is reached.
The caller may provide a pointer to a malloc buffer for the line in
.Fa *linep ,
and the capacity of that buffer in
.Fa *linecapp ;
if
.Fa *linecapp
is 0, then
.Fa *linep
is treated as
.Dv NULL .
These functions may expand the buffer as needed, as if via
.Fn realloc ,
and update
.Fa *linep
and
.Fa *linecapp
accordingly.
.Sh RETURN VALUES
The
.Fn getdelim
and
.Fn getline
functions return the number of characters written, excluding the
terminating
.Dv NULL .
The value \-1 is returned if an error occurs, or if end-of-file is reached.
.Sh EXAMPLES
The following code fragment reads lines from a file and
writes them to standard output.
The
.Fn fwrite
function is used in case the line contains embedded
.Dv NUL
characters.
.Bd -literal -offset indent
char *line = NULL;
size_t linecap = 0;
ssize_t linelen;
while ((linelen = getline(&line, &linecap, fp)) > 0)
	fwrite(line, linelen, 1, stdout);
.Ed
.Sh ERRORS
These functions may fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
Either
.Fa linep
or
.Fa linecapp
is
.Dv NULL .
.It Bq Er EOVERFLOW
No delimiter was found in the first
.Dv SSIZE_MAX
characters.
.El
.Pp
These functions may also fail for any of the errors specified for
.Fn fgets
and
.Fn malloc .
.Sh SEE ALSO
.Xr fgetln 3 ,
.Xr fgets 3 ,
.Xr malloc 3
.Sh STANDARDS
The
.Fn getdelim
and
.Fn getline
functions conform to
.St -p1003.1-2008 .
.Sh HISTORY
These routines first appeared in
.Fx 8.0 .
.Sh BUGS
There are no wide character versions of
.Fn getdelim
or
.Fn getline .
Commit	Line	Data
1f2f436a A	1	.\" Copyright (c) 2009 David Schultz <das@FreeBSD.org>
	2	.\" 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	.\"
	13	.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
	14	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	15	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	16	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
	17	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	18	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	19	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	20	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	21	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	22	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	23	.\" SUCH DAMAGE.
	24	.\"
	25	.\" $FreeBSD: src/lib/libc/stdio/getline.3,v 1.2 2009/04/06 13:50:04 das Exp $
	26	.\"
	27	.Dd March 29, 2009
	28	.Dt GETLINE 3
	29	.Os
	30	.Sh NAME
	31	.Nm getdelim ,
	32	.Nm getline
	33	.Nd get a line from a stream
	34	.Sh LIBRARY
	35	.Lb libc
	36	.Sh SYNOPSIS
1f2f436a A	37	.In stdio.h
	38	.Ft ssize_t
	39	.Fn getdelim "char ** restrict linep" "size_t * restrict linecapp" "int delimiter" " FILE * restrict stream"
	40	.Ft ssize_t
	41	.Fn getline "char ** restrict linep" "size_t * restrict linecapp" " FILE * restrict stream"
	42	.Sh DESCRIPTION
	43	The
	44	.Fn getdelim
	45	function reads a line from
	46	.Fa stream ,
	47	delimited by the character
	48	.Fa delimiter .
	49	The
	50	.Fn getline
	51	function is equivalent to
	52	.Fn getdelim
	53	with the newline character as the delimiter.
	54	The delimiter character is included as part of the line, unless
	55	the end of the file is reached.
	56	The caller may provide a pointer to a malloc buffer for the line in
	57	.Fa *linep ,
	58	and the capacity of that buffer in
	59	.Fa *linecapp ;
	60	if
	61	.Fa *linecapp
	62	is 0, then
	63	.Fa *linep
	64	is treated as
	65	.Dv NULL .
	66	These functions may expand the buffer as needed, as if via
	67	.Fn realloc ,
	68	and update
	69	.Fa *linep
	70	and
	71	.Fa *linecapp
	72	accordingly.
	73	.Sh RETURN VALUES
	74	The
	75	.Fn getdelim
	76	and
	77	.Fn getline
	78	functions return the number of characters written, excluding the
	79	terminating
	80	.Dv NULL .
	81	The value \-1 is returned if an error occurs, or if end-of-file is reached.
	82	.Sh EXAMPLES
	83	The following code fragment reads lines from a file and
	84	writes them to standard output.
	85	The
	86	.Fn fwrite
	87	function is used in case the line contains embedded
	88	.Dv NUL
	89	characters.
	90	.Bd -literal -offset indent
	91	char *line = NULL;
	92	size_t linecap = 0;
	93	ssize_t linelen;
	94	while ((linelen = getline(&line, &linecap, fp)) > 0)
	95	fwrite(line, linelen, 1, stdout);
	96	.Ed
1f2f436a A	97	.Sh ERRORS
	98	These functions may fail if:
	99	.Bl -tag -width Er
	100	.It Bq Er EINVAL
	101	Either
	102	.Fa linep
	103	or
	104	.Fa linecapp
	105	is
	106	.Dv NULL .
	107	.It Bq Er EOVERFLOW
	108	No delimiter was found in the first
	109	.Dv SSIZE_MAX
	110	characters.
	111	.El
	112	.Pp
	113	These functions may also fail for any of the errors specified for
	114	.Fn fgets
	115	and
	116	.Fn malloc .
	117	.Sh SEE ALSO
	118	.Xr fgetln 3 ,
	119	.Xr fgets 3 ,
	120	.Xr malloc 3
	121	.Sh STANDARDS
	122	The
	123	.Fn getdelim
	124	and
	125	.Fn getline
	126	functions conform to
	127	.St -p1003.1-2008 .
	128	.Sh HISTORY
	129	These routines first appeared in
	130	.Fx 8.0 .
	131	.Sh BUGS
	132	There are no wide character versions of
	133	.Fn getdelim
	134	or
	135	.Fn getline .