1.\" $NetBSD: openpam_subst.3,v 1.8 2017/05/06 19:50:09 christos Exp $ 2.\" 3.\" Generated from openpam_subst.c by gendoc.pl 4.\" $OpenPAM: openpam_subst.c 938 2017-04-30 21:34:42Z des $ 5.Dd April 30, 2017 6.Dt OPENPAM_SUBST 3 7.Os 8.Sh NAME 9.Nm openpam_subst 10.Nd substitute PAM item values in a string 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_SUCCESS 87Success. 88.It Bq Er PAM_BAD_ITEM 89Unrecognized or restricted item. 90.It Bq Er PAM_TRY_AGAIN 91Try again. 92.El 93.Sh SEE ALSO 94.Xr pam 3 , 95.Xr pam_get_authtok 3 , 96.Xr pam_get_item 3 , 97.Xr pam_get_user 3 , 98.Xr pam_strerror 3 99.Sh STANDARDS 100The 101.Fn openpam_subst 102function is an OpenPAM extension. 103.Sh AUTHORS 104The 105.Fn openpam_subst 106function and this manual page were 107developed by 108.An Dag-Erling Sm\(/orgrav Aq Mt des@des.no . 109