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