lib/libutil/fparseln.3

   1 .\"     $NetBSD: fparseln.3,v 1.7 1999/07/02 15:49:12 simonb Exp $
   2 .\"
   3 .\" Copyright (c) 1997 Christos Zoulas.  All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\" 3. All advertising materials mentioning features or use of this software
  14 .\"    must display the following acknowledgement:
  15 .\"     This product includes software developed by Christos Zoulas.
  16 .\" 4. The name of the author may not be used to endorse or promote products
  17 .\"    derived from this software without specific prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  20 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  21 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  22 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  23 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  24 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  25 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  26 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  27 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  28 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd December 1, 1997
  31 .Dt FPARSELN 3
  32 .Os
  33 .Sh NAME
  34 .Nm fparseln
  35 .Nd return the next logical line from a stream
  36 .Sh LIBRARY
  37 .Lb libutil
  38 .Sh SYNOPSIS
  39 .In stdio.h
  40 .In libutil.h
  41 .Ft "char *"
  42 .Fo fparseln
  43 .Fa "FILE *stream" "size_t *len" "size_t *lineno"
  44 .Fa "const char delim[3]" "int flags"
  45 .Fc
  46 .Sh DESCRIPTION
  47 The
  48 .Fn fparseln
  49 function
  50 returns a pointer to the next logical line from the stream referenced by
  51 .Fa stream .
  52 This string is
  53 .Dv NUL
  54 terminated and it is dynamically allocated on each invocation.
  55 It is the
  56 responsibility of the caller to free the pointer.
  57 .Pp
  58 By default, if a character is escaped, both it and the preceding escape
  59 character will be present in the returned string.
  60 Various
  61 .Fa flags
  62 alter this behaviour.
  63 .Pp
  64 The meaning of the arguments is as follows:
  65 .Bl -tag -width "lineno"
  66 .It Fa stream
  67 The stream to read from.
  68 .It Fa len
  69 If not
  70 .Dv NULL ,
  71 the length of the string is stored in the memory location to which it
  72 points.
  73 .It Fa lineno
  74 If not
  75 .Dv NULL ,
  76 the value of the memory location to which is pointed to, is incremented
  77 by the number of lines actually read from the file.
  78 .It Fa delim
  79 Contains the escape, continuation, and comment characters.
  80 If a character is
  81 .Dv NUL
  82 then processing for that character is disabled.
  83 If
  84 .Dv NULL ,
  85 all characters default to values specified below.
  86 The contents of
  87 .Fa delim
  88 is as follows:
  89 .Bl -tag -width "delim[0]"
  90 .It Fa delim[0]
  91 The escape character, which defaults to
  92 .Cm \e ,
  93 is used to remove any special meaning from the next character.
  94 .It Fa delim[1]
  95 The continuation character, which defaults to
  96 .Cm \e ,
  97 is used to indicate that the next line should be concatenated with the
  98 current one if this character is the last character on the current line
  99 and is not escaped.
 100 .It Fa delim[2]
 101 The comment character, which defaults to
 102 .Cm # ,
 103 if not escaped indicates the beginning of a comment that extends until the
 104 end of the current line.
 105 .El
 106 .It Fa flags
 107 If non-zero, alter the operation of
 108 .Fn fparseln .
 109 The various flags, which may be
 110 .Em or Ns -ed
 111 together, are:
 112 .Bl -tag -width "FPARSELN_UNESCCOMM"
 113 .It Dv FPARSELN_UNESCCOMM
 114 Remove escape preceding an escaped comment.
 115 .It Dv FPARSELN_UNESCCONT
 116 Remove escape preceding an escaped continuation.
 117 .It Dv FPARSELN_UNESCESC
 118 Remove escape preceding an escaped escape.
 119 .It Dv FPARSELN_UNESCREST
 120 Remove escape preceding any other character.
 121 .It Dv FPARSELN_UNESCALL
 122 All of the above.
 123 .El
 124 .El
 125 .Sh RETURN VALUES
 126 Upon successful completion a pointer to the parsed line is returned;
 127 otherwise,
 128 .Dv NULL
 129 is returned.
 130 .Pp
 131 The
 132 .Fn fparseln
 133 function uses internally
 134 .Xr fgetln 3 ,
 135 so all error conditions that apply to
 136 .Xr fgetln 3 ,
 137 apply to
 138 .Fn fparseln .
 139 In addition
 140 .Fn fparseln
 141 may set
 142 .Va errno
 143 to
 144 .Er ENOMEM
 145 and return
 146 .Dv NULL
 147 if it runs out of memory.
 148 .Sh SEE ALSO
 149 .Xr fgetln 3
 150 .Sh HISTORY
 151 The
 152 .Fn fparseln
 153 function first appeared in
 154 .Nx 1.4
 155 and
 156 .Fx 4.0 .