getline(3)

1GETLINE(3)                 Linux Programmer's Manual                GETLINE(3)
2
3
4

NAME

6       getline, getdelim - delimited string input
7

SYNOPSIS

9       #define _GNU_SOURCE
10       #include <stdio.h>
11
12       ssize_t getline(char **lineptr, size_t *n, FILE *stream);
13       ssize_t getdelim(char **lineptr, size_t *n, int delim, FILE *stream);
14

DESCRIPTION

16       getline()  reads an entire line from stream, storing the address of the
17       buffer containing the text into *lineptr.  The  buffer  is  null-termi‐
18       nated and includes the newline character, if one was found.
19
20       If  *lineptr is NULL, then getline() will allocate a buffer for storing
21       the line, which should be freed by the  user  program.   Alternatively,
22       before  calling  getline(),  *lineptr  can  contain a pointer to a mal‐
23       loc()-allocated buffer *n bytes in size. If the  buffer  is  not  large
24       enough  to hold the line, getline() resizes it with realloc(), updating
25       *lineptr and *n as necessary. In either case,  on  a  successful  call,
26       *lineptr and *n will be updated to reflect the buffer address and allo‐
27       cated size respectively.
28
29       getdelim() works like getline(), except a  line  delimiter  other  than
30       newline  can be specified as the delimiter argument. As with getline(),
31       a delimiter character is not added if one was not present in the  input
32       before end of file was reached.
33

RETURN VALUE

35       On  success,  getline()  and getdelim() return the number of characters
36       read, including the delimiter character, but not including  the  termi‐
37       nating  null byte. This value can be used to handle embedded null bytes
38       in the line read.
39
40       Both functions return -1  on failure to read a line (including  end  of
41       file condition).
42

ERRORS

44       EINVAL Bad parameters (n or lineptr is NULL, or stream is not valid).
45

EXAMPLE

47       #define _GNU_SOURCE
48       #include <stdio.h>
49       #include <stdlib.h>
50
51       int main(void)
52       {
53            FILE * fp;
54            char * line = NULL;
55            size_t len = 0;
56            ssize_t read;
57            fp = fopen("/etc/motd", "r");
58            if (fp == NULL)
59                 exit(EXIT_FAILURE);
60            while ((read = getline(&line, &len, fp)) != -1) {
61                 printf("Retrieved line of length %zu :\n", read);
62                 printf("%s", line);
63            }
64            if (line)
65                 free(line);
66            return EXIT_SUCCESS;
67       }
68

CONFORMING TO

70       Both  getline()  and getdelim() are GNU extensions.  They are available
71       since libc 4.6.27.
72