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