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 .Ed
  99 .Sh COMPATIBILITY
 100 Many application writers used the name
 101 .Va getline
 102 before the
 103 .Fn getline
 104 function was introduced in
 105 .St -p1003.1 ,
 106 so a prototype is not provided by default in order to avoid
 107 compatibility problems.
 108 Applications that wish to use the
 109 .Fn getline
 110 function described herein should either request a strict
 111 .St -p1003.1-2008
 112 environment by defining the macro
 113 .Dv _POSIX_C_SOURCE
 114 to the value 200809 or greater, or by defining the macro
 115 .Dv _WITH_GETLINE ,
 116 prior to the inclusion of
 117 .In stdio.h .
 118 For compatibility with GNU libc, defining either
 119 .Dv _BSD_SOURCE
 120 or
 121 .Dv _GNU_SOURCE
 122 prior to the inclusion of
 123 .In stdio.h
 124 will also make
 125 .Fn getline
 126 available.
 127 .Sh ERRORS
 128 These functions may fail if:
 129 .Bl -tag -width Er
 130 .It Bq Er EINVAL
 131 Either
 132 .Fa linep
 133 or
 134 .Fa linecapp
 135 is
 136 .Dv NULL .
 137 .It Bq Er EOVERFLOW
 138 No delimiter was found in the first
 139 .Dv SSIZE_MAX
 140 characters.
 141 .El
 142 .Pp
 143 These functions may also fail due to any of the errors specified for
 144 .Fn fgets
 145 and
 146 .Fn malloc .
 147 .Sh SEE ALSO
 148 .Xr fgetln 3 ,
 149 .Xr fgets 3 ,
 150 .Xr malloc 3
 151 .Sh STANDARDS
 152 The
 153 .Fn getdelim
 154 and
 155 .Fn getline
 156 functions conform to
 157 .St -p1003.1-2008 .
 158 .Sh HISTORY
 159 These routines first appeared in
 160 .Fx 8.0 .
 161 .Sh BUGS
 162 There are no wide character versions of
 163 .Fn getdelim
 164 or
 165 .Fn getline .