1.\" $NetBSD: openpam_subst.3,v 1.10 2023/06/30 21:46:20 christos Exp $ 2.\" 3.\" Generated from openpam_subst.c by gendoc.pl 4.Dd June 27, 2023 5.Dt OPENPAM_SUBST 3 6.Os 7.Sh NAME 8.Nm openpam_subst 9.Nd substitute PAM item values in a string 10.Sh SYNOPSIS 11.In sys/types.h 12.In security/pam_appl.h 13.In security/openpam.h 14.Ft "int" 15.Fn openpam_subst "const pam_handle_t *pamh" "char *buf" "size_t *bufsize" "const char *template" 16.Sh DESCRIPTION 17The 18.Fn openpam_subst 19function expands a string, substituting PAM item 20values for all occurrences of specific substitution codes. 21The 22.Fa template 23argument points to the initial string. 24The result is stored in the buffer pointed to by the 25.Fa buf 26argument; the 27.Fa bufsize 28argument specifies the size of that buffer. 29The actual size of the resulting string, including the terminating NUL 30character, is stored in the location pointed to by the 31.Fa bufsize 32argument. 33.Pp 34If 35.Fa buf 36is NULL, or if the buffer is too small to hold the expanded 37string, 38.Fa bufsize 39is updated to reflect the amount of space required to 40hold the entire string, and 41.Fn openpam_subst 42returns 43.Dv PAM_TRY_AGAIN . 44.Pp 45If 46.Fn openpam_subst 47fails for any other reason, the 48.Fa bufsize 49argument is 50untouched, but part of the buffer may still have been overwritten. 51.Pp 52Substitution codes are introduced by a percent character and correspond 53to PAM items: 54.Bl -tag -width 18n 55.It \&%H 56Replaced by the current value of the 57.Dv PAM_RHOST 58item. 59.It \&%h 60Replaced by the current value of the 61.Dv PAM_HOST 62item. 63.It \&%s 64Replaced by the current value of the 65.Dv PAM_SERVICE 66item. 67.It \&%t 68Replaced by the current value of the 69.Dv PAM_TTY 70item. 71.It \&%U 72Replaced by the current value of the 73.Dv PAM_RUSER 74item. 75.It \&%u 76Replaced by the current value of the 77.Dv PAM_USER 78item. 79.El 80.Sh RETURN VALUES 81The 82.Fn openpam_subst 83function returns one of the following values: 84.Bl -tag -width 18n 85.It Bq Er PAM_SUCCESS 86Success. 87.It Bq Er PAM_BAD_ITEM 88Unrecognized or restricted item. 89.It Bq Er PAM_TRY_AGAIN 90Try again. 91.El 92.Sh SEE ALSO 93.Xr pam 3 , 94.Xr pam_get_authtok 3 , 95.Xr pam_get_item 3 , 96.Xr pam_get_user 3 , 97.Xr pam_strerror 3 98.Sh STANDARDS 99The 100.Fn openpam_subst 101function is an OpenPAM extension. 102.Sh AUTHORS 103The 104.Fn openpam_subst 105function and this manual page were 106developed by 107.An Dag-Erling Sm\(/orgrav Aq Mt des@des.no . 108