Mon Nov 30 23:23:29 2009 UTC ()
Note that callers should use feof(3) or ferror(3) to distinguish between
EOF or an error.


(roy)
diff -r1.4 -r1.5 src/lib/libc/stdio/getdelim.3
cvs diff -r1.4 -r1.5 src/lib/libc/stdio/getdelim.3 (switch to unified diff)

--- src/lib/libc/stdio/getdelim.3 2009/11/30 22:51:46 1.4
+++ src/lib/libc/stdio/getdelim.3 2009/11/30 23:23:29 1.5
@@ -1,142 +1,149 @@ @@ -1,142 +1,149 @@
1.\" $NetBSD: getdelim.3,v 1.4 2009/11/30 22:51:46 roy Exp $ 1.\" $NetBSD: getdelim.3,v 1.5 2009/11/30 23:23:29 roy Exp $
2.\" 2.\"
3.\" Copyright (c) 2009 The NetBSD Foundation, Inc. 3.\" Copyright (c) 2009 The NetBSD Foundation, Inc.
4.\" All rights reserved. 4.\" All rights reserved.
5.\" 5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation 6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Roy Marples. 7.\" by Roy Marples.
8.\" 8.\"
9.\" Redistribution and use in source and binary forms, with or without 9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions 10.\" modification, are permitted provided that the following conditions
11.\" are met: 11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright 12.\" 1. Redistributions of source code must retain the above copyright
13.\" notice, this list of conditions and the following disclaimer. 13.\" notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\" notice, this list of conditions and the following disclaimer in the 15.\" notice, this list of conditions and the following disclaimer in the
16.\" documentation and/or other materials provided with the distribution. 16.\" documentation and/or other materials provided with the distribution.
17.\" 17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 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 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 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 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 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 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 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28.\" POSSIBILITY OF SUCH DAMAGE. 28.\" POSSIBILITY OF SUCH DAMAGE.
29.\" 29.\"
30.Dd November 30, 2009 30.Dd November 30, 2009
31.Dt GETDELIM 3 31.Dt GETDELIM 3
32.Os 32.Os
33.Sh NAME 33.Sh NAME
34.Nm getdelim , 34.Nm getdelim ,
35.Nm getline 35.Nm getline
36.Nd read a delimited record from a stream 36.Nd read a delimited record from a stream
37.Sh LIBRARY 37.Sh LIBRARY
38.Lb libc 38.Lb libc
39.Sh SYNOPSIS 39.Sh SYNOPSIS
40.In stdio.h 40.In stdio.h
41.Ft ssize_t 41.Ft ssize_t
42.Fn getdelim "char ** restrict lineptr" "size_t * restrict n" "int delimiter" "FILE * restrict stream" 42.Fn getdelim "char ** restrict lineptr" "size_t * restrict n" "int delimiter" "FILE * restrict stream"
43.Ft ssize_t 43.Ft ssize_t
44.Fn getline "char ** restrict lineptr" "size_t * restrict n" "FILE * restrict stream" 44.Fn getline "char ** restrict lineptr" "size_t * restrict n" "FILE * restrict stream"
45.Sh DESCRIPTION 45.Sh DESCRIPTION
46The 46The
47.Fn getdelim 47.Fn getdelim
48function reads from the 48function reads from the
49.Fa stream 49.Fa stream
50until it encounters a character matching the 50until it encounters a character matching the
51.Fa delimiter 51.Fa delimiter
52character, storing the input in 52character, storing the input in
53.Fa *lineptr . 53.Fa *lineptr .
54The buffer is 54The buffer is
55.Dv NUL Ns No -terminated 55.Dv NUL Ns No -terminated
56and includes the delimiter. 56and includes the delimiter.
57.Pp 57.Pp
58If 58If
59.Fa *n 59.Fa *n
60is non-zero, then 60is non-zero, then
61.Fa *lineptr 61.Fa *lineptr
62must be pre-allocated to at least 62must be pre-allocated to at least
63.Fa *n 63.Fa *n
64bytes. 64bytes.
65.Fn getdelim 65.Fn getdelim
66ensures that 66ensures that
67.Fa *lineptr 67.Fa *lineptr
68is large enough to hold the input, updating 68is large enough to hold the input, updating
69.Fa *n 69.Fa *n
70to reflect the new size. 70to reflect the new size.
71.Pp 71.Pp
72.Fa delimiter 72.Fa delimiter
73must be representable as an unsigned char, and 73must be representable as an unsigned char, and
74.Fa *lineptr 74.Fa *lineptr
75must be a 75must be a
76.Xr free(3) Ns No able 76.Xr free(3) Ns No able
77buffer. 77buffer.
78.Pp 78.Pp
79.Fa getline 79.Fa getline
80is equivalent to 80is equivalent to
81.Fa getdelim 81.Fa getdelim
82with the delimiter set to the newline character. 82with the delimiter set to the newline character.
83.Sh RETURN VALUES 83.Sh RETURN VALUES
84The 84The
85.Fn getdelim 85.Fn getdelim
86and 86and
87.Fn getline 87.Fn getline
88functions return the number of characters read, including the delimiter. 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 89If no characters were read and the stream is at end-of-file, the functions
90return \-1. 90return \-1.
91If an error occurs, the functions return \-1 and the global variable 91If an error occurs, the functions return \-1 and the global variable
92.Va errno 92.Va errno
93is set to indicate the error. 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.
94.Sh EXAMPLE 101.Sh EXAMPLE
95The following code fragment reads lines from a file and writes them to 102The following code fragment reads lines from a file and writes them to
96standard output. 103standard output.
97.Bd -literal -offset indent 104.Bd -literal -offset indent
98char *line = NULL; 105char *line = NULL;
99size_t linesize = 0; 106size_t linesize = 0;
100ssize_t linelen; 107ssize_t linelen;
101while ((linelen = getline(&line, &linesize, fp)) != -1) 108while ((linelen = getline(&line, &linesize, fp)) != -1)
102 fwrite(line, linelen, 1, stdout); 109 fwrite(line, linelen, 1, stdout);
103 110
104if (ferror(fp)) 111if (ferror(fp))
105 perror("getline"); 112 perror("getline");
106.Sh ERRORS 113.Sh ERRORS
107.Bl -tag -width [EOVERFLOW] 114.Bl -tag -width [EOVERFLOW]
108.It Bq Er EINVAL 115.It Bq Er EINVAL
109.Fa *lineptr 116.Fa *lineptr
110or 117or
111.Fa *n 118.Fa *n
112is a 119is a
113.Dv NULL 120.Dv NULL
114pointer. 121pointer.
115.It Bq Er EOVERFLOW 122.It Bq Er EOVERFLOW
116More than SSIZE_MAX characters were read without encountering the delimiter. 123More than SSIZE_MAX characters were read without encountering the delimiter.
117.El 124.El
118.Pp 125.Pp
119The 126The
120.Fn getdelim 127.Fn getdelim
121and 128and
122.Fn getline 129.Fn getline
123functions may also fail and set 130functions may also fail and set
124.Va errno 131.Va errno
125for any of the errors specified in the routines 132for any of the errors specified in the routines
126.Xr fflush 3 , 133.Xr fflush 3 ,
127.Xr malloc 3 , 134.Xr malloc 3 ,
128.Xr read 2 , 135.Xr read 2 ,
129.Xr stat 2 , 136.Xr stat 2 ,
130or 137or
131.Xr realloc 3 . 138.Xr realloc 3 .
132.Sh SEE ALSO 139.Sh SEE ALSO
133.Xr ferror 3 , 140.Xr ferror 3 ,
134.Xr fgets 3 , 141.Xr fgets 3 ,
135.Xr fopen 3 142.Xr fopen 3
136.Sh STANDARDS 143.Sh STANDARDS
137The 144The
138.Fn getdelim 145.Fn getdelim
139and 146and
140.Fn getline 147.Fn getline
141functions conform to 148functions conform to
142.St -p1003.1-2008 . 149.St -p1003.1-2008 .