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