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