contrib/openpam/doc/man/openpam_readlinev.3

   1 .\" Generated from openpam_readlinev.c by gendoc.pl
   2 .\" $Id: openpam_readlinev.c 648 2013-03-05 17:54:27Z des $
   3 .Dd September 12, 2014
   4 .Dt OPENPAM_READLINEV 3
   5 .Os
   6 .Sh NAME
   7 .Nm openpam_readlinev
   8 .Nd read a line from a file and split it into words
   9 .Sh LIBRARY
  10 .Lb libpam
  11 .Sh SYNOPSIS
  12 .In sys/types.h
  13 .In stdio.h
  14 .In security/pam_appl.h
  15 .In security/openpam.h
  16 .Ft "char **"
  17 .Fn openpam_readlinev "FILE *f" "int *lineno" "int *lenp"
  18 .Sh DESCRIPTION
  19 The
  20 .Fn openpam_readlinev
  21 function reads a line from a file, splits it
  22 into words according to the rules described in the
  23 .Xr openpam_readword 3
  24 manual page, and returns a list of those words.
  25 .Pp
  26 If
  27 .Fa lineno
  28 is not
  29 .Dv NULL ,
  30 the integer variable it points to is
  31 incremented every time a newline character is read.
  32 This includes quoted or escaped newline characters and the newline
  33 character at the end of the line.
  34 .Pp
  35 If
  36 .Fa lenp
  37 is not
  38 .Dv NULL ,
  39 the number of words on the line is stored in the
  40 variable to which it points.
  41 .Sh RETURN VALUES
  42 If successful, the
  43 .Fn openpam_readlinev
  44 function returns a pointer to a
  45 dynamically allocated array of pointers to individual dynamically
  46 allocated NUL-terminated strings, each containing a single word, in the
  47 order in which they were encountered on the line.
  48 The array is terminated by a
  49 .Dv NULL
  50 pointer.
  51 .Pp
  52 The caller is responsible for freeing both the array and the individual
  53 strings by passing each of them to
  54 .Xr free 3 .
  55 .Pp
  56 If the end of the line was reached before any words were read,
  57 .Fn openpam_readlinev
  58 returns a pointer to a dynamically allocated array
  59 containing a single
  60 .Dv NULL
  61 pointer.
  62 .Pp
  63 The
  64 .Fn openpam_readlinev
  65 function can fail and return
  66 .Dv NULL
  67 for one of
  68 four reasons:
  69 .Bl -bullet
  70 .It
  71 The end of the file was reached before any words were read;
  72 .Va errno
  73 is
  74 zero,
  75 .Xr ferror 3
  76 returns zero, and
  77 .Xr feof 3
  78 returns a non-zero value.
  79 .It
  80 The end of the file was reached while a quote or backslash escape
  81 was in effect;
  82 .Va errno
  83 is set to
  84 .Dv EINVAL ,
  85 .Xr ferror 3
  86 returns zero, and
  87 .Xr feof 3
  88 returns a non-zero value.
  89 .It
  90 An error occurred while reading from the file;
  91 .Va errno
  92 is non-zero,
  93 .Xr ferror 3
  94 returns a non-zero value and
  95 .Xr feof 3
  96 returns zero.
  97 .It
  98 A
  99 .Xr malloc 3
 100 or
 101 .Xr realloc 3
 102 call failed;
 103 .Va errno
 104 is set to
 105 .Dv ENOMEM ,
 106 .Xr ferror 3
 107 returns a non-zero value, and
 108 .Xr feof 3
 109 may or may not return
 110 a non-zero value.
 111 .El
 112 .Sh SEE ALSO
 113 .Xr openpam_readline 3 ,
 114 .Xr openpam_readword 3 ,
 115 .Xr pam 3
 116 .Sh STANDARDS
 117 The
 118 .Fn openpam_readlinev
 119 function is an OpenPAM extension.
 120 .Sh AUTHORS
 121 The
 122 .Fn openpam_readlinev
 123 function and this manual page were
 124 developed by
 125 .An Dag-Erling Sm\(/orgrav Aq des@des.no .