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