lib/libc/stdio/getdelim.3

   1 .\"     $NetBSD: getdelim.3,v 1.9 2011/04/20 23:37:51 enami 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 June 30, 2010
  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 storing the input in
  53 .Fa *lineptr .
  54 The buffer is
  55 .Dv NUL Ns No -terminated
  56 and includes the delimiter.
  57 The
  58 .Fa delimiter
  59 character must be representable as an unsigned char.
  60 .Pp
  61 If
  62 .Fa *n
  63 is non-zero, then
  64 .Fa *lineptr
  65 must be pre-allocated to at least
  66 .Fa *n
  67 bytes.
  68 The buffer should be allocated dynamically;
  69 it must be possible to
  70 .Xr free 3
  71 .Fa *lineptr .
  72 .Fn getdelim
  73 ensures that
  74 .Fa *lineptr
  75 is large enough to hold the input, updating
  76 .Fa *n
  77 to reflect the new size.
  78 .Pp
  79 The
  80 .Fn getline
  81 function is equivalent to
  82 .Fn getdelim
  83 with
  84 .Fa delimiter
  85 set to the newline character.
  86 .Sh RETURN VALUES
  87 The
  88 .Fn getdelim
  89 and
  90 .Fn getline
  91 functions return the number of characters read, including the delimiter.
  92 If no characters were read and the stream is at end-of-file, the functions
  93 return \-1.
  94 If an error occurs, the functions return \-1 and the global variable
  95 .Va errno
  96 is set to indicate the error.
  97 .Pp
  98 The functions do not distinguish between end-of-file and error,
  99 and callers must use
 100 .Xr feof 3
 101 and
 102 .Xr ferror 3
 103 to determine which occurred.
 104 .Sh EXAMPLES
 105 The following code fragment reads lines from a file and writes them to
 106 standard output.
 107 .Bd -literal -offset indent
 108 char *line = NULL;
 109 size_t linesize = 0;
 110 ssize_t linelen;
 111
 112 while ((linelen = getline(\*[Am]line, \*[Am]linesize, fp)) != -1)
 113         fwrite(line, linelen, 1, stdout);
 114
 115 if (ferror(fp))
 116         perror("getline");
 117 .Ed
 118 .Sh ERRORS
 119 .Bl -tag -width [EOVERFLOW]
 120 .It Bq Er EINVAL
 121 .Fa lineptr
 122 or
 123 .Fa n
 124 is a
 125 .Dv NULL
 126 pointer.
 127 .It Bq Er EOVERFLOW
 128 More than SSIZE_MAX characters were read without encountering the delimiter.
 129 .El
 130 .Pp
 131 The
 132 .Fn getdelim
 133 and
 134 .Fn getline
 135 functions may also fail and set
 136 .Va errno
 137 for any of the errors specified in the routines
 138 .Xr fflush 3 ,
 139 .Xr malloc 3 ,
 140 .Xr read 2 ,
 141 .Xr stat 2 ,
 142 or
 143 .Xr realloc 3 .
 144 .Sh SEE ALSO
 145 .Xr ferror 3 ,
 146 .Xr fgets 3 ,
 147 .Xr fopen 3
 148 .Sh STANDARDS
 149 The
 150 .Fn getdelim
 151 and
 152 .Fn getline
 153 functions conform to
 154 .St -p1003.1-2008 .