$Id: openpam_readlinev.c 648 2013-03-05 17:54:27Z des $
.Dd September 12, 2014 .Dt OPENPAM_READLINEV 3 .Os .Sh NAME .Nm openpam_readlinev .Nd read a line from a file and split it into words .Sh LIBRARY .Lb libpam .Sh SYNOPSIS n sys/types.h n stdio.h n security/pam_appl.h n security/openpam.h .Ft "char **" .Fn openpam_readlinev "FILE *f" "int *lineno" "int *lenp" .Sh DESCRIPTION The .Fn openpam_readlinev function reads a line from a file, splits it into words according to the rules described in the .Xr openpam_readword 3 manual page, and returns a list of those words.
p If .Fa lineno is not .Dv NULL , the integer variable it points to is incremented every time a newline character is read. This includes quoted or escaped newline characters and the newline character at the end of the line.
p If .Fa lenp is not .Dv NULL , the number of words on the line is stored in the variable to which it points. .Sh RETURN VALUES If successful, the .Fn openpam_readlinev function returns a pointer to a dynamically allocated array of pointers to individual dynamically allocated NUL-terminated strings, each containing a single word, in the order in which they were encountered on the line. The array is terminated by a .Dv NULL pointer.
p The caller is responsible for freeing both the array and the individual strings by passing each of them to .Xr free 3 .
p If the end of the line was reached before any words were read, .Fn openpam_readlinev returns a pointer to a dynamically allocated array containing a single .Dv NULL pointer.
p The .Fn openpam_readlinev function can fail and return .Dv NULL for one of four reasons: l -bullet t The end of the file was reached before any words were read; .Va errno is zero, .Xr ferror 3 returns zero, and .Xr feof 3 returns a non-zero value. t The end of the file was reached while a quote or backslash escape was in effect; .Va errno is set to .Dv EINVAL , .Xr ferror 3 returns zero, and .Xr feof 3 returns a non-zero value. t An error occurred while reading from the file; .Va errno is non-zero, .Xr ferror 3 returns a non-zero value and .Xr feof 3 returns zero. t A .Xr malloc 3 or .Xr realloc 3 call failed; .Va errno is set to .Dv ENOMEM , .Xr ferror 3 returns a non-zero value, and .Xr feof 3 may or may not return a non-zero value. .El .Sh SEE ALSO .Xr openpam_readline 3 , .Xr openpam_readword 3 , .Xr pam 3 .Sh STANDARDS The .Fn openpam_readlinev function is an OpenPAM extension. .Sh AUTHORS The .Fn openpam_readlinev function and this manual page were developed by .An Dag-Erling Sm\(/orgrav Aq des@des.no .