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