lib/libc/stdio/getline.3

   1 .\" Copyright (c) 2009 David Schultz <das@FreeBSD.org>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd November 30, 2012
  28 .Dt GETLINE 3
  29 .Os
  30 .Sh NAME
  31 .Nm getdelim ,
  32 .Nm getline
  33 .Nd get a line from a stream
  34 .Sh LIBRARY
  35 .Lb libc
  36 .Sh SYNOPSIS
  37 .Fd "#define _WITH_GETLINE"
  38 .In stdio.h
  39 .Ft ssize_t
  40 .Fn getdelim "char ** restrict linep" "size_t * restrict linecapp" "int delimiter" " FILE * restrict stream"
  41 .Ft ssize_t
  42 .Fn getline "char ** restrict linep" "size_t * restrict linecapp" " FILE * restrict stream"
  43 .Sh DESCRIPTION
  44 The
  45 .Fn getdelim
  46 function reads a line from
  47 .Fa stream ,
  48 delimited by the character
  49 .Fa delimiter .
  50 The
  51 .Fn getline
  52 function is equivalent to
  53 .Fn getdelim
  54 with the newline character as the delimiter.
  55 The delimiter character is included as part of the line, unless
  56 the end of the file is reached.
  57 .Pp
  58 The caller may provide a pointer to a malloced buffer for the line in
  59 .Fa *linep ,
  60 and the capacity of that buffer in
  61 .Fa *linecapp .
  62 These functions expand the buffer as needed, as if via
  63 .Fn realloc .
  64 If
  65 .Fa linep
  66 points to a
  67 .Dv NULL
  68 pointer, a new buffer will be allocated.
  69 In either case,
  70 .Fa *linep
  71 and
  72 .Fa *linecapp
  73 will be updated accordingly.
  74 .Sh RETURN VALUES
  75 The
  76 .Fn getdelim
  77 and
  78 .Fn getline
  79 functions return the number of characters stored in the buffer, excluding the
  80 terminating
  81 .Dv NUL
  82 character.
  83 The value \-1 is returned if an error occurs, or if end-of-file is reached.
  84 .Sh EXAMPLES
  85 The following code fragment reads lines from a file and
  86 writes them to standard output.
  87 The
  88 .Fn fwrite
  89 function is used in case the line contains embedded
  90 .Dv NUL
  91 characters.
  92 .Bd -literal -offset indent
  93 char *line = NULL;
  94 size_t linecap = 0;
  95 ssize_t linelen;
  96 while ((linelen = getline(&line, &linecap, fp)) > 0)
  97         fwrite(line, linelen, 1, stdout);
  98 free(line);
  99 .Ed
 100 .Sh COMPATIBILITY
 101 Many application writers used the name
 102 .Va getline
 103 before the
 104 .Fn getline
 105 function was introduced in
 106 .St -p1003.1 ,
 107 so a prototype is not provided by default in order to avoid
 108 compatibility problems.
 109 Applications that wish to use the
 110 .Fn getline
 111 function described herein should either request a strict
 112 .St -p1003.1-2008
 113 environment by defining the macro
 114 .Dv _POSIX_C_SOURCE
 115 to the value 200809 or greater, or by defining the macro
 116 .Dv _WITH_GETLINE ,
 117 prior to the inclusion of
 118 .In stdio.h .
 119 For compatibility with GNU libc, defining either
 120 .Dv _BSD_SOURCE
 121 or
 122 .Dv _GNU_SOURCE
 123 prior to the inclusion of
 124 .In stdio.h
 125 will also make
 126 .Fn getline
 127 available.
 128 .Sh ERRORS
 129 These functions may fail if:
 130 .Bl -tag -width Er
 131 .It Bq Er EINVAL
 132 Either
 133 .Fa linep
 134 or
 135 .Fa linecapp
 136 is
 137 .Dv NULL .
 138 .It Bq Er EOVERFLOW
 139 No delimiter was found in the first
 140 .Dv SSIZE_MAX
 141 characters.
 142 .El
 143 .Pp
 144 These functions may also fail due to any of the errors specified for
 145 .Fn fgets
 146 and
 147 .Fn malloc .
 148 .Sh SEE ALSO
 149 .Xr fgetln 3 ,
 150 .Xr fgets 3 ,
 151 .Xr malloc 3
 152 .Sh STANDARDS
 153 The
 154 .Fn getdelim
 155 and
 156 .Fn getline
 157 functions conform to
 158 .St -p1003.1-2008 .
 159 .Sh HISTORY
 160 These routines first appeared in
 161 .Fx 8.0 .
 162 .Sh BUGS
 163 There are no wide character versions of
 164 .Fn getdelim
 165 or
 166 .Fn getline .