]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 2001 John Levon <moz@compsoc.man.ac.uk> |
2 | .\" Based in part on GNU libc documentation | |
3 | .\" | |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
5 | .\" Permission is granted to make and distribute verbatim copies of this |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
c13182ef | 13 | .\" |
fea681da MK |
14 | .\" Since the Linux kernel and libraries are constantly changing, this |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
17 | .\" the use of the information contained herein. The author(s) may not | |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
c13182ef | 21 | .\" |
fea681da MK |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
c08df37a | 25 | .\" |
9ba01802 | 26 | .TH GETLINE 3 2019-03-06 "GNU" "Linux Programmer's Manual" |
fea681da MK |
27 | .SH NAME |
28 | getline, getdelim \- delimited string input | |
29 | .SH SYNOPSIS | |
30 | .nf | |
fea681da | 31 | .B #include <stdio.h> |
68e4db0a | 32 | .PP |
fea681da | 33 | .BI "ssize_t getline(char **" lineptr ", size_t *" n ", FILE *" stream ); |
dbfe9c70 | 34 | .PP |
c8250206 MK |
35 | .BI "ssize_t getdelim(char **" lineptr ", size_t *" n ", int " delim \ |
36 | ", FILE *" stream ); | |
37 | .fi | |
68e4db0a | 38 | .PP |
6deb7a03 MK |
39 | .in -4n |
40 | Feature Test Macro Requirements for glibc (see | |
41 | .BR feature_test_macros (7)): | |
42 | .in | |
68e4db0a | 43 | .PP |
6f1b61a1 | 44 | .ad l |
6deb7a03 MK |
45 | .BR getline (), |
46 | .BR getdelim (): | |
cfb08d1e MK |
47 | .PD 0 |
48 | .RS 4 | |
49 | .TP 4 | |
50 | Since glibc 2.10: | |
b0da7b8b | 51 | _POSIX_C_SOURCE\ >=\ 200809L |
cfb08d1e MK |
52 | .TP |
53 | Before glibc 2.10: | |
54 | _GNU_SOURCE | |
55 | .RE | |
56 | .PD | |
6f1b61a1 | 57 | .ad |
fea681da | 58 | .SH DESCRIPTION |
63aa9df0 | 59 | .BR getline () |
c13182ef | 60 | reads an entire line from \fIstream\fP, |
2df47dc8 | 61 | storing the address of the buffer containing the text into |
a5e0a0e4 | 62 | .IR "*lineptr" . |
2df47dc8 MK |
63 | The buffer is null-terminated and includes the newline character, if |
64 | one was found. | |
847e0d88 | 65 | .PP |
fea681da | 66 | If |
0daa9e92 | 67 | .I "*lineptr" |
ac16fdff MK |
68 | is set to NULL and |
69 | .I *n | |
70 | is set 0 before the call, then | |
63aa9df0 | 71 | .BR getline () |
cc82e457 AS |
72 | will allocate a buffer for storing the line. |
73 | This buffer should be freed by the user program | |
74 | even if | |
75 | .BR getline () | |
76 | failed. | |
847e0d88 | 77 | .PP |
fea681da | 78 | Alternatively, before calling |
e1d6264d | 79 | .BR getline (), |
0daa9e92 | 80 | .I "*lineptr" |
fea681da | 81 | can contain a pointer to a |
fb186734 | 82 | .BR malloc (3)\-allocated |
fea681da | 83 | buffer |
0daa9e92 | 84 | .I "*n" |
c13182ef MK |
85 | bytes in size. |
86 | If the buffer is not large enough to hold the line, | |
63aa9df0 | 87 | .BR getline () |
2df47dc8 | 88 | resizes it with |
fb186734 | 89 | .BR realloc (3), |
fea681da | 90 | updating |
0daa9e92 | 91 | .I "*lineptr" |
fea681da | 92 | and |
0daa9e92 | 93 | .I "*n" |
c13182ef | 94 | as necessary. |
847e0d88 | 95 | .PP |
c13182ef | 96 | In either case, on a successful call, |
0daa9e92 | 97 | .I "*lineptr" |
fea681da | 98 | and |
0daa9e92 | 99 | .I "*n" |
2df47dc8 | 100 | will be updated to reflect the buffer address and allocated size respectively. |
847e0d88 | 101 | .PP |
63aa9df0 | 102 | .BR getdelim () |
fea681da | 103 | works like |
e1d6264d | 104 | .BR getline (), |
6f1b61a1 | 105 | except that a line delimiter other than newline can be specified as the |
0daa9e92 | 106 | .I delimiter |
c13182ef MK |
107 | argument. |
108 | As with | |
e1d6264d | 109 | .BR getline (), |
fea681da MK |
110 | a delimiter character is not added if one was not present |
111 | in the input before end of file was reached. | |
47297adb | 112 | .SH RETURN VALUE |
fea681da | 113 | On success, |
e1d6264d | 114 | .BR getline () |
fea681da | 115 | and |
f87925c6 | 116 | .BR getdelim () |
fea681da | 117 | return the number of characters read, including the delimiter character, |
d1a71985 | 118 | but not including the terminating null byte (\(aq\e0\(aq). |
c13182ef | 119 | This value can be used |
28d88c17 | 120 | to handle embedded null bytes in the line read. |
847e0d88 | 121 | .PP |
1c1a8c02 | 122 | Both functions return \-1 on failure to read a line (including end-of-file |
fea681da | 123 | condition). |
1790ea44 MK |
124 | In the event of an error, |
125 | .I errno | |
126 | is set to indicate the cause. | |
fea681da MK |
127 | .SH ERRORS |
128 | .TP | |
129 | .B EINVAL | |
c4bb193f | 130 | Bad arguments |
fea681da MK |
131 | .RI ( n |
132 | or | |
133 | .I lineptr | |
134 | is NULL, or | |
135 | .I stream | |
136 | is not valid). | |
a2db5b9d JH |
137 | .TP |
138 | .B ENOMEM | |
139 | Allocation or reallocation of the line buffer failed. | |
65317e78 MS |
140 | .SH ATTRIBUTES |
141 | For an explanation of the terms used in this section, see | |
142 | .BR attributes (7). | |
143 | .TS | |
144 | allbox; | |
145 | lbw21 lb lb | |
146 | l l l. | |
147 | Interface Attribute Value | |
148 | T{ | |
149 | .BR getline (), | |
150 | .BR getdelim () | |
151 | T} Thread safety MT-Safe | |
152 | .TE | |
847e0d88 | 153 | .sp 1 |
47297adb | 154 | .SH CONFORMING TO |
2b2581ee MK |
155 | Both |
156 | .BR getline () | |
157 | and | |
158 | .BR getdelim () | |
6deb7a03 MK |
159 | were originally GNU extensions. |
160 | They were standardized in POSIX.1-2008. | |
47297adb | 161 | .SH EXAMPLE |
207050fa | 162 | .EX |
fea681da MK |
163 | #define _GNU_SOURCE |
164 | #include <stdio.h> | |
165 | #include <stdlib.h> | |
166 | ||
c13182ef | 167 | int |
cbc616e3 | 168 | main(int argc, char *argv[]) |
fea681da | 169 | { |
363b9dce | 170 | FILE *stream; |
9b50d251 | 171 | char *line = NULL; |
cf0a9ace | 172 | size_t len = 0; |
809b6c47 | 173 | ssize_t nread; |
e77234bb | 174 | |
cbc616e3 | 175 | if (argc != 2) { |
f0e956ca | 176 | fprintf(stderr, "Usage: %s <file>\en", argv[0]); |
cbc616e3 MK |
177 | exit(EXIT_FAILURE); |
178 | } | |
179 | ||
180 | stream = fopen(argv[1], "r"); | |
0885f950 MK |
181 | if (stream == NULL) { |
182 | perror("fopen"); | |
cf0a9ace | 183 | exit(EXIT_FAILURE); |
0885f950 | 184 | } |
e77234bb | 185 | |
809b6c47 | 186 | while ((nread = getline(&line, &len, stream)) != \-1) { |
71fd04a3 | 187 | printf("Retrieved line of length %zu:\en", nread); |
1b1069ee | 188 | fwrite(line, nread, 1, stdout); |
cf0a9ace | 189 | } |
e77234bb | 190 | |
7a4a8221 | 191 | free(line); |
363b9dce | 192 | fclose(stream); |
e77234bb | 193 | exit(EXIT_SUCCESS); |
fea681da | 194 | } |
207050fa | 195 | .EE |
47297adb | 196 | .SH SEE ALSO |
fea681da MK |
197 | .BR read (2), |
198 | .BR fgets (3), | |
199 | .BR fopen (3), | |
200 | .BR fread (3), | |
0a4f8b7b | 201 | .BR scanf (3) |