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