1GETDELIM(3P) POSIX Programmer's Manual GETDELIM(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 getdelim, getline — read a delimited record from stream
13
15 #include <stdio.h>
16 ssize_t getdelim(char **restrict lineptr, size_t *restrict n,
18 int delimiter, FILE *restrict stream);
19 ssize_t getline(char **restrict lineptr, size_t *restrict n,
20 FILE *restrict stream);
21
23 The getdelim() function shall read from stream until it encounters a
24 character matching the delimiter character. The delimiter argument is
25 an int, the value of which the application shall ensure is a character
26 representable as an unsigned char of equal value that terminates the
27 read process. If the delimiter argument has any other value, the behav‐
28 ior is undefined.
29 The application shall ensure that *lineptr is a valid argument that
31 could be passed to the free() function. If *n is non-zero, the applica‐
32 tion shall ensure that *lineptr either points to an object of size at
33 least *n bytes, or is a null pointer.
34 If *lineptr is a null pointer or if the object pointed to by *lineptr
36 is of insufficient size, an object shall be allocated as if by malloc()
37 or the object shall be reallocated as if by realloc(), respectively,
38 such that the object is large enough to hold the characters to be writ‐
39 ten to it, including the terminating NUL, and *n shall be set to the
40 new size. If the object was allocated, or if the reallocation operation
41 moved the object, *lineptr shall be updated to point to the new object
42 or new location. The characters read, including any delimiter, shall
43 be stored in the object, and a terminating NUL added when the delimiter
44 or end-of-file is encountered.
45 The getline() function shall be equivalent to the getdelim() function
47 with the delimiter character equal to the <newline> character.
48 The getdelim() and getline() functions may mark the last data access
50 timestamp of the file associated with stream for update. The last data
51 access timestamp shall be marked for update by the first successful
52 execution of fgetc(), fgets(), fread(), fscanf(), getc(), getchar(),
53 getdelim(), getline(), gets(), or scanf() using stream that returns
54 data not supplied by a prior call to ungetc().
55
57 Upon successful completion, the getline() and getdelim() functions
58 shall return the number of bytes written into the buffer, including the
59 delimiter character if one was encountered before EOF, but excluding
60 the terminating NUL character. If the end-of-file indicator for the
61 stream is set, or if no characters were read and the stream is at end-
62 of-file, the end-of-file indicator for the stream shall be set and the
63 function shall return -1. If an error occurs, the error indicator for
64 the stream shall be set, and the function shall return -1 and set errno
65 to indicate the error.
66
68 For the conditions under which the getdelim() and getline() functions
69 shall fail and may fail, refer to fgetc().
70 In addition, these functions shall fail if:
72 EINVAL lineptr or n is a null pointer.
74 ENOMEM Insufficient memory is available.
76 These functions may fail if:
78 EOVERFLOW
80 The number of bytes to be written into the buffer, including the
81 delimiter character (if encountered), would exceed {SSIZE_MAX}.
82 The following sections are informative.
84
86 #include <stdio.h>
87 #include <stdlib.h>
88 int main(void)
90 {
91 FILE *fp;
92 char *line = NULL;
93 size_t len = 0;
94 ssize_t read;
95 fp = fopen("/etc/motd", "r");
96 if (fp == NULL)
97 exit(1);
98 while ((read = getline(&line, &len, fp)) != -1) {
99 printf("Retrieved line of length %zu :\n", read);
100 printf("%s", line);
101 }
102 if (ferror(fp)) {
103 /* handle error */
104 }
105 free(line);
106 fclose(fp);
107 return 0;
108 }
109
111 Setting *lineptr to a null pointer and *n to zero are allowed and a
112 recommended way to start parsing a file.
113 The ferror() or feof() functions should be used to distinguish between
115 an error condition and an end-of-file condition.
116 Although a NUL terminator is always supplied after the line, note that
118 strlen(*lineptr) will be smaller than the return value if the line con‐
119 tains embedded NUL characters.
120
122 These functions are widely used to solve the problem that the fgets()
123 function has with long lines. The functions automatically enlarge the
124 target buffers if needed. These are especially useful since they reduce
125 code needed for applications.
126
128 None.
129
131 Section 2.5, Standard I/O Streams, fgetc(), fgets(), free(), malloc(),
132 realloc()
133 The Base Definitions volume of POSIX.1‐2017, <stdio.h>
135
137 Portions of this text are reprinted and reproduced in electronic form
138 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
139 table Operating System Interface (POSIX), The Open Group Base Specifi‐
140 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
141 Electrical and Electronics Engineers, Inc and The Open Group. In the
142 event of any discrepancy between this version and the original IEEE and
143 The Open Group Standard, the original IEEE and The Open Group Standard
144 is the referee document. The original Standard can be obtained online
145 at http://www.opengroup.org/unix/online.html .
146 Any typographical or formatting errors that appear in this page are
148 most likely to have been introduced during the conversion of the source
149 files to man page format. To report such errors, see https://www.ker‐
150 nel.org/doc/man-pages/reporting_bugs.html .
151IEEE/The Open Group 2017 GETDELIM(3P)