f2ba1a6b775a1ca587028744b1d8f497dcfe0620
[dragonfly.git] / contrib / openpam / doc / man / openpam_readlinev.3
1 .\"-
2 .\" Copyright (c) 2001-2003 Networks Associates Technology, Inc.
3 .\" Copyright (c) 2004-2011 Dag-Erling Smørgrav
4 .\" All rights reserved.
5 .\"
6 .\" This software was developed for the FreeBSD Project by ThinkSec AS and
7 .\" Network Associates Laboratories, the Security Research Division of
8 .\" Network Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035
9 .\" ("CBOSS"), as part of the DARPA CHATS research program.
10 .\"
11 .\" Redistribution and use in source and binary forms, with or without
12 .\" modification, are permitted provided that the following conditions
13 .\" are met:
14 .\" 1. Redistributions of source code must retain the above copyright
15 .\"    notice, this list of conditions and the following disclaimer.
16 .\" 2. Redistributions in binary form must reproduce the above copyright
17 .\"    notice, this list of conditions and the following disclaimer in the
18 .\"    documentation and/or other materials provided with the distribution.
19 .\" 3. The name of the author may not be used to endorse or promote
20 .\"    products derived from this software without specific prior written
21 .\"    permission.
22 .\"
23 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
24 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
27 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33 .\" SUCH DAMAGE.
34 .\"
35 .\" $Id$
36 .\"
37 .Dd May 26, 2012
38 .Dt OPENPAM_READLINEV 3
39 .Os
40 .Sh NAME
41 .Nm openpam_readlinev
42 .Nd read a line from a file and split it into words
43 .Sh LIBRARY
44 .Lb libpam
45 .Sh SYNOPSIS
46 .In sys/types.h
47 .In stdio.h
48 .In security/pam_appl.h
49 .In security/openpam.h
50 .Ft "char **"
51 .Fn openpam_readlinev "FILE *f" "int *lineno" "int *lenp"
52 .Sh DESCRIPTION
53 The
54 .Fn openpam_readlinev
55 function reads a line from a file, splits it
56 into words according to the rules described in the
57 .Xr openpam_readword 3
58 manual page, and returns a list of those words.
59 .Pp
60 If
61 .Fa lineno
62 is not
63 .Dv NULL ,
64 the integer variable it points to is
65 incremented every time a newline character is read.
66 This includes quoted or escaped newline characters and the newline
67 character at the end of the line.
68 .Pp
69 If
70 .Fa lenp
71 is not
72 .Dv NULL ,
73 the number of words on the line is stored in the
74 variable to which it points.
75 .Sh RETURN VALUES
76 If successful, the
77 .Fn openpam_readlinev
78 function returns a pointer to a
79 dynamically allocated array of pointers to individual dynamically
80 allocated NUL-terminated strings, each containing a single word, in the
81 order in which they were encountered on the line.
82 The array is terminated by a
83 .Dv NULL
84 pointer.
85 .Pp
86 The caller is responsible for freeing both the array and the individual
87 strings by passing each of them to
88 .Xr free 3 .
89 .Pp
90 If the end of the line was reached before any words were read,
91 .Fn openpam_readlinev
92 returns a pointer to a dynamically allocated array
93 containing a single
94 .Dv NULL
95 pointer.
96 .Pp
97 The
98 .Fn openpam_readlinev
99 function can fail and return
100 .Dv NULL
101 for one of
102 four reasons:
103 .Bl -bullet
104 .It
105 The end of the file was reached before any words were read;
106 .Va errno
107 is
108 zero,
109 .Xr ferror 3
110 returns zero, and
111 .Xr feof 3
112 returns a non-zero value.
113 .It
114 The end of the file was reached while a quote or backslash escape
115 was in effect;
116 .Va errno
117 is set to
118 .Dv EINVAL ,
119 .Xr ferror 3
120 returns zero, and
121 .Xr feof 3
122 returns a non-zero value.
123 .It
124 An error occurred while reading from the file;
125 .Va errno
126 is non-zero,
127 .Xr ferror 3
128 returns a non-zero value and
129 .Xr feof 3
130 returns zero.
131 .It
132 A
133 .Xr malloc 3
134 or
135 .Xr realloc 3
136 call failed;
137 .Va errno
138 is set to
139 .Dv ENOMEM ,
140 .Xr ferror 3
141 returns a non-zero value, and
142 .Xr feof 3
143 may or may not return
144 a non-zero value.
145 .El
146 .Sh SEE ALSO
147 .Xr openpam_readline 3 ,
148 .Xr openpam_readword 3 ,
149 .Xr pam 3
150 .Sh STANDARDS
151 The
152 .Fn openpam_readlinev
153 function is an OpenPAM extension.
154 .Sh AUTHORS
155 The
156 .Fn openpam_readlinev
157 function and this manual page were
158 developed by
159 .An Dag-Erling Sm\(/orgrav Aq des@des.no .