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
13 getdelim, getline — read a delimited record from stream
14
16 #include <stdio.h>
17 ssize_t getdelim(char **restrict lineptr, size_t *restrict n,
19 int delimiter, FILE *restrict stream);
20 ssize_t getline(char **restrict lineptr, size_t *restrict n,
21 FILE *restrict stream);
22
24 The getdelim() function shall read from stream until it encounters a
25 character matching the delimiter character. The delimiter argument is
26 an int, the value of which the application shall ensure is a character
27 representable as an unsigned char of equal value that terminates the
28 read process. If the delimiter argument has any other value, the behav‐
29 ior is undefined.
30 The application shall ensure that *lineptr is a valid argument that
32 could be passed to the free() function. If *n is non-zero, the applica‐
33 tion shall ensure that *lineptr either points to an object of size at
34 least *n bytes, or is a null pointer.
35 The size of the object pointed to by *lineptr shall be increased to fit
37 the incoming line, if it isn't already large enough, including room for
38 the delimiter and a terminating NUL. The characters read, including any
39 delimiter, shall be stored in the string pointed to by the lineptr
40 argument, and a terminating NUL added when the delimiter or end of file
41 is encountered.
42 The getline() function shall be equivalent to the getdelim() function
44 with the delimiter character equal to the <newline> character.
45 The getdelim() and getline() functions may mark the last data access
47 timestamp of the file associated with stream for update. The last data
48 access timestamp shall be marked for update by the first successful
49 execution of fgetc(), fgets(), fread(), fscanf(), getc(), getchar(),
50 getdelim(), getline(), gets(), or scanf() using stream that returns
51 data not supplied by a prior call to ungetc().
52
54 Upon successful completion, the getline() and getdelim() functions
55 shall return the number of characters written into the buffer, includ‐
56 ing the delimiter character if one was encountered before EOF, but
57 excluding the terminating NUL character. If no characters were read,
58 and the end-of-file indicator for the stream is set, or if the stream
59 is at end-of-file, the end-of-file indicator for the stream shall be
60 set and the function shall return −1. If an error occurs, the error
61 indicator for the stream shall be set, and the function shall return −1
62 and set errno to indicate the error.
63
65 For the conditions under which the getdelim() and getline() functions
66 shall fail and may fail, refer to fgetc().
67 In addition, these functions shall fail if:
69 EINVAL lineptr or n is a null pointer.
71 ENOMEM Insufficient memory is available.
73 These functions may fail if:
75 EOVERFLOW
77 More than {SSIZE_MAX} characters were read without encountering
78 the delimiter character.
79 The following sections are informative.
81
83 #include <stdio.h>
84 #include <stdlib.h>
85 int main(void)
87 {
88 FILE *fp;
89 char *line = NULL;
90 size_t len = 0;
91 ssize_t read;
92 fp = fopen("/etc/motd", "r");
93 if (fp == NULL)
94 exit(1);
95 while ((read = getline(&line, &len, fp)) != -1) {
96 printf("Retrieved line of length %zu :\n", read);
97 printf("%s", line);
98 }
99 if (ferror(fp)) {
100 /* handle error */
101 }
102 free(line);
103 fclose(fp);
104 return 0;
105 }
106
108 Setting *lineptr to a null pointer and *n to zero are allowed and a
109 recommended way to start parsing a file.
110 The ferror() or feof() functions should be used to distinguish between
112 an error condition and an end-of-file condition.
113 Although a NUL terminator is always supplied after the line, note that
115 strlen(*lineptr) will be smaller than the return value if the line con‐
116 tains embedded NUL characters.
117
119 These functions are widely used to solve the problem that the fgets()
120 function has with long lines. The functions automatically enlarge the
121 target buffers if needed. These are especially useful since they reduce
122 code needed for applications.
123
125 None.
126
128 Section 2.5, Standard I/O Streams, fgetc(), fgets(), free()
129 The Base Definitions volume of POSIX.1‐2008, <stdio.h>
131
133 Portions of this text are reprinted and reproduced in electronic form
134 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
135 -- Portable Operating System Interface (POSIX), The Open Group Base
136 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
137 cal and Electronics Engineers, Inc and The Open Group. (This is
138 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
139 event of any discrepancy between this version and the original IEEE and
140 The Open Group Standard, the original IEEE and The Open Group Standard
141 is the referee document. The original Standard can be obtained online
142 at http://www.unix.org/online.html .
143 Any typographical or formatting errors that appear in this page are
145 most likely to have been introduced during the conversion of the source
146 files to man page format. To report such errors, see https://www.ker‐
147 nel.org/doc/man-pages/reporting_bugs.html .
148IEEE/The Open Group 2013 GETDELIM(3P)