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: head/lib/libc/stdio/getline.3 303524 2016-07-30 01:00:16Z bapt $
  26 .\"
  27 .Dd January 16, 2019
  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 .In stdio.h
  38 .Ft ssize_t
  39 .Fn getdelim "char ** restrict linep" "size_t * restrict linecapp" "int delimiter" "FILE * restrict stream"
  40 .Ft ssize_t
  41 .Fn getline "char ** restrict linep" "size_t * restrict linecapp" "FILE * restrict stream"
  42 .Sh DESCRIPTION
  43 The
  44 .Fn getdelim
  45 function reads a line from
  46 .Fa stream ,
  47 delimited by the character
  48 .Fa delimiter .
  49 The
  50 .Fn getline
  51 function is equivalent to
  52 .Fn getdelim
  53 with the newline character as the delimiter.
  54 The delimiter character is included as part of the line, unless
  55 the end of the file is reached.
  56 .Pp
  57 The caller may provide a pointer to a malloced buffer for the line in
  58 .Fa *linep ,
  59 and the capacity of that buffer in
  60 .Fa *linecapp .
  61 These functions expand the buffer as needed, as if via
  62 .Fn realloc .
  63 If
  64 .Fa linep
  65 points to a
  66 .Dv NULL
  67 pointer, a new buffer will be allocated.
  68 In either case,
  69 .Fa *linep
  70 and
  71 .Fa *linecapp
  72 will be updated accordingly.
  73 .Sh RETURN VALUES
  74 The
  75 .Fn getdelim
  76 and
  77 .Fn getline
  78 functions return the number of characters stored in the buffer, excluding the
  79 terminating
  80 .Dv NUL
  81 character.
  82 The value \-1 is returned if an error occurs, or if end-of-file is reached.
  83 .Pp
  84 The functions do not distinguish between end-of-file and error,
  85 and callers must use
  86 .Xr feof 3
  87 and
  88 .Xr ferror 3
  89 to determine which occurred.
  90 .Sh EXAMPLES
  91 The following code fragment reads lines from a file and
  92 writes them to standard output.
  93 The
  94 .Fn fwrite
  95 function is used in case the line contains embedded
  96 .Dv NUL
  97 characters.
  98 .Bd -literal -offset indent
  99 char *line = NULL;
 100 size_t linecap = 0;
 101 ssize_t linelen;
 102
 103 while ((linelen = getline(&line, &linecap, fp)) > 0)
 104         fwrite(line, linelen, 1, stdout);
 105
 106 free(line);
 107 if (ferror(fp))
 108         perror("getline");
 109 .Ed
 110 .Sh ERRORS
 111 These functions may fail if:
 112 .Bl -tag -width Er
 113 .It Bq Er EINVAL
 114 Either
 115 .Fa linep
 116 or
 117 .Fa linecapp
 118 is
 119 .Dv NULL .
 120 .It Bq Er EOVERFLOW
 121 No delimiter was found in the first
 122 .Dv SSIZE_MAX
 123 characters.
 124 .El
 125 .Pp
 126 These functions may also fail due to any of the errors specified for
 127 .Fn fgets
 128 and
 129 .Fn malloc .
 130 .Sh SEE ALSO
 131 .Xr ferror 3 ,
 132 .Xr fgetln 3 ,
 133 .Xr fgets 3 ,
 134 .Xr malloc 3
 135 .Sh STANDARDS
 136 The
 137 .Fn getdelim
 138 and
 139 .Fn getline
 140 functions conform to
 141 .St -p1003.1-2008 .
 142 .Sh HISTORY
 143 These routines first appeared in
 144 .Dx 2.3 .
 145 .Sh BUGS
 146 There are no wide character versions of
 147 .Fn getdelim
 148 or
 149 .Fn getline .