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  2014-08-19 "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 .sp
  33 .BI "ssize_t getline(char **" lineptr ", size_t *" n ", FILE *" stream );
  34
  35 .BI "ssize_t getdelim(char **" lineptr ", size_t *" n ", int " delim \
  36 ", FILE *" stream );
  37 .fi
  38 .sp
  39 .in -4n
  40 Feature Test Macro Requirements for glibc (see
  41 .BR feature_test_macros (7)):
  42 .in
  43 .sp
  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 || _XOPEN_SOURCE\ >=\ 700
  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
  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
  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
  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
 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\\0\(aq).
 119 This value can be used
 120 to handle embedded null bytes in the line read.
 121
 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 .SH CONFORMING TO
 138 Both
 139 .BR getline ()
 140 and
 141 .BR getdelim ()
 142 were originally GNU extensions.
 143 They were standardized in POSIX.1-2008.
 144 .SH EXAMPLE
 145 .nf
 146 #define _GNU_SOURCE
 147 #include <stdio.h>
 148 #include <stdlib.h>
 149
 150 int
 151 main(void)
 152 {
 153     FILE *fp;
 154     char *line = NULL;
 155     size_t len = 0;
 156     ssize_t read;
 157
 158     fp = fopen("/etc/motd", "r");
 159     if (fp == NULL)
 160         exit(EXIT_FAILURE);
 161
 162     while ((read = getline(&line, &len, fp)) != \-1) {
 163         printf("Retrieved line of length %zu :\en", read);
 164         printf("%s", line);
 165     }
 166
 167     free(line);
 168     fclose(fp);
 169     exit(EXIT_SUCCESS);
 170 }
 171 .fi
 172 .SH SEE ALSO
 173 .BR read (2),
 174 .BR fgets (3),
 175 .BR fopen (3),
 176 .BR fread (3),
 177 .BR scanf (3)