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