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