[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
.Fd "#define _WITH_GETLINE"
.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 COMPATIBILITY
Many application writers used the name
.Va getline
before the
.Fn getline
function was introduced in
.St -p1003.1 ,
so a prototype is not provided by default in order to avoid
compatibility problems.
Applications that wish to use the
.Fn getline
function described herein should either request a strict
.St -p1003.1-2008
environment by defining the macro
.Dv _POSIX_C_SOURCE
to the value 200809 or greater, or by defining the macro
.Dv _WITH_GETLINE ,
prior to the inclusion of
.In stdio.h .
For compatibility with GNU libc, defining either
.Dv _BSD_SOURCE
or
.Dv _GNU_SOURCE
prior to the inclusion of
.In stdio.h
will also make
.Fn getline
available.
.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
	37	.Fd "#define _WITH_GETLINE"
	38	.In stdio.h
	39	.Ft ssize_t
	40	.Fn getdelim "char ** restrict linep" "size_t * restrict linecapp" "int delimiter" " FILE * restrict stream"
	41	.Ft ssize_t
	42	.Fn getline "char ** restrict linep" "size_t * restrict linecapp" " FILE * restrict stream"
	43	.Sh DESCRIPTION
	44	The
	45	.Fn getdelim
	46	function reads a line from
	47	.Fa stream ,
	48	delimited by the character
	49	.Fa delimiter .
	50	The
	51	.Fn getline
	52	function is equivalent to
	53	.Fn getdelim
	54	with the newline character as the delimiter.
	55	The delimiter character is included as part of the line, unless
	56	the end of the file is reached.
	57	The caller may provide a pointer to a malloc buffer for the line in
	58	.Fa *linep ,
	59	and the capacity of that buffer in
	60	.Fa *linecapp ;
	61	if
	62	.Fa *linecapp
	63	is 0, then
	64	.Fa *linep
65	is treated as
66	.Dv NULL .
67	These functions may expand the buffer as needed, as if via
68	.Fn realloc ,
69	and update
70	.Fa *linep
71	and
72	.Fa *linecapp
73	accordingly.
74	.Sh RETURN VALUES
75	The
76	.Fn getdelim
77	and
78	.Fn getline
79	functions return the number of characters written, excluding the
80	terminating
81	.Dv NULL .
82	The value \-1 is returned if an error occurs, or if end-of-file is reached.
83	.Sh EXAMPLES
84	The following code fragment reads lines from a file and
85	writes them to standard output.
86	The
87	.Fn fwrite
88	function is used in case the line contains embedded
89	.Dv NUL
90	characters.
91	.Bd -literal -offset indent
92	char *line = NULL;
93	size_t linecap = 0;
94	ssize_t linelen;
95	while ((linelen = getline(&line, &linecap, fp)) > 0)
96	fwrite(line, linelen, 1, stdout);
97	.Ed
98	.Sh COMPATIBILITY
99	Many application writers used the name
100	.Va getline
101	before the
102	.Fn getline
103	function was introduced in
104	.St -p1003.1 ,
105	so a prototype is not provided by default in order to avoid
106	compatibility problems.
107	Applications that wish to use the
108	.Fn getline
109	function described herein should either request a strict
110	.St -p1003.1-2008
111	environment by defining the macro
112	.Dv _POSIX_C_SOURCE
113	to the value 200809 or greater, or by defining the macro
114	.Dv _WITH_GETLINE ,
115	prior to the inclusion of
116	.In stdio.h .
117	For compatibility with GNU libc, defining either
118	.Dv _BSD_SOURCE
119	or
120	.Dv _GNU_SOURCE
121	prior to the inclusion of
122	.In stdio.h
123	will also make
124	.Fn getline
125	available.
126	.Sh ERRORS
127	These functions may fail if:
128	.Bl -tag -width Er
129	.It Bq Er EINVAL
130	Either
131	.Fa linep
132	or
133	.Fa linecapp
134	is
135	.Dv NULL .
136	.It Bq Er EOVERFLOW
137	No delimiter was found in the first
138	.Dv SSIZE_MAX
139	characters.
140	.El
141	.Pp
142	These functions may also fail for any of the errors specified for
143	.Fn fgets
144	and
145	.Fn malloc .
146	.Sh SEE ALSO
147	.Xr fgetln 3 ,
148	.Xr fgets 3 ,
149	.Xr malloc 3
150	.Sh STANDARDS
151	The
152	.Fn getdelim
153	and
154	.Fn getline
155	functions conform to
156	.St -p1003.1-2008 .
157	.Sh HISTORY
158	These routines first appeared in
159	.Fx 8.0 .
160	.Sh BUGS
161	There are no wide character versions of
162	.Fn getdelim
163	or
164	.Fn getline .