doc/man/pam_get_user.3

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