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