1.\" $NetBSD: getdelim.3,v 1.7 2009/12/09 18:06:08 joerg 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 November 30, 2009 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 the 51.Fa delimiter 52character, storing the input in 53.Fa *lineptr . 54The buffer is 55.Dv NUL Ns No -terminated 56and includes the delimiter. 57.Pp 58If 59.Fa *n 60is non-zero, then 61.Fa *lineptr 62must be pre-allocated to at least 63.Fa *n 64bytes. 65.Fn getdelim 66ensures that 67.Fa *lineptr 68is large enough to hold the input, updating 69.Fa *n 70to reflect the new size. 71.Pp 72.Fa delimiter 73must be representable as an unsigned char, and 74.Fa *lineptr 75must be a 76.Xr free 3 Ns No able 77buffer. 78.Pp 79.Fa getline 80is equivalent to 81.Fa getdelim 82with the delimiter set to the newline character. 83.Sh RETURN VALUES 84The 85.Fn getdelim 86and 87.Fn getline 88functions return the number of characters read, including the delimiter. 89If no characters were read and the stream is at end-of-file, the functions 90return \-1. 91If an error occurs, the functions return \-1 and the global variable 92.Va errno 93is set to indicate the error. 94.Pp 95The functions do not distinguish between end-of-file and error, 96and callers must use 97.Xr feof 3 98and 99.Xr ferror 3 100to determine which occurred. 101.Sh EXAMPLES 102The following code fragment reads lines from a file and writes them to 103standard output. 104.Bd -literal -offset indent 105char *line = NULL; 106size_t linesize = 0; 107ssize_t linelen; 108while ((linelen = getline(\*[Am]line, \*[Am]linesize, fp)) != -1) 109 fwrite(line, linelen, 1, stdout); 110 111if (ferror(fp)) 112 perror("getline"); 113.Ed 114.Sh ERRORS 115.Bl -tag -width [EOVERFLOW] 116.It Bq Er EINVAL 117.Fa *lineptr 118or 119.Fa *n 120is a 121.Dv NULL 122pointer. 123.It Bq Er EOVERFLOW 124More than SSIZE_MAX characters were read without encountering the delimiter. 125.El 126.Pp 127The 128.Fn getdelim 129and 130.Fn getline 131functions may also fail and set 132.Va errno 133for any of the errors specified in the routines 134.Xr fflush 3 , 135.Xr malloc 3 , 136.Xr read 2 , 137.Xr stat 2 , 138or 139.Xr realloc 3 . 140.Sh SEE ALSO 141.Xr ferror 3 , 142.Xr fgets 3 , 143.Xr fopen 3 144.Sh STANDARDS 145The 146.Fn getdelim 147and 148.Fn getline 149functions conform to 150.St -p1003.1-2008 . 151