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