NAME

pam_get_user - retrieve user name

SYNOPSIS

#include <security/pam_appl.h>

int pam_get_user (
    pam_handle_t    *pamh,
    char           **user,
    const char      *prompt
);

DESCRIPTION

The pam_get_user() function is used by PAM service modules to retrieve the current user name from the pamh handle. If the user name has not been set via pam_start() or pam_set_item(), then the PAM conversation function will be used to prompt the user for the user name with the string prompt. If prompt is NULL, then pam_get_item() is called and the value of PAM_USER_PROMPT is used for prompting. If the value of PAM_USER_PROMPT is NULL, the following default prompt is used:

 

Please enter user name:

After the user name is gathered by the conversation function, pam_set_item() is used to set the value of PAM_USER.

By convention, applications that need to prompt for a user name should call pam_set_item() and set the value of PAM_USER_PROMPT before calling pam_authenticate(). The service module's pam_sm_authenticate() function will then call pam_get_user() to prompt for the user name. Note that certain PAM service modules (such as a smart card module) may override the value of PAM_USER_PROMPT and pass in their own prompt.

Applications that call pam_authenticate() multiple times should set the value of PAM_USER to NULL with pam_set_item() before calling pam_authenticate() if they want the user to be prompted for a new user name each time.

The value of user retrieved by pam_get_user() should not be modified or freed. The item will be released by pam_end().

The arguments for pam_get_user() are:

pamh (in)

The PAM authentication handle, obtained from a previous call to pam_start().

user (out)

The user name returned from pamh.

prompt (in)

The prompt to be used if the conversation function needs to prompt the user for a user name.

RETURN VALUE

The following PAM status codes shall be returned:

[PAM_SUCCESS]

Successful completion.

[PAM_CONV_ERR]

Conversation failure.

[PAM_SYSTEM_ERR]

System error.

[PAM_BUF_ERR]

Memory buffer error.

[PAM_CONV_ERR]

Conversation error.

[??] Some characters or strings that appear in the printed document are not easily representable using HTML.