1*0d9d0fd8Schristos.\" $NetBSD: openpam_readlinev.3,v 1.8 2023/06/30 21:46:20 christos Exp $ 223e44a77Schristos.\" 38fa0fefeSchristos.\" Generated from openpam_readlinev.c by gendoc.pl 4*0d9d0fd8Schristos.Dd June 27, 2023 523e44a77Schristos.Dt OPENPAM_READLINEV 3 623e44a77Schristos.Os 723e44a77Schristos.Sh NAME 823e44a77Schristos.Nm openpam_readlinev 923e44a77Schristos.Nd read a line from a file and split it into words 1023e44a77Schristos.Sh SYNOPSIS 1123e44a77Schristos.In sys/types.h 1223e44a77Schristos.In stdio.h 1323e44a77Schristos.In security/pam_appl.h 1423e44a77Schristos.In security/openpam.h 1523e44a77Schristos.Ft "char **" 1623e44a77Schristos.Fn openpam_readlinev "FILE *f" "int *lineno" "int *lenp" 1723e44a77Schristos.Sh DESCRIPTION 1823e44a77SchristosThe 1923e44a77Schristos.Fn openpam_readlinev 2023e44a77Schristosfunction reads a line from a file, splits it 2123e44a77Schristosinto words according to the rules described in the 2223e44a77Schristos.Xr openpam_readword 3 2323e44a77Schristosmanual page, and returns a list of those words. 2423e44a77Schristos.Pp 2523e44a77SchristosIf 2623e44a77Schristos.Fa lineno 2723e44a77Schristosis not 2823e44a77Schristos.Dv NULL , 2923e44a77Schristosthe integer variable it points to is 3023e44a77Schristosincremented every time a newline character is read. 3123e44a77SchristosThis includes quoted or escaped newline characters and the newline 3223e44a77Schristoscharacter at the end of the line. 3323e44a77Schristos.Pp 3423e44a77SchristosIf 3523e44a77Schristos.Fa lenp 3623e44a77Schristosis not 3723e44a77Schristos.Dv NULL , 3823e44a77Schristosthe number of words on the line is stored in the 3923e44a77Schristosvariable to which it points. 4023e44a77Schristos.Sh RETURN VALUES 4123e44a77SchristosIf successful, the 4223e44a77Schristos.Fn openpam_readlinev 4323e44a77Schristosfunction returns a pointer to a 4423e44a77Schristosdynamically allocated array of pointers to individual dynamically 4523e44a77Schristosallocated NUL-terminated strings, each containing a single word, in the 4623e44a77Schristosorder in which they were encountered on the line. 4723e44a77SchristosThe array is terminated by a 4823e44a77Schristos.Dv NULL 4923e44a77Schristospointer. 5023e44a77Schristos.Pp 5123e44a77SchristosThe caller is responsible for freeing both the array and the individual 5223e44a77Schristosstrings by passing each of them to 5323e44a77Schristos.Xr free 3 . 5423e44a77Schristos.Pp 5523e44a77SchristosIf the end of the line was reached before any words were read, 5623e44a77Schristos.Fn openpam_readlinev 5723e44a77Schristosreturns a pointer to a dynamically allocated array 5823e44a77Schristoscontaining a single 5923e44a77Schristos.Dv NULL 6023e44a77Schristospointer. 6123e44a77Schristos.Pp 6223e44a77SchristosThe 6323e44a77Schristos.Fn openpam_readlinev 6423e44a77Schristosfunction can fail and return 6523e44a77Schristos.Dv NULL 6623e44a77Schristosfor one of 6723e44a77Schristosfour reasons: 6823e44a77Schristos.Bl -bullet 6923e44a77Schristos.It 7023e44a77SchristosThe end of the file was reached before any words were read; 7123e44a77Schristos.Va errno 7223e44a77Schristosis 7323e44a77Schristoszero, 7423e44a77Schristos.Xr ferror 3 7523e44a77Schristosreturns zero, and 7623e44a77Schristos.Xr feof 3 7723e44a77Schristosreturns a non-zero value. 7823e44a77Schristos.It 7923e44a77SchristosThe end of the file was reached while a quote or backslash escape 8023e44a77Schristoswas in effect; 8123e44a77Schristos.Va errno 8223e44a77Schristosis set to 8323e44a77Schristos.Dv EINVAL , 8423e44a77Schristos.Xr ferror 3 8523e44a77Schristosreturns zero, and 8623e44a77Schristos.Xr feof 3 8723e44a77Schristosreturns a non-zero value. 8823e44a77Schristos.It 8923e44a77SchristosAn error occurred while reading from the file; 9023e44a77Schristos.Va errno 9123e44a77Schristosis non-zero, 9223e44a77Schristos.Xr ferror 3 9323e44a77Schristosreturns a non-zero value and 9423e44a77Schristos.Xr feof 3 9523e44a77Schristosreturns zero. 9623e44a77Schristos.It 9723e44a77SchristosA 9823e44a77Schristos.Xr malloc 3 9923e44a77Schristosor 10023e44a77Schristos.Xr realloc 3 10123e44a77Schristoscall failed; 10223e44a77Schristos.Va errno 10323e44a77Schristosis set to 10423e44a77Schristos.Dv ENOMEM , 10523e44a77Schristos.Xr ferror 3 10623e44a77Schristosreturns a non-zero value, and 10723e44a77Schristos.Xr feof 3 10823e44a77Schristosmay or may not return 10923e44a77Schristosa non-zero value. 11023e44a77Schristos.El 11123e44a77Schristos.Sh SEE ALSO 11223e44a77Schristos.Xr openpam_readline 3 , 11323e44a77Schristos.Xr openpam_readword 3 , 11423e44a77Schristos.Xr pam 3 11523e44a77Schristos.Sh STANDARDS 11623e44a77SchristosThe 11723e44a77Schristos.Fn openpam_readlinev 11823e44a77Schristosfunction is an OpenPAM extension. 11923e44a77Schristos.Sh AUTHORS 12023e44a77SchristosThe 12123e44a77Schristos.Fn openpam_readlinev 12223e44a77Schristosfunction and this manual page were 12323e44a77Schristosdeveloped by 124a5684d07Swiz.An Dag-Erling Sm\(/orgrav Aq Mt des@des.no . 125