original/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-04-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 .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 VERSIONS
 138 These functions are available since libc 4.6.27.
 139 .SH CONFORMING TO
 140 Both
 141 .BR getline ()
 142 and
 143 .BR getdelim ()
 144 were originally GNU extensions.
 145 They were standardized in POSIX.1-2008.
 146 .SH EXAMPLE
 147 .nf
 148 #define _GNU_SOURCE
 149 #include <stdio.h>
 150 #include <stdlib.h>
 151
 152 int
 153 main(void)
 154 {
 155     FILE *fp;
 156     char *line = NULL;
 157     size_t len = 0;
 158     ssize_t read;
 159
 160     fp = fopen("/etc/motd", "r");
 161     if (fp == NULL)
 162         exit(EXIT_FAILURE);
 163
 164     while ((read = getline(&line, &len, fp)) != \-1) {
 165         printf("Retrieved line of length %zu :\en", read);
 166         printf("%s", line);
 167     }
 168
 169     free(line);
 170     exit(EXIT_SUCCESS);
 171 }
 172 .fi
 173 .SH SEE ALSO
 174 .BR read (2),
 175 .BR fgets (3),
 176 .BR fopen (3),
 177 .BR fread (3),
 178 .BR scanf (3)
 179 .SH COLOPHON
 180 This page is part of release 3.68 of the Linux
 181 .I man-pages
 182 project.
 183 A description of the project,
 184 information about reporting bugs,
 185 and the latest version of this page,
 186 can be found at
 187 \%http://www.kernel.org/doc/man\-pages/.