1GETDELIM(3P)               POSIX Programmer's Manual              GETDELIM(3P)
2
3
4

PROLOG

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

NAME

12       getdelim, getline — read a delimited record from stream
13

SYNOPSIS

15       #include <stdio.h>
16
17       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

DESCRIPTION

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
30       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
35       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
46       The  getline()  function shall be equivalent to the getdelim() function
47       with the delimiter character equal to the <newline> character.
48
49       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

RETURN VALUE

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

ERRORS

68       For  the  conditions under which the getdelim() and getline() functions
69       shall fail and may fail, refer to fgetc().
70
71       In addition, these functions shall fail if:
72
73       EINVAL lineptr or n is a null pointer.
74
75       ENOMEM Insufficient memory is available.
76
77       These functions may fail if:
78
79       EOVERFLOW
80              The number of bytes to be written into the buffer, including the
81              delimiter character (if encountered), would exceed {SSIZE_MAX}.
82
83       The following sections are informative.
84

EXAMPLES

86           #include <stdio.h>
87           #include <stdlib.h>
88
89           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

APPLICATION USAGE

111       Setting  *lineptr  to  a  null pointer and *n to zero are allowed and a
112       recommended way to start parsing a file.
113
114       The ferror() or feof() functions should be used to distinguish  between
115       an error condition and an end-of-file condition.
116
117       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

RATIONALE

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

FUTURE DIRECTIONS

128       None.
129

SEE ALSO

131       Section 2.5, Standard I/O Streams, fgetc(), fgets(), free(),  malloc(),
132       realloc()
133
134       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
147       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 .
151
152
153
154IEEE/The Open Group                  2017                         GETDELIM(3P)
Impressum