1.\" Generated from openpam_readlinev.c by gendoc.pl 2.Dd June 27, 2023 3.Dt OPENPAM_READLINEV 3 4.Os 5.Sh NAME 6.Nm openpam_readlinev 7.Nd read a line from a file and split it into words 8.Sh SYNOPSIS 9.In sys/types.h 10.In stdio.h 11.In security/pam_appl.h 12.In security/openpam.h 13.Ft "char **" 14.Fn openpam_readlinev "FILE *f" "int *lineno" "int *lenp" 15.Sh DESCRIPTION 16The 17.Fn openpam_readlinev 18function reads a line from a file, splits it 19into words according to the rules described in the 20.Xr openpam_readword 3 21manual page, and returns a list of those words. 22.Pp 23If 24.Fa lineno 25is not 26.Dv NULL , 27the integer variable it points to is 28incremented every time a newline character is read. 29This includes quoted or escaped newline characters and the newline 30character at the end of the line. 31.Pp 32If 33.Fa lenp 34is not 35.Dv NULL , 36the number of words on the line is stored in the 37variable to which it points. 38.Sh RETURN VALUES 39If successful, the 40.Fn openpam_readlinev 41function returns a pointer to a 42dynamically allocated array of pointers to individual dynamically 43allocated NUL-terminated strings, each containing a single word, in the 44order in which they were encountered on the line. 45The array is terminated by a 46.Dv NULL 47pointer. 48.Pp 49The caller is responsible for freeing both the array and the individual 50strings by passing each of them to 51.Xr free 3 . 52.Pp 53If the end of the line was reached before any words were read, 54.Fn openpam_readlinev 55returns a pointer to a dynamically allocated array 56containing a single 57.Dv NULL 58pointer. 59.Pp 60The 61.Fn openpam_readlinev 62function can fail and return 63.Dv NULL 64for one of 65four reasons: 66.Bl -bullet 67.It 68The end of the file was reached before any words were read; 69.Va errno 70is 71zero, 72.Xr ferror 3 73returns zero, and 74.Xr feof 3 75returns a non-zero value. 76.It 77The end of the file was reached while a quote or backslash escape 78was in effect; 79.Va errno 80is set to 81.Dv EINVAL , 82.Xr ferror 3 83returns zero, and 84.Xr feof 3 85returns a non-zero value. 86.It 87An error occurred while reading from the file; 88.Va errno 89is non-zero, 90.Xr ferror 3 91returns a non-zero value and 92.Xr feof 3 93returns zero. 94.It 95A 96.Xr malloc 3 97or 98.Xr realloc 3 99call failed; 100.Va errno 101is set to 102.Dv ENOMEM , 103.Xr ferror 3 104returns a non-zero value, and 105.Xr feof 3 106may or may not return 107a non-zero value. 108.El 109.Sh SEE ALSO 110.Xr openpam_readline 3 , 111.Xr openpam_readword 3 , 112.Xr pam 3 113.Sh STANDARDS 114The 115.Fn openpam_readlinev 116function is an OpenPAM extension. 117.Sh AUTHORS 118The 119.Fn openpam_readlinev 120function and this manual page were 121developed by 122.An Dag-Erling Sm\(/orgrav Aq Mt des@des.no . 123