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