contrib/openpam/doc/man/pam_get_user.3

   1 .\" Generated from pam_get_user.c by gendoc.pl
   2 .\" $Id: pam_get_user.c 670 2013-03-17 19:26:07Z des $
   3 .Dd September 7, 2013
   4 .Dt PAM_GET_USER 3
   5 .Os
   6 .Sh NAME
   7 .Nm pam_get_user
   8 .Nd retrieve user name
   9 .Sh LIBRARY
  10 .Lb libpam
  11 .Sh SYNOPSIS
  12 .In sys/types.h
  13 .In security/pam_appl.h
  14 .Ft "int"
  15 .Fn pam_get_user "pam_handle_t *pamh" "const char **user" "const char *prompt"
  16 .Sh DESCRIPTION
  17 The
  18 .Fn pam_get_user
  19 function returns the name of the target user, as
  20 specified to
  21 .Xr pam_start 3 .
  22 If no user was specified, nor set using
  23 .Xr pam_set_item 3 ,
  24 .Fn pam_get_user
  25 will prompt for a user name.
  26 Either way, a pointer to the user name is stored in the location
  27 pointed to by the
  28 .Fa user
  29 argument, and the corresponding PAM item is
  30 updated.
  31 .Pp
  32 The
  33 .Fa prompt
  34 argument specifies a prompt to use if no user name is
  35 cached.
  36 If it is
  37 .Dv NULL ,
  38 the
  39 .Dv PAM_USER_PROMPT
  40 item will be used.
  41 If that item is also
  42 .Dv NULL ,
  43 a hardcoded default prompt will be used.
  44 Additionally, when
  45 .Fn pam_get_user
  46 is called from a service module, the
  47 prompt may be affected by module options as described below.
  48 The prompt is then expanded using
  49 .Xr openpam_subst 3
  50 before it is passed to
  51 the conversation function.
  52 .Sh MODULE OPTIONS
  53 When called by a service module,
  54 .Fn pam_get_user
  55 will recognize the
  56 following module options:
  57 .Bl -tag -width 18n
  58 .It Dv user_prompt
  59 Prompt to use when asking for the user name.
  60 This option overrides both the
  61 .Fa prompt
  62 argument and the
  63 .Dv PAM_USER_PROMPT
  64 item.
  65 .El
  66 .Sh RETURN VALUES
  67 The
  68 .Fn pam_get_user
  69 function returns one of the following values:
  70 .Bl -tag -width 18n
  71 .It Bq Er PAM_BUF_ERR
  72 Memory buffer error.
  73 .It Bq Er PAM_CONV_ERR
  74 Conversation failure.
  75 .It Bq Er PAM_SYSTEM_ERR
  76 System error.
  77 .El
  78 .Sh SEE ALSO
  79 .Xr openpam_get_option 3 ,
  80 .Xr openpam_subst 3 ,
  81 .Xr pam 3 ,
  82 .Xr pam_conv 3 ,
  83 .Xr pam_get_authtok 3 ,
  84 .Xr pam_get_item 3 ,
  85 .Xr pam_set_item 3 ,
  86 .Xr pam_start 3 ,
  87 .Xr pam_strerror 3
  88 .Sh STANDARDS
  89 .Rs
  90 .%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules"
  91 .%D "June 1997"
  92 .Re
  93 .Sh AUTHORS
  94 The
  95 .Fn pam_get_user
  96 function and this manual page were
  97 developed for the
  98 .Fx
  99 Project by ThinkSec AS and Network Associates Laboratories, the
 100 Security Research Division of Network Associates, Inc.\& under
 101 DARPA/SPAWAR contract N66001-01-C-8035
 102 .Pq Dq CBOSS ,
 103 as part of the DARPA CHATS research program.
 104 .Pp
 105 The OpenPAM library is maintained by
 106 .An Dag-Erling Sm\(/orgrav Aq des@des.no .