lib/libc/stdio/getdelim.3

   1 .\"     $NetBSD: getdelim.3,v 1.14 2014/09/16 08:52:02 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 2009 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Roy Marples.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd September 15, 2014
  31 .Dt GETDELIM 3
  32 .Os
  33 .Sh NAME
  34 .Nm getdelim ,
  35 .Nm getline
  36 .Nd read a delimited record from a stream
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .In stdio.h
  41 .Ft ssize_t
  42 .Fn getdelim "char ** restrict lineptr" "size_t * restrict n" "int delimiter" "FILE * restrict stream"
  43 .Ft ssize_t
  44 .Fn getline "char ** restrict lineptr" "size_t * restrict n" "FILE * restrict stream"
  45 .Sh DESCRIPTION
  46 The
  47 .Fn getdelim
  48 function reads from the
  49 .Fa stream
  50 until it encounters a character matching
  51 .Fa delimiter
  52 or
  53 .Dv EOF ,
  54 storing the input in
  55 .Fa *lineptr .
  56 The buffer is
  57 .Dv NUL Ns No -terminated
  58 and includes the delimiter, if one was found.
  59 The
  60 .Fa delimiter
  61 character must be representable as an unsigned char.
  62 .Pp
  63 If
  64 .Fa *n
  65 is non-zero, then
  66 .Fa *lineptr
  67 must be pre-allocated to at least
  68 .Fa *n
  69 bytes.
  70 The buffer should be allocated dynamically;
  71 it must be possible to
  72 .Xr free 3
  73 .Fa *lineptr .
  74 .Fn getdelim
  75 ensures that
  76 .Fa *lineptr
  77 is large enough to hold the input, updating
  78 .Fa *n
  79 to reflect the new size.
  80 .Pp
  81 The
  82 .Fn getline
  83 function is equivalent to
  84 .Fn getdelim
  85 with
  86 .Fa delimiter
  87 set to the newline character.
  88 .Sh RETURN VALUES
  89 The
  90 .Fn getdelim
  91 and
  92 .Fn getline
  93 functions return the number of characters read, including the delimiter if
  94 one was found.
  95 If no characters were read and the stream is at end-of-file, the functions
  96 return \-1.
  97 If an error occurs, the functions return \-1 and the global variable
  98 .Va errno
  99 is set to indicate the error.
 100 .Pp
 101 The functions do not distinguish between end-of-file and error,
 102 and callers must use
 103 .Xr feof 3
 104 and
 105 .Xr ferror 3
 106 to determine which occurred.
 107 .Sh EXAMPLES
 108 The following code fragment reads lines from a file and writes them to
 109 standard output.
 110 .Bd -literal -offset indent
 111 char *line = NULL;
 112 size_t linesize = 0;
 113 ssize_t linelen;
 114
 115 while ((linelen = getline(\*[Am]line, \*[Am]linesize, fp)) != -1)
 116         fwrite(line, linelen, 1, stdout);
 117
 118 if (ferror(fp))
 119         perror("getline");
 120 .Ed
 121 .Sh ERRORS
 122 .Bl -tag -width [EOVERFLOW]
 123 .It Bq Er EINVAL
 124 .Fa lineptr
 125 or
 126 .Fa n
 127 is a
 128 .Dv NULL
 129 pointer.
 130 .It Bq Er EOVERFLOW
 131 More than SSIZE_MAX characters were read without encountering the delimiter.
 132 .El
 133 .Pp
 134 The
 135 .Fn getdelim
 136 and
 137 .Fn getline
 138 functions may also fail and set
 139 .Va errno
 140 for any of the errors specified in the routines
 141 .Xr fflush 3 ,
 142 .Xr malloc 3 ,
 143 .Xr read 2 ,
 144 .Xr stat 2 ,
 145 or
 146 .Xr realloc 3 .
 147 .Sh SEE ALSO
 148 .Xr ferror 3 ,
 149 .Xr fgets 3 ,
 150 .Xr fopen 3 ,
 151 .Xr strlen 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 NOTES
 160 The
 161 .Fn getdelim
 162 and
 163 .Fn getline
 164 functions can return results that include
 165 .Dv NUL
 166 characters, which can cause the apparent length reported by
 167 .Xr strlen 3
 168 to be less than the true length reported by the
 169 return values of the functions.