1.\" $NetBSD: getdelim.3,v 1.14 2014/09/16 08:52:02 wiz Exp $ 2.\" 3.\" Copyright (c) 2009 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Roy Marples. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd September 15, 2014 31.Dt GETDELIM 3 32.Os 33.Sh NAME 34.Nm getdelim , 35.Nm getline 36.Nd read a delimited record from a stream 37.Sh LIBRARY 38.Lb libc 39.Sh SYNOPSIS 40.In stdio.h 41.Ft ssize_t 42.Fn getdelim "char ** restrict lineptr" "size_t * restrict n" "int delimiter" "FILE * restrict stream" 43.Ft ssize_t 44.Fn getline "char ** restrict lineptr" "size_t * restrict n" "FILE * restrict stream" 45.Sh DESCRIPTION 46The 47.Fn getdelim 48function reads from the 49.Fa stream 50until it encounters a character matching 51.Fa delimiter 52or 53.Dv EOF , 54storing the input in 55.Fa *lineptr . 56The buffer is 57.Dv NUL Ns No -terminated 58and includes the delimiter, if one was found. 59The 60.Fa delimiter 61character must be representable as an unsigned char. 62.Pp 63If 64.Fa *n 65is non-zero, then 66.Fa *lineptr 67must be pre-allocated to at least 68.Fa *n 69bytes. 70The buffer should be allocated dynamically; 71it must be possible to 72.Xr free 3 73.Fa *lineptr . 74.Fn getdelim 75ensures that 76.Fa *lineptr 77is large enough to hold the input, updating 78.Fa *n 79to reflect the new size. 80.Pp 81The 82.Fn getline 83function is equivalent to 84.Fn getdelim 85with 86.Fa delimiter 87set to the newline character. 88.Sh RETURN VALUES 89The 90.Fn getdelim 91and 92.Fn getline 93functions return the number of characters read, including the delimiter if 94one was found. 95If no characters were read and the stream is at end-of-file, the functions 96return \-1. 97If an error occurs, the functions return \-1 and the global variable 98.Va errno 99is set to indicate the error. 100.Pp 101The functions do not distinguish between end-of-file and error, 102and callers must use 103.Xr feof 3 104and 105.Xr ferror 3 106to determine which occurred. 107.Sh EXAMPLES 108The following code fragment reads lines from a file and writes them to 109standard output. 110.Bd -literal -offset indent 111char *line = NULL; 112size_t linesize = 0; 113ssize_t linelen; 114 115while ((linelen = getline(\*[Am]line, \*[Am]linesize, fp)) != -1) 116 fwrite(line, linelen, 1, stdout); 117 118if (ferror(fp)) 119 perror("getline"); 120.Ed 121.Sh ERRORS 122.Bl -tag -width [EOVERFLOW] 123.It Bq Er EINVAL 124.Fa lineptr 125or 126.Fa n 127is a 128.Dv NULL 129pointer. 130.It Bq Er EOVERFLOW 131More than SSIZE_MAX characters were read without encountering the delimiter. 132.El 133.Pp 134The 135.Fn getdelim 136and 137.Fn getline 138functions may also fail and set 139.Va errno 140for any of the errors specified in the routines 141.Xr fflush 3 , 142.Xr malloc 3 , 143.Xr read 2 , 144.Xr stat 2 , 145or 146.Xr realloc 3 . 147.Sh SEE ALSO 148.Xr ferror 3 , 149.Xr fgets 3 , 150.Xr fopen 3 , 151.Xr strlen 3 152.Sh STANDARDS 153The 154.Fn getdelim 155and 156.Fn getline 157functions conform to 158.St -p1003.1-2008 . 159.Sh NOTES 160The 161.Fn getdelim 162and 163.Fn getline 164functions can return results that include 165.Dv NUL 166characters, which can cause the apparent length reported by 167.Xr strlen 3 168to be less than the true length reported by the 169return values of the functions. 170