lib/libc/stdio/getdelim.3

   1 .\"     $NetBSD: getdelim.3,v 1.8 2010/06/30 13:38:10 jruoho 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 while ((linelen = getline(\*[Am]line, \*[Am]linesize, fp)) != -1)
 112         fwrite(line, linelen, 1, stdout);
 113
 114 if (ferror(fp))
 115         perror("getline");
 116 .Ed
 117 .Sh ERRORS
 118 .Bl -tag -width [EOVERFLOW]
 119 .It Bq Er EINVAL
 120 .Fa *lineptr
 121 or
 122 .Fa *n
 123 is a
 124 .Dv NULL
 125 pointer.
 126 .It Bq Er EOVERFLOW
 127 More than SSIZE_MAX characters were read without encountering the delimiter.
 128 .El
 129 .Pp
 130 The
 131 .Fn getdelim
 132 and
 133 .Fn getline
 134 functions may also fail and set
 135 .Va errno
 136 for any of the errors specified in the routines
 137 .Xr fflush 3 ,
 138 .Xr malloc 3 ,
 139 .Xr read 2 ,
 140 .Xr stat 2 ,
 141 or
 142 .Xr realloc 3 .
 143 .Sh SEE ALSO
 144 .Xr ferror 3 ,
 145 .Xr fgets 3 ,
 146 .Xr fopen 3
 147 .Sh STANDARDS
 148 The
 149 .Fn getdelim
 150 and
 151 .Fn getline
 152 functions conform to
 153 .St -p1003.1-2008 .