Tue Dec 1 08:15:50 2009 UTC ()
Make HTML-ready, use standard section headers, fix Xr.


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

--- src/lib/libc/stdio/getdelim.3 2009/11/30 23:23:29 1.5
+++ src/lib/libc/stdio/getdelim.3 2009/12/01 08:15:50 1.6
@@ -1,149 +1,149 @@ @@ -1,149 +1,149 @@
1.\" $NetBSD: getdelim.3,v 1.5 2009/11/30 23:23:29 roy Exp $ 1.\" $NetBSD: getdelim.3,v 1.6 2009/12/01 08:15:50 wiz 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 94.Pp
95The functions do not distinguish between end-of-file and error, 95The functions do not distinguish between end-of-file and error,
96and callers must use 96and callers must use
97.Xr feof 3 97.Xr feof 3
98and 98and
99.Xr ferror 3 99.Xr ferror 3
100to determine which occurred. 100to determine which occurred.
101.Sh EXAMPLE 101.Sh EXAMPLES
102The 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
103standard output. 103standard output.
104.Bd -literal -offset indent 104.Bd -literal -offset indent
105char *line = NULL; 105char *line = NULL;
106size_t linesize = 0; 106size_t linesize = 0;
107ssize_t linelen; 107ssize_t linelen;
108while ((linelen = getline(&line, &linesize, fp)) != -1) 108while ((linelen = getline(\*[Am]line, \*[Am]linesize, fp)) != -1)
109 fwrite(line, linelen, 1, stdout); 109 fwrite(line, linelen, 1, stdout);
110 110
111if (ferror(fp)) 111if (ferror(fp))
112 perror("getline"); 112 perror("getline");
113.Sh ERRORS 113.Sh ERRORS
114.Bl -tag -width [EOVERFLOW] 114.Bl -tag -width [EOVERFLOW]
115.It Bq Er EINVAL 115.It Bq Er EINVAL
116.Fa *lineptr 116.Fa *lineptr
117or 117or
118.Fa *n 118.Fa *n
119is a 119is a
120.Dv NULL 120.Dv NULL
121pointer. 121pointer.
122.It Bq Er EOVERFLOW 122.It Bq Er EOVERFLOW
123More than SSIZE_MAX characters were read without encountering the delimiter. 123More than SSIZE_MAX characters were read without encountering the delimiter.
124.El 124.El
125.Pp 125.Pp
126The 126The
127.Fn getdelim 127.Fn getdelim
128and 128and
129.Fn getline 129.Fn getline
130functions may also fail and set 130functions may also fail and set
131.Va errno 131.Va errno
132for any of the errors specified in the routines 132for any of the errors specified in the routines
133.Xr fflush 3 , 133.Xr fflush 3 ,
134.Xr malloc 3 , 134.Xr malloc 3 ,
135.Xr read 2 , 135.Xr read 2 ,
136.Xr stat 2 , 136.Xr stat 2 ,
137or 137or
138.Xr realloc 3 . 138.Xr realloc 3 .
139.Sh SEE ALSO 139.Sh SEE ALSO
140.Xr ferror 3 , 140.Xr ferror 3 ,
141.Xr fgets 3 , 141.Xr fgets 3 ,
142.Xr fopen 3 142.Xr fopen 3
143.Sh STANDARDS 143.Sh STANDARDS
144The 144The
145.Fn getdelim 145.Fn getdelim
146and 146and
147.Fn getline 147.Fn getline
148functions conform to 148functions conform to
149.St -p1003.1-2008 . 149.St -p1003.1-2008 .