---
name: "openpam_subst"
section: "3"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/openpam_subst"
---

# openpam\_subst(3)

substitute PAM item values in a string

## NAME

**openpam\_subst** – substitute PAM item values in a string

## SYNOPSIS

**#include \<sys/types.h\>**

**#include \<security/pam\_appl.h\>**

**#include \<security/openpam.h\>**

*int*\

**openpam\_subst**(*const pam\_handle\_t \*pamh*, *char \*buf*, *size\_t \*bufsize*, *const char \*template*);

## DESCRIPTION

The **openpam\_subst**() function expands a string, substituting PAM item values for all occurrences of specific substitution codes. The *template* argument points to the initial string. The result is stored in the buffer pointed to by the *buf* argument; the *bufsize* argument specifies the size of that buffer. The actual size of the resulting string, including the terminating NUL character, is stored in the location pointed to by the *bufsize* argument.

If *buf* is NULL, or if the buffer is too small to hold the expanded string, *bufsize* is updated to reflect the amount of space required to hold the entire string, and **openpam\_subst**() returns PAM\_TRY\_AGAIN.

If **openpam\_subst**() fails for any other reason, the *bufsize* argument is untouched, but part of the buffer may still have been overwritten.

Substitution codes are introduced by a percent character and correspond to PAM items:

- %H

  Replaced by the current value of the PAM\_RHOST item.

- %h

  Replaced by the current value of the PAM\_HOST item.

- %s

  Replaced by the current value of the PAM\_SERVICE item.

- %t

  Replaced by the current value of the PAM\_TTY item.

- %U

  Replaced by the current value of the PAM\_RUSER item.

- %u

  Replaced by the current value of the PAM\_USER item.

## RETURN VALUES

The **openpam\_subst**() function returns one of the following values:

- \[PAM\_SUCCESS\]

  Success.

- \[PAM\_BAD\_ITEM\]

  Unrecognized or restricted item.

- \[PAM\_TRY\_AGAIN\]

  Try again.

## SEE ALSO

[pam(3)](/pam/3.md), [pam\_get\_authtok(3)](/pam_get_authtok/3.md), [pam\_get\_item(3)](/pam_get_item/3.md), [pam\_get\_user(3)](/pam_get_user/3.md), [pam\_strerror(3)](/pam_strerror/3.md)

## STANDARDS

The **openpam\_subst**() function is an OpenPAM extension.

## AUTHORS

The **openpam\_subst**() function and this manual page were developed by Dag-Erling Smørgrav ⟨*des@des.dev*⟩.