xref: /freebsd/lib/libc/stdio/getline.3 (revision 8c039ae1549bf4c7529709ab4d474e08ac92b232)
169099ba2SDavid Schultz.\" Copyright (c) 2009 David Schultz <das@FreeBSD.org>
269099ba2SDavid Schultz.\" All rights reserved.
369099ba2SDavid Schultz.\"
469099ba2SDavid Schultz.\" Redistribution and use in source and binary forms, with or without
569099ba2SDavid Schultz.\" modification, are permitted provided that the following conditions
669099ba2SDavid Schultz.\" are met:
769099ba2SDavid Schultz.\" 1. Redistributions of source code must retain the above copyright
869099ba2SDavid Schultz.\"    notice, this list of conditions and the following disclaimer.
969099ba2SDavid Schultz.\" 2. Redistributions in binary form must reproduce the above copyright
1069099ba2SDavid Schultz.\"    notice, this list of conditions and the following disclaimer in the
1169099ba2SDavid Schultz.\"    documentation and/or other materials provided with the distribution.
1269099ba2SDavid Schultz.\"
1369099ba2SDavid Schultz.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
1469099ba2SDavid Schultz.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
1569099ba2SDavid Schultz.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
1669099ba2SDavid Schultz.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
1769099ba2SDavid Schultz.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
1869099ba2SDavid Schultz.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
1969099ba2SDavid Schultz.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
2069099ba2SDavid Schultz.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
2169099ba2SDavid Schultz.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
2269099ba2SDavid Schultz.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
2369099ba2SDavid Schultz.\" SUCH DAMAGE.
2469099ba2SDavid Schultz.\"
2569099ba2SDavid Schultz.\" $FreeBSD$
2669099ba2SDavid Schultz.\"
27*8c039ae1SEitan Adler.Dd November 30, 2012
2869099ba2SDavid Schultz.Dt GETLINE 3
2969099ba2SDavid Schultz.Os
3069099ba2SDavid Schultz.Sh NAME
3169099ba2SDavid Schultz.Nm getdelim ,
3269099ba2SDavid Schultz.Nm getline
3369099ba2SDavid Schultz.Nd get a line from a stream
3469099ba2SDavid Schultz.Sh LIBRARY
3569099ba2SDavid Schultz.Lb libc
3669099ba2SDavid Schultz.Sh SYNOPSIS
3769099ba2SDavid Schultz.Fd "#define _WITH_GETLINE"
3869099ba2SDavid Schultz.In stdio.h
3969099ba2SDavid Schultz.Ft ssize_t
4069099ba2SDavid Schultz.Fn getdelim "char ** restrict linep" "size_t * restrict linecapp" "int delimiter" " FILE * restrict stream"
4169099ba2SDavid Schultz.Ft ssize_t
4269099ba2SDavid Schultz.Fn getline "char ** restrict linep" "size_t * restrict linecapp" " FILE * restrict stream"
4369099ba2SDavid Schultz.Sh DESCRIPTION
4469099ba2SDavid SchultzThe
4569099ba2SDavid Schultz.Fn getdelim
4669099ba2SDavid Schultzfunction reads a line from
4769099ba2SDavid Schultz.Fa stream ,
4869099ba2SDavid Schultzdelimited by the character
4969099ba2SDavid Schultz.Fa delimiter .
5069099ba2SDavid SchultzThe
5169099ba2SDavid Schultz.Fn getline
5269099ba2SDavid Schultzfunction is equivalent to
5369099ba2SDavid Schultz.Fn getdelim
5469099ba2SDavid Schultzwith the newline character as the delimiter.
5569099ba2SDavid SchultzThe delimiter character is included as part of the line, unless
5669099ba2SDavid Schultzthe end of the file is reached.
5706127c9cSDavid Schultz.Pp
5806127c9cSDavid SchultzThe caller may provide a pointer to a malloced buffer for the line in
5969099ba2SDavid Schultz.Fa *linep ,
6069099ba2SDavid Schultzand the capacity of that buffer in
6106127c9cSDavid Schultz.Fa *linecapp .
6206127c9cSDavid SchultzThese functions expand the buffer as needed, as if via
6306127c9cSDavid Schultz.Fn realloc .
6406127c9cSDavid SchultzIf
6506127c9cSDavid Schultz.Fa linep
6606127c9cSDavid Schultzpoints to a
6706127c9cSDavid Schultz.Dv NULL
6806127c9cSDavid Schultzpointer, a new buffer will be allocated.
6906127c9cSDavid SchultzIn either case,
7069099ba2SDavid Schultz.Fa *linep
7169099ba2SDavid Schultzand
7269099ba2SDavid Schultz.Fa *linecapp
7306127c9cSDavid Schultzwill be updated accordingly.
7469099ba2SDavid Schultz.Sh RETURN VALUES
7569099ba2SDavid SchultzThe
7669099ba2SDavid Schultz.Fn getdelim
7769099ba2SDavid Schultzand
7869099ba2SDavid Schultz.Fn getline
79*8c039ae1SEitan Adlerfunctions return the number of characters stored in the buffer, excluding the
8069099ba2SDavid Schultzterminating
815d26f10fSMatteo Riondato.Dv NUL
825d26f10fSMatteo Riondatocharacter.
836685ac34SDavid SchultzThe value \-1 is returned if an error occurs, or if end-of-file is reached.
8469099ba2SDavid Schultz.Sh EXAMPLES
8569099ba2SDavid SchultzThe following code fragment reads lines from a file and
8669099ba2SDavid Schultzwrites them to standard output.
8769099ba2SDavid SchultzThe
8869099ba2SDavid Schultz.Fn fwrite
8969099ba2SDavid Schultzfunction is used in case the line contains embedded
9069099ba2SDavid Schultz.Dv NUL
9169099ba2SDavid Schultzcharacters.
9269099ba2SDavid Schultz.Bd -literal -offset indent
9369099ba2SDavid Schultzchar *line = NULL;
9469099ba2SDavid Schultzsize_t linecap = 0;
9569099ba2SDavid Schultzssize_t linelen;
9669099ba2SDavid Schultzwhile ((linelen = getline(&line, &linecap, fp)) > 0)
9769099ba2SDavid Schultz	fwrite(line, linelen, 1, stdout);
9869099ba2SDavid Schultz.Ed
9969099ba2SDavid Schultz.Sh COMPATIBILITY
10069099ba2SDavid SchultzMany application writers used the name
10169099ba2SDavid Schultz.Va getline
10269099ba2SDavid Schultzbefore the
10369099ba2SDavid Schultz.Fn getline
10469099ba2SDavid Schultzfunction was introduced in
10569099ba2SDavid Schultz.St -p1003.1 ,
10669099ba2SDavid Schultzso a prototype is not provided by default in order to avoid
10769099ba2SDavid Schultzcompatibility problems.
10869099ba2SDavid SchultzApplications that wish to use the
10969099ba2SDavid Schultz.Fn getline
11069099ba2SDavid Schultzfunction described herein should either request a strict
11169099ba2SDavid Schultz.St -p1003.1-2008
11269099ba2SDavid Schultzenvironment by defining the macro
11369099ba2SDavid Schultz.Dv _POSIX_C_SOURCE
11469099ba2SDavid Schultzto the value 200809 or greater, or by defining the macro
11569099ba2SDavid Schultz.Dv _WITH_GETLINE ,
11669099ba2SDavid Schultzprior to the inclusion of
11769099ba2SDavid Schultz.In stdio.h .
11869099ba2SDavid SchultzFor compatibility with GNU libc, defining either
11969099ba2SDavid Schultz.Dv _BSD_SOURCE
12069099ba2SDavid Schultzor
12169099ba2SDavid Schultz.Dv _GNU_SOURCE
12269099ba2SDavid Schultzprior to the inclusion of
12369099ba2SDavid Schultz.In stdio.h
12469099ba2SDavid Schultzwill also make
12569099ba2SDavid Schultz.Fn getline
12669099ba2SDavid Schultzavailable.
12769099ba2SDavid Schultz.Sh ERRORS
12869099ba2SDavid SchultzThese functions may fail if:
12969099ba2SDavid Schultz.Bl -tag -width Er
13069099ba2SDavid Schultz.It Bq Er EINVAL
13169099ba2SDavid SchultzEither
13269099ba2SDavid Schultz.Fa linep
13369099ba2SDavid Schultzor
13469099ba2SDavid Schultz.Fa linecapp
13569099ba2SDavid Schultzis
13669099ba2SDavid Schultz.Dv NULL .
13769099ba2SDavid Schultz.It Bq Er EOVERFLOW
13869099ba2SDavid SchultzNo delimiter was found in the first
13969099ba2SDavid Schultz.Dv SSIZE_MAX
14069099ba2SDavid Schultzcharacters.
14169099ba2SDavid Schultz.El
14269099ba2SDavid Schultz.Pp
14306127c9cSDavid SchultzThese functions may also fail due to any of the errors specified for
14469099ba2SDavid Schultz.Fn fgets
14569099ba2SDavid Schultzand
14669099ba2SDavid Schultz.Fn malloc .
14769099ba2SDavid Schultz.Sh SEE ALSO
14869099ba2SDavid Schultz.Xr fgetln 3 ,
14969099ba2SDavid Schultz.Xr fgets 3 ,
15069099ba2SDavid Schultz.Xr malloc 3
15169099ba2SDavid Schultz.Sh STANDARDS
15269099ba2SDavid SchultzThe
15369099ba2SDavid Schultz.Fn getdelim
15469099ba2SDavid Schultzand
15569099ba2SDavid Schultz.Fn getline
15669099ba2SDavid Schultzfunctions conform to
15769099ba2SDavid Schultz.St -p1003.1-2008 .
15869099ba2SDavid Schultz.Sh HISTORY
15969099ba2SDavid SchultzThese routines first appeared in
16069099ba2SDavid Schultz.Fx 8.0 .
16169099ba2SDavid Schultz.Sh BUGS
16269099ba2SDavid SchultzThere are no wide character versions of
16369099ba2SDavid Schultz.Fn getdelim
16469099ba2SDavid Schultzor
16569099ba2SDavid Schultz.Fn getline .
166