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