man3/getline.3

   1 .\" Copyright (c) 2001 John Levon <moz@compsoc.man.ac.uk>
   2 .\" Based in part on GNU libc documentation
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .TH GETLINE 3  2019-03-06 "GNU" "Linux Programmer's Manual"
  27 .SH NAME
  28 getline, getdelim \- delimited string input
  29 .SH SYNOPSIS
  30 .nf
  31 .B #include <stdio.h>
  32 .PP
  33 .BI "ssize_t getline(char **" lineptr ", size_t *" n ", FILE *" stream );
  34 .PP
  35 .BI "ssize_t getdelim(char **" lineptr ", size_t *" n ", int " delim \
  36 ", FILE *" stream );
  37 .fi
  38 .PP
  39 .in -4n
  40 Feature Test Macro Requirements for glibc (see
  41 .BR feature_test_macros (7)):
  42 .in
  43 .PP
  44 .ad l
  45 .BR getline (),
  46 .BR getdelim ():
  47 .PD 0
  48 .RS 4
  49 .TP 4
  50 Since glibc 2.10:
  51 _POSIX_C_SOURCE\ >=\ 200809L
  52 .TP
  53 Before glibc 2.10:
  54 _GNU_SOURCE
  55 .RE
  56 .PD
  57 .ad
  58 .SH DESCRIPTION
  59 .BR getline ()
  60 reads an entire line from \fIstream\fP,
  61 storing the address of the buffer containing the text into
  62 .IR "*lineptr" .
  63 The buffer is null-terminated and includes the newline character, if
  64 one was found.
  65 .PP
  66 If
  67 .I "*lineptr"
  68 is set to NULL and
  69 .I *n
  70 is set 0 before the call, then
  71 .BR getline ()
  72 will allocate a buffer for storing the line.
  73 This buffer should be freed by the user program
  74 even if
  75 .BR getline ()
  76 failed.
  77 .PP
  78 Alternatively, before calling
  79 .BR getline (),
  80 .I "*lineptr"
  81 can contain a pointer to a
  82 .BR malloc (3)\-allocated
  83 buffer
  84 .I "*n"
  85 bytes in size.
  86 If the buffer is not large enough to hold the line,
  87 .BR getline ()
  88 resizes it with
  89 .BR realloc (3),
  90 updating
  91 .I "*lineptr"
  92 and
  93 .I "*n"
  94 as necessary.
  95 .PP
  96 In either case, on a successful call,
  97 .I "*lineptr"
  98 and
  99 .I "*n"
 100 will be updated to reflect the buffer address and allocated size respectively.
 101 .PP
 102 .BR getdelim ()
 103 works like
 104 .BR getline (),
 105 except that a line delimiter other than newline can be specified as the
 106 .I delimiter
 107 argument.
 108 As with
 109 .BR getline (),
 110 a delimiter character is not added if one was not present
 111 in the input before end of file was reached.
 112 .SH RETURN VALUE
 113 On success,
 114 .BR getline ()
 115 and
 116 .BR getdelim ()
 117 return the number of characters read, including the delimiter character,
 118 but not including the terminating null byte (\(aq\e0\(aq).
 119 This value can be used
 120 to handle embedded null bytes in the line read.
 121 .PP
 122 Both functions return \-1 on failure to read a line (including end-of-file
 123 condition).
 124 In the event of an error,
 125 .I errno
 126 is set to indicate the cause.
 127 .SH ERRORS
 128 .TP
 129 .B EINVAL
 130 Bad arguments
 131 .RI ( n
 132 or
 133 .I lineptr
 134 is NULL, or
 135 .I stream
 136 is not valid).
 137 .TP
 138 .B ENOMEM
 139 Allocation or reallocation of the line buffer failed.
 140 .SH ATTRIBUTES
 141 For an explanation of the terms used in this section, see
 142 .BR attributes (7).
 143 .TS
 144 allbox;
 145 lbw21 lb lb
 146 l l l.
 147 Interface       Attribute       Value
 148 T{
 149 .BR getline (),
 150 .BR getdelim ()
 151 T}      Thread safety   MT-Safe
 152 .TE
 153 .sp 1
 154 .SH CONFORMING TO
 155 Both
 156 .BR getline ()
 157 and
 158 .BR getdelim ()
 159 were originally GNU extensions.
 160 They were standardized in POSIX.1-2008.
 161 .SH EXAMPLE
 162 .EX
 163 #define _GNU_SOURCE
 164 #include <stdio.h>
 165 #include <stdlib.h>
 166
 167 int
 168 main(int argc, char *argv[])
 169 {
 170     FILE *stream;
 171     char *line = NULL;
 172     size_t len = 0;
 173     ssize_t nread;
 174
 175     if (argc != 2) {
 176         fprintf(stderr, "Usage: %s <file>\en", argv[0]);
 177         exit(EXIT_FAILURE);
 178     }
 179
 180     stream = fopen(argv[1], "r");
 181     if (stream == NULL) {
 182         perror("fopen");
 183         exit(EXIT_FAILURE);
 184     }
 185
 186     while ((nread = getline(&line, &len, stream)) != \-1) {
 187         printf("Retrieved line of length %zu:\en", nread);
 188         fwrite(line, nread, 1, stdout);
 189     }
 190
 191     free(line);
 192     fclose(stream);
 193     exit(EXIT_SUCCESS);
 194 }
 195 .EE
 196 .SH SEE ALSO
 197 .BR read (2),
 198 .BR fgets (3),
 199 .BR fopen (3),
 200 .BR fread (3),
 201 .BR scanf (3)