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