doc/man/openpam_readlinev.3

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