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