1.\" Generated from openpam_readline.c by gendoc.pl
2.\" $OpenPAM: openpam_readline.c 938 2017-04-30 21:34:42Z des $
3.Dd February 24, 2019
4.Dt OPENPAM_READLINE 3
5.Os
6.Sh NAME
7.Nm openpam_readline
8.Nd read a line from a file
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_readline "FILE *f" "int *lineno" "size_t *lenp"
16.Sh DESCRIPTION
17.Bf Sy
18This function is deprecated and may be removed in a future release without further warning.
19The
20.Fn openpam_readlinev
21function may be used to achieve similar results.
22.Ef
23.Pp
24The
25.Fn openpam_readline
26function reads a line from a file, and returns it
27in a NUL-terminated buffer allocated with
28.Xr malloc 3 .
29.Pp
30The
31.Fn openpam_readline
32function performs a certain amount of processing
33on the data it reads:
34.Bl -bullet
35.It
36Comments (introduced by a hash sign) are stripped.
37.It
38Blank lines are ignored.
39.It
40If a line ends in a backslash, the backslash is stripped and the
41next line is appended.
42.El
43.Pp
44If
45.Fa lineno
46is not
47.Dv NULL ,
48the integer variable it points to is
49incremented every time a newline character is read.
50.Pp
51If
52.Fa lenp
53is not
54.Dv NULL ,
55the length of the line (not including the
56terminating NUL character) is stored in the variable it points to.
57.Pp
58The caller is responsible for releasing the returned buffer by passing
59it to
60.Xr free 3 .
61.Pp
62.Sh RETURN VALUES
63The
64.Fn openpam_readline
65function returns
66.Dv NULL
67on failure.
68.Sh SEE ALSO
69.Xr openpam_readlinev 3 ,
70.Xr openpam_readword 3 ,
71.Xr pam 3
72.Sh STANDARDS
73The
74.Fn openpam_readline
75function is an OpenPAM extension.
76.Sh AUTHORS
77The
78.Fn openpam_readline
79function and this manual page were
80developed for the
81.Fx
82Project by ThinkSec AS and Network Associates Laboratories, the
83Security Research Division of Network Associates, Inc.\& under
84DARPA/SPAWAR contract N66001-01-C-8035
85.Pq Dq CBOSS ,
86as part of the DARPA CHATS research program.
87.Pp
88The OpenPAM library is maintained by
89.An Dag-Erling Sm\(/orgrav Aq Mt des@des.no .
90