Debian Codegraph @

upstream/debian-unstable/man3/getline.3

raw
1 '\" t
2 .\" Copyright 2001, John Levon <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH getline 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 getline, getdelim \- delimited string input
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <stdio.h>
16 .P
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 );
21 .fi
22 .P
23 .RS -4
24 Feature Test Macro Requirements for glibc (see
25 .BR feature_test_macros (7)):
26 .RE
27 .P
28 .BR getline (),
29 .BR getdelim ():
30 .nf
31 Since glibc 2.10:
32 _POSIX_C_SOURCE >= 200809L
33 Before glibc 2.10:
34 _GNU_SOURCE
35 .fi
36 .SH DESCRIPTION
37 .BR getline ()
38 reads an entire line from
39 .IR stream ,
40 storing the address of the buffer containing the text into
41 .IR *lineptr .
42 The buffer is null-terminated and includes the newline character, if
43 one was found.
44 .P
45 If
46 .I *lineptr
47 is set to NULL before the call, then
48 .BR getline ()
49 will allocate a buffer for storing the line.
50 This buffer should be freed by the user program
51 even if
52 .BR getline ()
53 failed.
54 .P
55 Alternatively, before calling
56 .BR getline (),
57 .I *lineptr
58 can contain a pointer to a
59 .BR malloc (3)\-allocated
60 buffer
61 .I *n
62 bytes in size.
63 If the buffer is not large enough to hold the line,
64 .BR getline ()
65 resizes it with
66 .BR realloc (3),
67 updating
68 .I *lineptr
69 and
70 .I *n
71 as necessary.
72 .P
73 In either case, on a successful call,
74 .I *lineptr
75 and
76 .I *n
77 will be updated to reflect the buffer address and allocated size respectively.
78 .P
79 .BR getdelim ()
80 works like
81 .BR getline (),
82 except that a line delimiter other than newline can be specified as the
83 .I delimiter
84 argument.
85 As with
86 .BR getline (),
87 a delimiter character is not added if one was not present
88 in the input before end of file was reached.
89 .SH RETURN VALUE
90 On success,
91 .BR getline ()
92 and
93 .BR getdelim ()
94 return the number of characters read, including the delimiter character,
95 but not including the terminating null byte (\[aq]\[rs]0\[aq]).
96 This value can be used
97 to handle embedded null bytes in the line read.
98 .P
99 At end of file,
100 both functions return \-1 with the file stream end-of-file indicator set.
101 On error,
102 both functions return \-1 with the file stream error indicator set,
103 and
104 .I errno
105 is set to indicate the error.
106 .P
107 If
108 .I *lineptr
109 was set to NULL before the call, then the buffer should be freed by the
110 user program even on failure.
111 .SH ERRORS
112 .TP
113 .B EINVAL
114 Bad arguments
115 .RI ( n
116 or
117 .I lineptr
118 is NULL, or
119 .I stream
120 is not valid).
121 .TP
122 .B ENOMEM
123 Allocation or reallocation of the line buffer failed.
124 .SH ATTRIBUTES
125 For an explanation of the terms used in this section, see
126 .BR attributes (7).
127 .TS
128 allbox;
129 lbx lb lb
130 l l l.
131 Interface Attribute Value
132 T{
133 .na
134 .nh
135 .BR getline (),
136 .BR getdelim ()
137 T} Thread safety MT-Safe
138 .TE
139 .SH STANDARDS
140 POSIX.1-2008.
141 .SH HISTORY
142 GNU, POSIX.1-2008.
143 .SH EXAMPLES
144 .\" SRC BEGIN (getline.c)
145 .EX
146 #define _GNU_SOURCE
147 #include <stdio.h>
148 #include <stdlib.h>
149 \&
150 int
151 main(int argc, char *argv[])
152 {
153 FILE *stream;
154 char *line = NULL;
155 size_t size = 0;
156 ssize_t nread;
157 \&
158 if (argc != 2) {
159 fprintf(stderr, "Usage: %s <file>\[rs]n", argv[0]);
160 exit(EXIT_FAILURE);
161 }
162 \&
163 stream = fopen(argv[1], "r");
164 if (stream == NULL) {
165 perror("fopen");
166 exit(EXIT_FAILURE);
167 }
168 \&
169 while ((nread = getline(&line, &size, stream)) != \-1) {
170 printf("Retrieved line of length %zd:\[rs]n", nread);
171 fwrite(line, nread, 1, stdout);
172 }
173 \&
174 free(line);
175 fclose(stream);
176 exit(EXIT_SUCCESS);
177 }
178 .EE
179 .\" SRC END
180 .SH SEE ALSO
181 .BR read (2),
182 .BR fgets (3),
183 .BR fopen (3),
184 .BR fread (3),
185 .BR scanf (3)