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: src/lib/libc/stdio/getline.3,v 1.2 2009/04/06 13:50:04 das Exp $
  26 .\"
  27 .Dd March 29, 2009
  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 The caller may provide a pointer to a malloc buffer for the line in
  58 .Fa *linep ,
  59 and the capacity of that buffer in
  60 .Fa *linecapp ;
  61 if
  62 .Fa *linecapp
  63 is 0, then
  64 .Fa *linep
  65 is treated as
  66 .Dv NULL .
  67 These functions may expand the buffer as needed, as if via
  68 .Fn realloc ,
  69 and update
  70 .Fa *linep
  71 and
  72 .Fa *linecapp
  73 accordingly.
  74 .Sh RETURN VALUES
  75 The
  76 .Fn getdelim
  77 and
  78 .Fn getline
  79 functions return the number of characters written, excluding the
  80 terminating
  81 .Dv NUL .
  82 The value \-1 is returned if an error occurs, or if end-of-file is reached.
  83 .Sh EXAMPLES
  84 The following code fragment reads lines from a file and
  85 writes them to standard output.
  86 The
  87 .Fn fwrite
  88 function is used in case the line contains embedded
  89 .Dv NUL
  90 characters.
  91 .Bd -literal -offset indent
  92 char *line = NULL;
  93 size_t linecap = 0;
  94 ssize_t linelen;
  95 while ((linelen = getline(&line, &linecap, fp)) > 0)
  96         fwrite(line, linelen, 1, stdout);
  97 .Ed
  98 .Sh COMPATIBILITY
  99 Many application writers used the name
 100 .Va getline
 101 before the
 102 .Fn getline
 103 function was introduced in
 104 .St -p1003.1 ,
 105 so a prototype is not provided by default in order to avoid
 106 compatibility problems.
 107 Applications that wish to use the
 108 .Fn getline
 109 function described herein should either request a strict
 110 .St -p1003.1-2008
 111 environment by defining the macro
 112 .Dv _POSIX_C_SOURCE
 113 to the value 200809 or greater, or by defining the macro
 114 .Dv _WITH_GETLINE ,
 115 prior to the inclusion of
 116 .In stdio.h .
 117 For compatibility with GNU libc, defining either
 118 .Dv _BSD_SOURCE
 119 or
 120 .Dv _GNU_SOURCE
 121 prior to the inclusion of
 122 .In stdio.h
 123 will also make
 124 .Fn getline
 125 available.
 126 .Sh ERRORS
 127 These functions may fail if:
 128 .Bl -tag -width Er
 129 .It Bq Er EINVAL
 130 Either
 131 .Fa linep
 132 or
 133 .Fa linecapp
 134 is
 135 .Dv NULL .
 136 .It Bq Er EOVERFLOW
 137 No delimiter was found in the first
 138 .Dv SSIZE_MAX
 139 characters.
 140 .El
 141 .Pp
 142 These functions may also fail for any of the errors specified for
 143 .Fn fgets
 144 and
 145 .Fn malloc .
 146 .Sh SEE ALSO
 147 .Xr fgetln 3 ,
 148 .Xr fgets 3 ,
 149 .Xr malloc 3
 150 .Sh STANDARDS
 151 The
 152 .Fn getdelim
 153 and
 154 .Fn getline
 155 functions conform to
 156 .St -p1003.1-2008 .
 157 .Sh HISTORY
 158 These routines first appeared in
 159 .Dx 2.3 .
 160 .Sh BUGS
 161 There are no wide character versions of
 162 .Fn getdelim
 163 or
 164 .Fn getline .