1.\" $NetBSD: getdelim.3,v 1.3 2009/08/25 16:28:26 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 August 25, 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 an error occurs, the functions return \-1 and the global variable 90.Va errno 91is set to indicate the error. 92.Sh ERRORS 93.Bl -tag -width [EOVERFLOW] 94.It Bq Er EINVAL 95.Fa *lineptr 96or 97.Fa *n 98is a 99.Dv NULL 100pointer. 101.It Bq Er EOVERFLOW 102More than ssize_t characters were read without encountering the delimiter. 103.El 104.Pp 105The 106.Fn getdelim 107and 108.Fn getline 109functions may also fail and set 110.Va errno 111for any of the errors specified in the routines 112.Xr fflush 3 , 113.Xr malloc 3 , 114.Xr read 2 , 115.Xr stat 2 , 116or 117.Xr realloc 3 . 118.Sh SEE ALSO 119.Xr ferror 3 , 120.Xr fgets 3 , 121.Xr fopen 3 122.Sh STANDARDS 123The 124.Fn getdelim 125and 126.Fn getline 127functions conform to 128.St -p1003.1-2008 . 129