NAME
getdelim,
getline —
read a delimited record from a stream
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <stdio.h>
ssize_t
getdelim(
char **
restrict lineptr,
size_t *
restrict n,
int
delimiter,
FILE * restrict
stream);
ssize_t
getline(
char **
restrict lineptr,
size_t *
restrict n,
FILE * restrict
stream);
DESCRIPTION
The
getdelim() function reads from the
stream until it encounters a character matching
delimiter or
EOF
, storing the
input in
*lineptr. The buffer is
NUL
-terminated and includes
the delimiter, if one was found. The
delimiter character
must be representable as an unsigned char.
If
*n is non-zero, then
*lineptr
must be pre-allocated to at least
*n bytes. The buffer
should be allocated dynamically; it must be possible to
free(3)
*lineptr.
getdelim() ensures that
*lineptr is large enough to hold the input, updating
*n to reflect the new size.
The
getline() function is equivalent to
getdelim() with
delimiter set to the
newline character.
RETURN VALUES
The
getdelim() and
getline() functions
return the number of characters read, including the delimiter if one was
found. If no characters were read and the stream is at end-of-file, the
functions return -1. If an error occurs, the functions return -1 and the
global variable
errno is set to indicate the error.
The functions do not distinguish between end-of-file and error, and callers must
use
feof(3) and
ferror(3) to determine which
occurred.
EXAMPLES
The following code fragment reads lines from a file and writes them to standard
output.
char *line = NULL;
size_t linesize = 0;
ssize_t linelen;
while ((linelen = getline(&line, &linesize, fp)) != -1)
fwrite(line, linelen, 1, stdout);
if (ferror(fp))
perror("getline");
ERRORS
-
-
- [
EINVAL
]
- lineptr or n is
a
NULL
pointer.
-
-
- [
EOVERFLOW
]
- More than SSIZE_MAX characters were read without
encountering the delimiter.
The
getdelim() and
getline() functions may
also fail and set
errno for any of the errors specified
in the routines
fflush(3),
malloc(3),
read(2),
stat(2), or
realloc(3).
SEE ALSO
ferror(3),
fgets(3),
fopen(3),
strlen(3)
STANDARDS
The
getdelim() and
getline() functions
conform to
IEEE Std 1003.1-2008
(“POSIX.1”).
NOTES
The
getdelim() and
getline() functions can
return results that include
NUL
characters, which can
cause the apparent length reported by
strlen(3) to be less than the
true length reported by the return values of the functions.