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