Debian Codegraph @

upstream/fedora-44/man3/getline.3

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