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 53The 54.Fn openpam_readlinev 55function reads a line from a file, splits it 56into words according to the rules described in the 57.Xr openpam_readword 3 58manual page, and returns a list of those words. 59.Pp 60If 61.Fa lineno 62is not 63.Dv NULL , 64the integer variable it points to is 65incremented every time a newline character is read. 66This includes quoted or escaped newline characters and the newline 67character at the end of the line. 68.Pp 69If 70.Fa lenp 71is not 72.Dv NULL , 73the number of words on the line is stored in the 74variable to which it points. 75.Sh RETURN VALUES 76If successful, the 77.Fn openpam_readlinev 78function returns a pointer to a 79dynamically allocated array of pointers to individual dynamically 80allocated NUL-terminated strings, each containing a single word, in the 81order in which they were encountered on the line. 82The array is terminated by a 83.Dv NULL 84pointer. 85.Pp 86The caller is responsible for freeing both the array and the individual 87strings by passing each of them to 88.Xr free 3 . 89.Pp 90If the end of the line was reached before any words were read, 91.Fn openpam_readlinev 92returns a pointer to a dynamically allocated array 93containing a single 94.Dv NULL 95pointer. 96.Pp 97The 98.Fn openpam_readlinev 99function can fail and return 100.Dv NULL 101for one of 102four reasons: 103.Bl -bullet 104.It 105The end of the file was reached before any words were read; 106.Va errno 107is 108zero, 109.Xr ferror 3 110returns zero, and 111.Xr feof 3 112returns a non-zero value. 113.It 114The end of the file was reached while a quote or backslash escape 115was in effect; 116.Va errno 117is set to 118.Dv EINVAL , 119.Xr ferror 3 120returns zero, and 121.Xr feof 3 122returns a non-zero value. 123.It 124An error occurred while reading from the file; 125.Va errno 126is non-zero, 127.Xr ferror 3 128returns a non-zero value and 129.Xr feof 3 130returns zero. 131.It 132A 133.Xr malloc 3 134or 135.Xr realloc 3 136call failed; 137.Va errno 138is set to 139.Dv ENOMEM , 140.Xr ferror 3 141returns a non-zero value, and 142.Xr feof 3 143may or may not return 144a 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 151The 152.Fn openpam_readlinev 153function is an OpenPAM extension. 154.Sh AUTHORS 155The 156.Fn openpam_readlinev 157function and this manual page were 158developed by 159.An Dag-Erling Sm\(/orgrav Aq des@des.no . 160