1.\" $OpenBSD: getdelim.3,v 1.7 2022/12/20 17:59:29 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: December 20 2022 $ 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 61.Vt 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 75will 76.Xr realloc 3 77.Fa *lineptr 78as necessary, updating 79.Fa *n 80to reflect the new size. 81It is the responsibility of the caller to 82.Xr free 3 83.Fa *lineptr 84when it is no longer needed. 85Even when it fails, 86.Fn getdelim 87may update 88.Fa *lineptr . 89.Pp 90The 91.Fn getline 92function is equivalent to 93.Fn getdelim 94with 95.Fa delimiter 96set to the newline character. 97.Sh RETURN VALUES 98The 99.Fn getdelim 100and 101.Fn getline 102functions return the number of characters read, including the delimiter. 103If no characters were read and the stream is at end-of-file, the functions 104return \-1. 105If an error occurs, the functions return \-1 and the global variable 106.Va errno 107is set to indicate the error. 108.Pp 109The functions do not distinguish between end-of-file and error, 110and callers must use 111.Xr feof 3 112and 113.Xr ferror 3 114to determine which occurred. 115.Sh EXAMPLES 116The following code fragment reads lines from a file and writes them to 117standard output. 118.Bd -literal -offset indent 119char *line = NULL; 120size_t linesize = 0; 121ssize_t linelen; 122 123while ((linelen = getline(\*[Am]line, \*[Am]linesize, fp)) != -1) 124 fwrite(line, linelen, 1, stdout); 125 126free(line); 127if (ferror(fp)) 128 err(1, "getline"); 129.Ed 130.Sh ERRORS 131.Bl -tag -width [EOVERFLOW] 132.It Bq Er EINVAL 133.Fa lineptr 134or 135.Fa n 136is a 137.Dv NULL 138pointer. 139.It Bq Er EOVERFLOW 140More than SSIZE_MAX characters were read without encountering the delimiter. 141.El 142.Pp 143The 144.Fn getdelim 145and 146.Fn getline 147functions may also fail and set 148.Va errno 149for any of the errors specified in the routines 150.Xr fflush 3 , 151.Xr malloc 3 , 152.Xr read 2 , 153.Xr stat 2 , 154or 155.Xr realloc 3 . 156.Sh SEE ALSO 157.Xr ferror 3 , 158.Xr fgets 3 , 159.Xr fopen 3 160.Sh STANDARDS 161The 162.Fn getdelim 163and 164.Fn getline 165functions conform to 166.St -p1003.1-2008 . 167.Sh HISTORY 168These functions were ported from 169.Nx 170to 171.Ox 5.2 . 172