1.\" $NetBSD: getdelim.3,v 1.2 2009/07/13 22:30:52 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 July 12, 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 getline 73is equivalent to 74.Fa getdelim 75with the delimiter set to the newline character. 76.Sh RETURN VALUES 77The 78.Fn getdelim 79and 80.Fn getline 81functions return the number of characters read, including the delimiter. 82If an error occurs, the functions return \-1 and the global variable 83.Va errno 84is set to indicate the error. 85.Sh ERRORS 86.Bl -tag -width [EOVERFLOW] 87.It Bq Er EINVAL 88.Fa *lineptr 89or 90.Fa *n 91is a 92.Dv NULL 93pointer. 94.It Bq Er EOVERFLOW 95More than ssize_t characters were read without encountering the delimiter. 96.El 97.Pp 98The 99.Fn getdelim 100and 101.Fn getline 102functions may also fail and set 103.Va errno 104for any of the errors specified in the routines 105.Xr fflush 3 , 106.Xr malloc 3 , 107.Xr read 2 , 108.Xr stat 2 , 109or 110.Xr realloc 3 . 111.Sh SEE ALSO 112.Xr ferror 3 , 113.Xr fgets 3 , 114.Xr fopen 3 115.Sh STANDARDS 116The 117.Fn getdelim 118and 119.Fn getline 120functions conform to 121.St -p1003.1-2008 . 122