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