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