man3/getline.3

   1 '\" t
   2 .\" Copyright (c) 2001 John Levon <moz@compsoc.man.ac.uk>
   3 .\" Based in part on GNU libc documentation
   4 .\"
   5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   6 .\"
   7 .TH getline 3 (date) "Linux man-pages (unreleased)"
   8 .SH NAME
   9 getline, getdelim \- delimited string input
  10 .SH LIBRARY
  11 Standard C library
  12 .RI ( libc ", " \-lc )
  13 .SH SYNOPSIS
  14 .nf
  15 .B #include <stdio.h>
  16 .PP
  17 .BI "ssize_t getline(char **restrict " lineptr ", size_t *restrict " n ,
  18 .BI "                FILE *restrict " stream );
  19 .BI "ssize_t getdelim(char **restrict " lineptr ", size_t *restrict " n ,
  20 .BI "                int " delim ", FILE *restrict " stream );
  21 .fi
  22 .PP
  23 .RS -4
  24 Feature Test Macro Requirements for glibc (see
  25 .BR feature_test_macros (7)):
  26 .RE
  27 .PP
  28 .BR getline (),
  29 .BR getdelim ():
  30 .nf
  31     Since glibc 2.10:
  32         _POSIX_C_SOURCE >= 200809L
  33     Before glibc 2.10:
  34         _GNU_SOURCE
  35 .fi
  36 .SH DESCRIPTION
  37 .BR getline ()
  38 reads an entire line from \fIstream\fP,
  39 storing the address of the buffer containing the text into
  40 .IR *lineptr .
  41 The buffer is null-terminated and includes the newline character, if
  42 one was found.
  43 .PP
  44 If
  45 .I *lineptr
  46 is set to NULL before the call, then
  47 .BR getline ()
  48 will allocate a buffer for storing the line.
  49 This buffer should be freed by the user program
  50 even if
  51 .BR getline ()
  52 failed.
  53 .PP
  54 Alternatively, before calling
  55 .BR getline (),
  56 .I *lineptr
  57 can contain a pointer to a
  58 .BR malloc (3)\-allocated
  59 buffer
  60 .I *n
  61 bytes in size.
  62 If the buffer is not large enough to hold the line,
  63 .BR getline ()
  64 resizes it with
  65 .BR realloc (3),
  66 updating
  67 .I *lineptr
  68 and
  69 .I *n
  70 as necessary.
  71 .PP
  72 In either case, on a successful call,
  73 .I *lineptr
  74 and
  75 .I *n
  76 will be updated to reflect the buffer address and allocated size respectively.
  77 .PP
  78 .BR getdelim ()
  79 works like
  80 .BR getline (),
  81 except that a line delimiter other than newline can be specified as the
  82 .I delimiter
  83 argument.
  84 As with
  85 .BR getline (),
  86 a delimiter character is not added if one was not present
  87 in the input before end of file was reached.
  88 .SH RETURN VALUE
  89 On success,
  90 .BR getline ()
  91 and
  92 .BR getdelim ()
  93 return the number of characters read, including the delimiter character,
  94 but not including the terminating null byte (\[aq]\e0\[aq]).
  95 This value can be used
  96 to handle embedded null bytes in the line read.
  97 .PP
  98 Both functions return \-1 on failure to read a line (including end-of-file
  99 condition).
 100 In the event of a failure,
 101 .I errno
 102 is set to indicate the error.
 103 .PP
 104 If
 105 .I *lineptr
 106 was set to NULL before the call, then the buffer should be freed by the
 107 user program even on failure.
 108 .SH ERRORS
 109 .TP
 110 .B EINVAL
 111 Bad arguments
 112 .RI ( n
 113 or
 114 .I lineptr
 115 is NULL, or
 116 .I stream
 117 is not valid).
 118 .TP
 119 .B ENOMEM
 120 Allocation or reallocation of the line buffer failed.
 121 .SH ATTRIBUTES
 122 For an explanation of the terms used in this section, see
 123 .BR attributes (7).
 124 .ad l
 125 .nh
 126 .TS
 127 allbox;
 128 lbx lb lb
 129 l l l.
 130 Interface       Attribute       Value
 131 T{
 132 .BR getline (),
 133 .BR getdelim ()
 134 T}      Thread safety   MT-Safe
 135 .TE
 136 .hy
 137 .ad
 138 .sp 1
 139 .SH STANDARDS
 140 POSIX.1-2008.
 141 .SH HISTORY
 142 GNU, POSIX.1-2008.
 143 .SH EXAMPLES
 144 .\" SRC BEGIN (getline.c)
 145 .EX
 146 #define _GNU_SOURCE
 147 #include <stdio.h>
 148 #include <stdlib.h>
 149 \&
 150 int
 151 main(int argc, char *argv[])
 152 {
 153     FILE *stream;
 154     char *line = NULL;
 155     size_t len = 0;
 156     ssize_t nread;
 157 \&
 158     if (argc != 2) {
 159         fprintf(stderr, "Usage: %s <file>\en", argv[0]);
 160         exit(EXIT_FAILURE);
 161     }
 162 \&
 163     stream = fopen(argv[1], "r");
 164     if (stream == NULL) {
 165         perror("fopen");
 166         exit(EXIT_FAILURE);
 167     }
 168 \&
 169     while ((nread = getline(&line, &len, stream)) != \-1) {
 170         printf("Retrieved line of length %zd:\en", nread);
 171         fwrite(line, nread, 1, stdout);
 172     }
 173 \&
 174     free(line);
 175     fclose(stream);
 176     exit(EXIT_SUCCESS);
 177 }
 178 .EE
 179 .\" SRC END
 180 .SH SEE ALSO
 181 .BR read (2),
 182 .BR fgets (3),
 183 .BR fopen (3),
 184 .BR fread (3),
 185 .BR scanf (3)