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