contrib/openpam/doc/man/openpam_subst.3

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