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.Dd July 30, 2016 26.Dt GETLINE 3 27.Os 28.Sh NAME 29.Nm getdelim , 30.Nm getline 31.Nd get a line from a stream 32.Sh LIBRARY 33.Lb libc 34.Sh SYNOPSIS 35.In stdio.h 36.Ft ssize_t 37.Fn getdelim "char ** restrict linep" "size_t * restrict linecapp" "int delimiter" " FILE * restrict stream" 38.Ft ssize_t 39.Fn getline "char ** restrict linep" "size_t * restrict linecapp" " FILE * restrict stream" 40.Sh DESCRIPTION 41The 42.Fn getdelim 43function reads a line from 44.Fa stream , 45delimited by the character 46.Fa delimiter . 47The 48.Fn getline 49function is equivalent to 50.Fn getdelim 51with the newline character as the delimiter. 52The delimiter character is included as part of the line, unless 53the end of the file is reached. 54.Pp 55The caller may provide a pointer to a malloced buffer for the line in 56.Fa *linep , 57and the capacity of that buffer in 58.Fa *linecapp . 59These functions expand the buffer as needed, as if via 60.Fn realloc . 61If 62.Fa linep 63points to a 64.Dv NULL 65pointer, a new buffer will be allocated. 66In either case, 67.Fa *linep 68and 69.Fa *linecapp 70will be updated accordingly. 71.Sh RETURN VALUES 72The 73.Fn getdelim 74and 75.Fn getline 76functions return the number of characters stored in the buffer, excluding the 77terminating 78.Dv NUL 79character. 80The value \-1 is returned if an error occurs, or if end-of-file is reached. 81.Sh EXAMPLES 82The following code fragment reads lines from a file and 83writes them to standard output. 84The 85.Fn fwrite 86function is used in case the line contains embedded 87.Dv NUL 88characters. 89.Bd -literal -offset indent 90char *line = NULL; 91size_t linecap = 0; 92ssize_t linelen; 93while ((linelen = getline(&line, &linecap, fp)) > 0) 94 fwrite(line, linelen, 1, stdout); 95free(line); 96.Ed 97.Sh ERRORS 98These functions may fail if: 99.Bl -tag -width Er 100.It Bq Er EINVAL 101Either 102.Fa linep 103or 104.Fa linecapp 105is 106.Dv NULL . 107.It Bq Er EOVERFLOW 108No delimiter was found in the first 109.Dv SSIZE_MAX 110characters. 111.El 112.Pp 113These functions may also fail due to any of the errors specified for 114.Fn fgets 115and 116.Fn malloc . 117.Sh SEE ALSO 118.Xr fgetln 3 , 119.Xr fgets 3 , 120.Xr malloc 3 121.Sh STANDARDS 122The 123.Fn getdelim 124and 125.Fn getline 126functions conform to 127.St -p1003.1-2008 . 128.Sh HISTORY 129These routines first appeared in 130.Fx 8.0 . 131.Sh BUGS 132There are no wide character versions of 133.Fn getdelim 134or 135.Fn getline . 136