1.\" Generated from openpam_subst.c by gendoc.pl
2.Dd June 27, 2023
3.Dt OPENPAM_SUBST 3
4.Os
5.Sh NAME
6.Nm openpam_subst
7.Nd substitute PAM item values in a string
8.Sh SYNOPSIS
9.In sys/types.h
10.In security/pam_appl.h
11.In security/openpam.h
12.Ft "int"
13.Fn openpam_subst "const pam_handle_t *pamh" "char *buf" "size_t *bufsize" "const char *template"
14.Sh DESCRIPTION
15The
16.Fn openpam_subst
17function expands a string, substituting PAM item
18values for all occurrences of specific substitution codes.
19The
20.Fa template
21argument points to the initial string.
22The result is stored in the buffer pointed to by the
23.Fa buf
24argument; the
25.Fa bufsize
26argument specifies the size of that buffer.
27The actual size of the resulting string, including the terminating NUL
28character, is stored in the location pointed to by the
29.Fa bufsize
30argument.
31.Pp
32If
33.Fa buf
34is NULL, or if the buffer is too small to hold the expanded
35string,
36.Fa bufsize
37is updated to reflect the amount of space required to
38hold the entire string, and
39.Fn openpam_subst
40returns
41.Dv PAM_TRY_AGAIN .
42.Pp
43If
44.Fn openpam_subst
45fails for any other reason, the
46.Fa bufsize
47argument is
48untouched, but part of the buffer may still have been overwritten.
49.Pp
50Substitution codes are introduced by a percent character and correspond
51to PAM items:
52.Bl -tag -width 18n
53.It \&%H
54Replaced by the current value of the
55.Dv PAM_RHOST
56item.
57.It \&%h
58Replaced by the current value of the
59.Dv PAM_HOST
60item.
61.It \&%s
62Replaced by the current value of the
63.Dv PAM_SERVICE
64item.
65.It \&%t
66Replaced by the current value of the
67.Dv PAM_TTY
68item.
69.It \&%U
70Replaced by the current value of the
71.Dv PAM_RUSER
72item.
73.It \&%u
74Replaced by the current value of the
75.Dv PAM_USER
76item.
77.El
78.Sh RETURN VALUES
79The
80.Fn openpam_subst
81function returns one of the following values:
82.Bl -tag -width 18n
83.It Bq Er PAM_SUCCESS
84Success.
85.It Bq Er PAM_BAD_ITEM
86Unrecognized or restricted item.
87.It Bq Er PAM_TRY_AGAIN
88Try again.
89.El
90.Sh SEE ALSO
91.Xr pam 3 ,
92.Xr pam_get_authtok 3 ,
93.Xr pam_get_item 3 ,
94.Xr pam_get_user 3 ,
95.Xr pam_strerror 3
96.Sh STANDARDS
97The
98.Fn openpam_subst
99function is an OpenPAM extension.
100.Sh AUTHORS
101The
102.Fn openpam_subst
103function and this manual page were
104developed by
105.An Dag-Erling Sm\(/orgrav Aq Mt des@des.no .
106