1 '\" t
2 .\"
3 .\" This file and its contents are supplied under the terms of the
4 .\" Common Development and Distribution License ("CDDL"), version 1.0.
5 .\" You may only use this file in accordance with the terms of version
6 .\" 1.0 of the CDDL.
7 .\"
8 .\" A full copy of the text of the CDDL should have accompanied this
9 .\" source. A copy of the CDDL is also available via the Internet at
10 .\" http://www.illumos.org/license/CDDL.
11 .\"
12 .\"
13 .\" Copyright (c) 2013, Joyent, Inc. All rights reserved.
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
42 behaviour, but uses the newline character as the delimiter. The delimiter
43 character is included in the string (unless end-of-file was reached first) and
44 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
49 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
57 written into the buffer, excluding the terminating null byte. If an error
58 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
103 #include <stdio.h>
104 \&...
105 char *ptr = NULL;
106 size_t cap = 0;
107
108 if (getline(&ptr, &cap, stdin) == -1) {
109 perror("getline");
110 exit(1);
111 }
112 fprintf(stdout, "input line: %s", ptr);
113
114 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)
|
1 .\"
2 .\" This file and its contents are supplied under the terms of the
3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
4 .\" You may only use this file in accordance with the terms of version
5 .\" 1.0 of the CDDL.
6 .\"
7 .\" A full copy of the text of the CDDL should have accompanied this
8 .\" source. A copy of the CDDL is also available via the Internet at
9 .\" http://www.illumos.org/license/CDDL.
10 .\"
11 .\"
12 .\" Copyright (c) 2013, Joyent, Inc. All rights reserved.
13 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
14 .\"
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
52 behaviour, but uses the newline character as the delimiter. The delimiter
53 character is included in the string (unless end-of-file was reached first) and
54 the string is terminated with a null byte.
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
69 will be allocated automatically. If the buffer provided is not large enough to
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
81 written into the buffer, excluding the terminating null byte. If an error
82 occurs, or if end-of-file is reached prior to reading any bytes, the value
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
93 #include <stdio.h>
94 \&...
95 char *ptr = NULL;
96 size_t cap = 0;
97
98 if (getline(&ptr, &cap, stdin) == -1) {
99 perror("getline");
100 exit(1);
101 }
102 fprintf(stdout, "input line: %s", ptr);
103
104 free(ptr);
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 .
|