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