contrib/openpam/doc/man/openpam_readlinev.3

   1 .\"-
   2 .\" Copyright (c) 2001-2003 Networks Associates Technology, Inc.
   3 .\" Copyright (c) 2004-2011 Dag-Erling Smørgrav
   4 .\" All rights reserved.
   5 .\"
   6 .\" This software was developed for the FreeBSD Project by ThinkSec AS and
   7 .\" Network Associates Laboratories, the Security Research Division of
   8 .\" Network Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035
   9 .\" ("CBOSS"), as part of the DARPA CHATS research program.
  10 .\"
  11 .\" Redistribution and use in source and binary forms, with or without
  12 .\" modification, are permitted provided that the following conditions
  13 .\" are met:
  14 .\" 1. Redistributions of source code must retain the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer.
  16 .\" 2. Redistributions in binary form must reproduce the above copyright
  17 .\"    notice, this list of conditions and the following disclaimer in the
  18 .\"    documentation and/or other materials provided with the distribution.
  19 .\" 3. The name of the author may not be used to endorse or promote
  20 .\"    products derived from this software without specific prior written
  21 .\"    permission.
  22 .\"
  23 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  24 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  25 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  26 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  27 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  28 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  29 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  30 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  31 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  32 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  33 .\" SUCH DAMAGE.
  34 .\"
  35 .\" $Id$
  36 .\"
  37 .Dd May 26, 2012
  38 .Dt OPENPAM_READLINEV 3
  39 .Os
  40 .Sh NAME
  41 .Nm openpam_readlinev
  42 .Nd read a line from a file and split it into words
  43 .Sh LIBRARY
  44 .Lb libpam
  45 .Sh SYNOPSIS
  46 .In sys/types.h
  47 .In stdio.h
  48 .In security/pam_appl.h
  49 .In security/openpam.h
  50 .Ft "char **"
  51 .Fn openpam_readlinev "FILE *f" "int *lineno" "int *lenp"
  52 .Sh DESCRIPTION
  53 The
  54 .Fn openpam_readlinev
  55 function reads a line from a file, splits it
  56 into words according to the rules described in the
  57 .Xr openpam_readword 3
  58 manual page, and returns a list of those words.
  59 .Pp
  60 If
  61 .Fa lineno
  62 is not
  63 .Dv NULL ,
  64 the integer variable it points to is
  65 incremented every time a newline character is read.
  66 This includes quoted or escaped newline characters and the newline
  67 character at the end of the line.
  68 .Pp
  69 If
  70 .Fa lenp
  71 is not
  72 .Dv NULL ,
  73 the number of words on the line is stored in the
  74 variable to which it points.
  75 .Sh RETURN VALUES
  76 If successful, the
  77 .Fn openpam_readlinev
  78 function returns a pointer to a
  79 dynamically allocated array of pointers to individual dynamically
  80 allocated NUL-terminated strings, each containing a single word, in the
  81 order in which they were encountered on the line.
  82 The array is terminated by a
  83 .Dv NULL
  84 pointer.
  85 .Pp
  86 The caller is responsible for freeing both the array and the individual
  87 strings by passing each of them to
  88 .Xr free 3 .
  89 .Pp
  90 If the end of the line was reached before any words were read,
  91 .Fn openpam_readlinev
  92 returns a pointer to a dynamically allocated array
  93 containing a single
  94 .Dv NULL
  95 pointer.
  96 .Pp
  97 The
  98 .Fn openpam_readlinev
  99 function can fail and return
 100 .Dv NULL
 101 for one of
 102 four reasons:
 103 .Bl -bullet
 104 .It
 105 The end of the file was reached before any words were read;
 106 .Va errno
 107 is
 108 zero,
 109 .Xr ferror 3
 110 returns zero, and
 111 .Xr feof 3
 112 returns a non-zero value.
 113 .It
 114 The end of the file was reached while a quote or backslash escape
 115 was in effect;
 116 .Va errno
 117 is set to
 118 .Dv EINVAL ,
 119 .Xr ferror 3
 120 returns zero, and
 121 .Xr feof 3
 122 returns a non-zero value.
 123 .It
 124 An error occurred while reading from the file;
 125 .Va errno
 126 is non-zero,
 127 .Xr ferror 3
 128 returns a non-zero value and
 129 .Xr feof 3
 130 returns zero.
 131 .It
 132 A
 133 .Xr malloc 3
 134 or
 135 .Xr realloc 3
 136 call failed;
 137 .Va errno
 138 is set to
 139 .Dv ENOMEM ,
 140 .Xr ferror 3
 141 returns a non-zero value, and
 142 .Xr feof 3
 143 may or may not return
 144 a non-zero value.
 145 .El
 146 .Sh SEE ALSO
 147 .Xr openpam_readline 3 ,
 148 .Xr openpam_readword 3 ,
 149 .Xr pam 3
 150 .Sh STANDARDS
 151 The
 152 .Fn openpam_readlinev
 153 function is an OpenPAM extension.
 154 .Sh AUTHORS
 155 The
 156 .Fn openpam_readlinev
 157 function and this manual page were
 158 developed by
 159 .An Dag-Erling Sm\(/orgrav Aq des@des.no .