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