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