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