]>
Commit | Line | Data |
---|---|---|
a1eaacb1 | 1 | '\" t |
fea681da MK |
2 | .\" Copyright (c) 2001 John Levon <moz@compsoc.man.ac.uk> |
3 | .\" Based in part on GNU libc documentation | |
4 | .\" | |
5fbde956 | 5 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
c08df37a | 6 | .\" |
4c1c5274 | 7 | .TH getline 3 (date) "Linux man-pages (unreleased)" |
fea681da MK |
8 | .SH NAME |
9 | getline, getdelim \- delimited string input | |
42009080 AC |
10 | .SH LIBRARY |
11 | Standard C library | |
12 | .RI ( libc ", " \-lc ) | |
fea681da MK |
13 | .SH SYNOPSIS |
14 | .nf | |
fea681da | 15 | .B #include <stdio.h> |
c6d039a3 | 16 | .P |
22f4c265 AC |
17 | .BI "ssize_t getline(char **restrict " lineptr ", size_t *restrict " n , |
18 | .BI " FILE *restrict " stream ); | |
19 | .BI "ssize_t getdelim(char **restrict " lineptr ", size_t *restrict " n , | |
20 | .BI " int " delim ", FILE *restrict " stream ); | |
c8250206 | 21 | .fi |
c6d039a3 | 22 | .P |
d39ad78f | 23 | .RS -4 |
6deb7a03 MK |
24 | Feature Test Macro Requirements for glibc (see |
25 | .BR feature_test_macros (7)): | |
d39ad78f | 26 | .RE |
c6d039a3 | 27 | .P |
6deb7a03 MK |
28 | .BR getline (), |
29 | .BR getdelim (): | |
9d2adbae MK |
30 | .nf |
31 | Since glibc 2.10: | |
5c10d2c5 | 32 | _POSIX_C_SOURCE >= 200809L |
9d2adbae MK |
33 | Before glibc 2.10: |
34 | _GNU_SOURCE | |
35 | .fi | |
fea681da | 36 | .SH DESCRIPTION |
63aa9df0 | 37 | .BR getline () |
c13182ef | 38 | reads an entire line from \fIstream\fP, |
2df47dc8 | 39 | storing the address of the buffer containing the text into |
a4e6163e | 40 | .IR *lineptr . |
2df47dc8 MK |
41 | The buffer is null-terminated and includes the newline character, if |
42 | one was found. | |
c6d039a3 | 43 | .P |
fea681da | 44 | If |
a4e6163e | 45 | .I *lineptr |
8b97c4f8 | 46 | is set to NULL before the call, then |
63aa9df0 | 47 | .BR getline () |
cc82e457 AS |
48 | will allocate a buffer for storing the line. |
49 | This buffer should be freed by the user program | |
50 | even if | |
51 | .BR getline () | |
52 | failed. | |
c6d039a3 | 53 | .P |
fea681da | 54 | Alternatively, before calling |
e1d6264d | 55 | .BR getline (), |
a4e6163e | 56 | .I *lineptr |
fea681da | 57 | can contain a pointer to a |
fb186734 | 58 | .BR malloc (3)\-allocated |
fea681da | 59 | buffer |
a4e6163e | 60 | .I *n |
c13182ef MK |
61 | bytes in size. |
62 | If the buffer is not large enough to hold the line, | |
63aa9df0 | 63 | .BR getline () |
2df47dc8 | 64 | resizes it with |
fb186734 | 65 | .BR realloc (3), |
fea681da | 66 | updating |
a4e6163e | 67 | .I *lineptr |
fea681da | 68 | and |
a4e6163e | 69 | .I *n |
c13182ef | 70 | as necessary. |
c6d039a3 | 71 | .P |
c13182ef | 72 | In either case, on a successful call, |
a4e6163e | 73 | .I *lineptr |
fea681da | 74 | and |
a4e6163e | 75 | .I *n |
2df47dc8 | 76 | will be updated to reflect the buffer address and allocated size respectively. |
c6d039a3 | 77 | .P |
63aa9df0 | 78 | .BR getdelim () |
fea681da | 79 | works like |
e1d6264d | 80 | .BR getline (), |
6f1b61a1 | 81 | except that a line delimiter other than newline can be specified as the |
0daa9e92 | 82 | .I delimiter |
c13182ef MK |
83 | argument. |
84 | As with | |
e1d6264d | 85 | .BR getline (), |
fea681da MK |
86 | a delimiter character is not added if one was not present |
87 | in the input before end of file was reached. | |
47297adb | 88 | .SH RETURN VALUE |
fea681da | 89 | On success, |
e1d6264d | 90 | .BR getline () |
fea681da | 91 | and |
f87925c6 | 92 | .BR getdelim () |
fea681da | 93 | return the number of characters read, including the delimiter character, |
b957f81f | 94 | but not including the terminating null byte (\[aq]\e0\[aq]). |
c13182ef | 95 | This value can be used |
28d88c17 | 96 | to handle embedded null bytes in the line read. |
c6d039a3 | 97 | .P |
1c1a8c02 | 98 | Both functions return \-1 on failure to read a line (including end-of-file |
fea681da | 99 | condition). |
cb6a894e | 100 | In the event of a failure, |
1790ea44 | 101 | .I errno |
cb6a894e | 102 | is set to indicate the error. |
c6d039a3 | 103 | .P |
4562fb5e | 104 | If |
105 | .I *lineptr | |
106 | was set to NULL before the call, then the buffer should be freed by the | |
107 | user program even on failure. | |
fea681da MK |
108 | .SH ERRORS |
109 | .TP | |
110 | .B EINVAL | |
c4bb193f | 111 | Bad arguments |
fea681da MK |
112 | .RI ( n |
113 | or | |
114 | .I lineptr | |
115 | is NULL, or | |
116 | .I stream | |
117 | is not valid). | |
a2db5b9d JH |
118 | .TP |
119 | .B ENOMEM | |
120 | Allocation or reallocation of the line buffer failed. | |
65317e78 MS |
121 | .SH ATTRIBUTES |
122 | For an explanation of the terms used in this section, see | |
123 | .BR attributes (7). | |
124 | .TS | |
125 | allbox; | |
c466875e | 126 | lbx lb lb |
65317e78 MS |
127 | l l l. |
128 | Interface Attribute Value | |
129 | T{ | |
9e54434e BR |
130 | .na |
131 | .nh | |
65317e78 MS |
132 | .BR getline (), |
133 | .BR getdelim () | |
134 | T} Thread safety MT-Safe | |
135 | .TE | |
3113c7f3 | 136 | .SH STANDARDS |
4131356c AC |
137 | POSIX.1-2008. |
138 | .SH HISTORY | |
139 | GNU, POSIX.1-2008. | |
a14af333 | 140 | .SH EXAMPLES |
b0b6ab4e | 141 | .\" SRC BEGIN (getline.c) |
207050fa | 142 | .EX |
fea681da MK |
143 | #define _GNU_SOURCE |
144 | #include <stdio.h> | |
145 | #include <stdlib.h> | |
fe5dba13 | 146 | \& |
c13182ef | 147 | int |
cbc616e3 | 148 | main(int argc, char *argv[]) |
fea681da | 149 | { |
363b9dce | 150 | FILE *stream; |
9b50d251 | 151 | char *line = NULL; |
cf0a9ace | 152 | size_t len = 0; |
809b6c47 | 153 | ssize_t nread; |
fe5dba13 | 154 | \& |
cbc616e3 | 155 | if (argc != 2) { |
f0e956ca | 156 | fprintf(stderr, "Usage: %s <file>\en", argv[0]); |
cbc616e3 MK |
157 | exit(EXIT_FAILURE); |
158 | } | |
fe5dba13 | 159 | \& |
cbc616e3 | 160 | stream = fopen(argv[1], "r"); |
0885f950 MK |
161 | if (stream == NULL) { |
162 | perror("fopen"); | |
cf0a9ace | 163 | exit(EXIT_FAILURE); |
0885f950 | 164 | } |
fe5dba13 | 165 | \& |
809b6c47 | 166 | while ((nread = getline(&line, &len, stream)) != \-1) { |
0ca5f061 | 167 | printf("Retrieved line of length %zd:\en", nread); |
1b1069ee | 168 | fwrite(line, nread, 1, stdout); |
cf0a9ace | 169 | } |
fe5dba13 | 170 | \& |
7a4a8221 | 171 | free(line); |
363b9dce | 172 | fclose(stream); |
e77234bb | 173 | exit(EXIT_SUCCESS); |
fea681da | 174 | } |
207050fa | 175 | .EE |
b0b6ab4e | 176 | .\" SRC END |
47297adb | 177 | .SH SEE ALSO |
fea681da MK |
178 | .BR read (2), |
179 | .BR fgets (3), | |
180 | .BR fopen (3), | |
181 | .BR fread (3), | |
0a4f8b7b | 182 | .BR scanf (3) |