1.\"- 2.\" Copyright (c) 2001-2003 Networks Associates Technology, Inc. 3.\" Copyright (c) 2004-2011 Dag-Erling Smørgrav 4.\" All rights reserved. 5.\" 6.\" This software was developed for the FreeBSD Project by ThinkSec AS and 7.\" Network Associates Laboratories, the Security Research Division of 8.\" Network Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 9.\" ("CBOSS"), as part of the DARPA CHATS research program. 10.\" 11.\" Redistribution and use in source and binary forms, with or without 12.\" modification, are permitted provided that the following conditions 13.\" are met: 14.\" 1. Redistributions of source code must retain the above copyright 15.\" notice, this list of conditions and the following disclaimer. 16.\" 2. Redistributions in binary form must reproduce the above copyright 17.\" notice, this list of conditions and the following disclaimer in the 18.\" documentation and/or other materials provided with the distribution. 19.\" 3. The name of the author may not be used to endorse or promote 20.\" products derived from this software without specific prior written 21.\" permission. 22.\" 23.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 24.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 25.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 26.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 27.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 28.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 29.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 30.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 33.\" SUCH DAMAGE. 34.\" 35.\" $Id$ 36.\" 37.Dd May 26, 2012 38.Dt OPENPAM_SUBST 3 39.Os 40.Sh NAME 41.Nm openpam_subst 42.Nd substitute PAM item values in a string 43.Sh LIBRARY 44.Lb libpam 45.Sh SYNOPSIS 46.In sys/types.h 47.In security/pam_appl.h 48.In security/openpam.h 49.Ft "int" 50.Fn openpam_subst "const pam_handle_t *pamh" "char *buf" "size_t *bufsize" "const char *template" 51.Sh DESCRIPTION 52The 53.Fn openpam_subst 54function expands a string, substituting PAM item 55values for all occurrences of specific substitution codes. 56The 57.Fa template 58argument points to the initial string. 59The result is stored in the buffer pointed to by the 60.Fa buf 61argument; the 62.Fa bufsize 63argument specifies the size of that buffer. 64The actual size of the resulting string, including the terminating NUL 65character, is stored in the location pointed to by the 66.Fa bufsize 67argument. 68.Pp 69If 70.Fa buf 71is NULL, or if the buffer is too small to hold the expanded 72string, 73.Fa bufsize 74is updated to reflect the amount of space required to 75hold the entire string, and 76.Fn openpam_subst 77returns 78.Dv PAM_TRY_AGAIN . 79.Pp 80If 81.Fn openpam_subst 82fails for any other reason, the 83.Fa bufsize 84argument is 85untouched, but part of the buffer may still have been overwritten. 86.Pp 87Substitution codes are introduced by a percent character and correspond 88to PAM items: 89.Bl -tag -width 18n 90.It \&%H 91Replaced by the current value of the 92.Dv PAM_RHOST 93item. 94.It \&%h 95Replaced by the current value of the 96.Dv PAM_HOST 97item. 98.It \&%s 99Replaced by the current value of the 100.Dv PAM_SERVICE 101item. 102.It \&%t 103Replaced by the current value of the 104.Dv PAM_TTY 105item. 106.It \&%U 107Replaced by the current value of the 108.Dv PAM_RUSER 109item. 110.It \&%u 111Replaced by the current value of the 112.Dv PAM_USER 113item. 114.El 115.Sh RETURN VALUES 116The 117.Fn openpam_subst 118function returns one of the following values: 119.Bl -tag -width 18n 120.It Bq Er PAM_SYSTEM_ERR 121System error. 122.It Bq Er PAM_TRY_AGAIN 123Try again. 124.El 125.Sh SEE ALSO 126.Xr pam 3 , 127.Xr pam_get_authtok 3 , 128.Xr pam_get_item 3 , 129.Xr pam_get_user 3 , 130.Xr pam_strerror 3 131.Sh STANDARDS 132The 133.Fn openpam_subst 134function is an OpenPAM extension. 135.Sh AUTHORS 136The 137.Fn openpam_subst 138function and this manual page were 139developed by 140.An Dag-Erling Sm\(/orgrav Aq des@des.no . 141