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