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