1.\" $NetBSD: getdelim.3,v 1.6 2009/12/01 08:15:50 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 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.Sh ERRORS 114.Bl -tag -width [EOVERFLOW] 115.It Bq Er EINVAL 116.Fa *lineptr 117or 118.Fa *n 119is a 120.Dv NULL 121pointer. 122.It Bq Er EOVERFLOW 123More than SSIZE_MAX characters were read without encountering the delimiter. 124.El 125.Pp 126The 127.Fn getdelim 128and 129.Fn getline 130functions may also fail and set 131.Va errno 132for any of the errors specified in the routines 133.Xr fflush 3 , 134.Xr malloc 3 , 135.Xr read 2 , 136.Xr stat 2 , 137or 138.Xr realloc 3 . 139.Sh SEE ALSO 140.Xr ferror 3 , 141.Xr fgets 3 , 142.Xr fopen 3 143.Sh STANDARDS 144The 145.Fn getdelim 146and 147.Fn getline 148functions conform to 149.St -p1003.1-2008 . 150