1.\" Generated from openpam_subst.c by gendoc.pl 2.\" $Id: openpam_subst.c 648 2013-03-05 17:54:27Z des $ 3.Dd September 7, 2013 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 LIBRARY 10.Lb libpam 11.Sh SYNOPSIS 12.In sys/types.h 13.In security/pam_appl.h 14.In security/openpam.h 15.Ft "int" 16.Fn openpam_subst "const pam_handle_t *pamh" "char *buf" "size_t *bufsize" "const char *template" 17.Sh DESCRIPTION 18The 19.Fn openpam_subst 20function expands a string, substituting PAM item 21values for all occurrences of specific substitution codes. 22The 23.Fa template 24argument points to the initial string. 25The result is stored in the buffer pointed to by the 26.Fa buf 27argument; the 28.Fa bufsize 29argument specifies the size of that buffer. 30The actual size of the resulting string, including the terminating NUL 31character, is stored in the location pointed to by the 32.Fa bufsize 33argument. 34.Pp 35If 36.Fa buf 37is NULL, or if the buffer is too small to hold the expanded 38string, 39.Fa bufsize 40is updated to reflect the amount of space required to 41hold the entire string, and 42.Fn openpam_subst 43returns 44.Dv PAM_TRY_AGAIN . 45.Pp 46If 47.Fn openpam_subst 48fails for any other reason, the 49.Fa bufsize 50argument is 51untouched, but part of the buffer may still have been overwritten. 52.Pp 53Substitution codes are introduced by a percent character and correspond 54to PAM items: 55.Bl -tag -width 18n 56.It \&%H 57Replaced by the current value of the 58.Dv PAM_RHOST 59item. 60.It \&%h 61Replaced by the current value of the 62.Dv PAM_HOST 63item. 64.It \&%s 65Replaced by the current value of the 66.Dv PAM_SERVICE 67item. 68.It \&%t 69Replaced by the current value of the 70.Dv PAM_TTY 71item. 72.It \&%U 73Replaced by the current value of the 74.Dv PAM_RUSER 75item. 76.It \&%u 77Replaced by the current value of the 78.Dv PAM_USER 79item. 80.El 81.Sh RETURN VALUES 82The 83.Fn openpam_subst 84function returns one of the following values: 85.Bl -tag -width 18n 86.It Bq Er PAM_SYSTEM_ERR 87System error. 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 des@des.no . 107