Print this page
Whoops! Wrong file modified!
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man3c/getline.3c
+++ new/usr/src/man/man3c/getline.3c
1 -'\" t
2 1 .\"
3 2 .\" This file and its contents are supplied under the terms of the
4 3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
5 4 .\" You may only use this file in accordance with the terms of version
6 5 .\" 1.0 of the CDDL.
7 6 .\"
8 7 .\" A full copy of the text of the CDDL should have accompanied this
9 8 .\" source. A copy of the CDDL is also available via the Internet at
10 9 .\" http://www.illumos.org/license/CDDL.
11 10 .\"
12 11 .\"
13 12 .\" Copyright (c) 2013, Joyent, Inc. All rights reserved.
13 +.\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
14 14 .\"
15 -.TH GETLINE 3C "Apr 24, 2013"
16 -.SH NAME
17 -getline, getdelim \- read delimited input from streams
18 -.SH SYNOPSIS
19 -.LP
20 -.nf
21 -#include <stdio.h>
22 -.fi
23 -
24 -.LP
25 -.nf
26 -\fBssize_t\fR \fBgetline\fR(\fBchar **restrict\fR \fIptr\fR, \
27 -\fBsize_t *restrict\fR \fIcap\fR,
28 - \fBFILE *restrict\fR \fIstream\fR);
29 -.fi
30 -
31 -.LP
32 -.nf
33 -\fBssize_t\fR \fBgetdelim\fR(\fBchar **restrict\fR \fIptr\fR, \
34 -\fBsize_t *restrict\fR \fIcap\fR,
35 - \fBint\fR \fIdelimiter\fR, \fBFILE *restrict\fR \fIstream\fR);
36 -.fi
37 -
38 -.SH DESCRIPTION
39 -The \fBgetdelim\fR() function reads bytes from the \fIstream\fR into the the
40 -array pointed to by \fIptr\fR, until the \fIdelimiter\fR byte or an end-of-file
41 -condition is encountered. The \fBgetline\fR() function is identical in
15 +.Dd "Apr 24, 2013"
16 +.Dt GETLINE 3C
17 +.Os
18 +.Sh NAME
19 +.Nm getline ,
20 +.Nm getdelim
21 +.Nd read delimited input from streams
22 +.Sh SYNOPSIS
23 +.In stdio.h
24 +.Ft ssize_t
25 +.Fo getline
26 +.Fa "char **restrict ptr"
27 +.Fa "size_t *restrict cap"
28 +.Fa "FILE *restrict stream"
29 +.Fc
30 +.
31 +.Ft ssize_t
32 +.Fo getdelim
33 +.Fa "char **restrict ptr"
34 +.Fa "size_t *restrict cap"
35 +.Fa "int delimiter"
36 +.Fa "FILE *restrict stream"
37 +.Fc
38 +.
39 +.Sh DESCRIPTION
40 +The
41 +.Fn getdelim
42 +function reads bytes from the
43 +.Fa stream
44 +into the the
45 +array pointed to by
46 +.Fa ptr ,
47 +until the
48 +.Fa delimiter
49 +byte or an end-of-file condition is encountered. The
50 +.Fa getline
51 +function is identical in
42 52 behaviour, but uses the newline character as the delimiter. The delimiter
43 53 character is included in the string (unless end-of-file was reached first) and
44 54 the string is terminated with a null byte.
45 -
46 -The caller may pass a pre-allocated \fBmalloc\fR(3C) buffer as \fI*ptr\fR,
47 -along with the capacity of that buffer as \fI*cap\fR. It is also valid to pass
48 -\fBNULL\fR for \fI*ptr\fR and \fB0\fR for \fI*cap\fR, at which point memory
55 +.Lp
56 +The caller may pass a buffer pre-allocated with
57 +.Xr malloc 3C
58 +as
59 +.Fa *ptr ,
60 +along with the capacity of that buffer as
61 +.Fa *cap .
62 +It is also valid to pass
63 +.Dv NULL
64 +for
65 +.Fa *ptr
66 +and 0 for
67 +.Fa *cap ,
68 +at which point memory
49 69 will be allocated automatically. If the buffer provided is not large enough to
50 -hold the string it will be expanded, as if via \fBrealloc(3C)\fR. The caller
51 -must \fBfree(3C)\fR the buffer when it is no longer required.
52 -
53 -.SH RETURN VALUES
54 -.sp
55 -.LP
56 -If successful, \fBgetdelim\fR() and \fBgetline\fR() return the number of bytes
70 +hold the string it will be expanded, as if via
71 +.Xr realloc 3C .
72 +The caller should
73 +.Xr free 3C
74 +the buffer when it is no longer required.
75 +.Sh RETURN VALUES
76 +If successful,
77 +.Fn getdelim
78 +and
79 +.Fn getline
80 +return the number of bytes
57 81 written into the buffer, excluding the terminating null byte. If an error
58 82 occurs, or if end-of-file is reached prior to reading any bytes, the value
59 -\fB\(mi1\fR is returned and \fIerrno\fR is set to indicate the error.
60 -
61 -.SH ERRORS
62 -.sp
63 -.LP
64 -The \fBgetline\fR() and \fBgetdelim\fR() functions may fail due to the
65 -following errors:
66 -
67 -.sp
68 -.ne 2
69 -.na
70 -\fBEINVAL\fR
71 -.ad
72 -.RS 13n
73 -Either \fIptr\fR or \fIcap\fR are \fBNULL\fR, or the \fIdelimiter\fR is
74 -not a valid character.
75 -.RE
76 -
77 -.sp
78 -.ne 2
79 -.na
80 -\fBEOVERFLOW\fR
81 -.ad
82 -.RS 13n
83 -More than \fBSSIZE_MAX\fR characters were read from the stream without
84 -encountering the \fIdelimiter\fR.
85 -.RE
86 -
87 -.sp
88 -.LP
89 -The \fBgetline\fR() and \fBgetdelim\fR() functions may also fail and set
90 -\fIerrno\fR for any of the errors specified for the library routines
91 -\fBrealloc\fR(3C) or \fBfgetc\fR(3C).
92 -
93 -.SH EXAMPLES
94 -.LP
95 -\fBExample 1\fR Read a line from \fBstdin\fR.
96 -.sp
97 -.LP
98 -The following example uses \fBgetline\fR to read a line from stdin.
99 -
100 -.sp
101 -.in +2
102 -.nf
83 +\(mi1 is returned and
84 +.Va errno
85 +is set to indicate the error.
86 +.Sh EXAMPLES
87 +.Ss Example 1 Read a line from Va stdin
88 +The following example uses
89 +.Fn getline
90 +to read a line from
91 +.Va stdin .
92 +.Bd -literal -offset indent
103 93 #include <stdio.h>
104 94 \&...
105 95 char *ptr = NULL;
106 96 size_t cap = 0;
107 97
108 98 if (getline(&ptr, &cap, stdin) == -1) {
109 99 perror("getline");
110 100 exit(1);
111 101 }
112 102 fprintf(stdout, "input line: %s", ptr);
113 103
114 104 free(ptr);
115 -.
116 -.fi
117 -.in -2
118 -
119 -.SH ATTRIBUTES
120 -.sp
121 -.TS
122 -box;
123 -c | c
124 -l | l .
125 -ATTRIBUTE TYPE ATTRIBUTE VALUE
126 -_
127 -Interface Stability Committed
128 -_
129 -MT-Level MT-Safe
130 -.TE
131 -
132 -.SH SEE ALSO
133 -.sp
134 -.LP
135 -\fBfgetc\fR(3C), \fBfgets\fR(3C), \fBfree\fR(3C), \fBmalloc\fR(3C),
136 -\fBrealloc\fR(3C), \fBattributes\fR(5)
105 +.Ed
106 +.Sh ERRORS
107 +The
108 +.Fn getline
109 +and
110 +.Fn getdelim
111 +functions may fail due to the following errors:
112 +.Bl -tag -width Er
113 +.It Er EINVAL
114 +Either
115 +.Fa ptr
116 +or
117 +.Fa cap are
118 +.Dv NULL , or th
119 +.Fa delimiter
120 +is not a valid character.
121 +.It Er EOVERFLOW
122 +More than
123 +.Dv SSIZE_MAX
124 +characters were read from the stream without
125 +encountering the
126 +.Fa delimiter .
127 +.El
128 +.Lp
129 +The
130 +.Fn getline
131 +and
132 +.Fn getdelim
133 +functions may also fail and set
134 +.Va errno
135 +for any of the errors specified for the library routines
136 +.Xr realloc 3C
137 +or
138 +.Xr fgetc 3C .
139 +.Sh INTERFACE STABILITY
140 +.Sy Standard .
141 +.Sh MT-LEVEL
142 +.Sy MT-Safe .
143 +.Sh SEE ALSO
144 +.Xr fgetc 3C ,
145 +.Xr fgets 3C ,
146 +.Xr free 3C ,
147 +.Xr malloc 3C ,
148 +.Xr realloc 3C ,
149 +.Xr standards 5
150 +.Sh STANDARDS
151 +These functions were introduced in
152 +.St -p1003.1-2008 .
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX