pam_get_user Subroutine

Purpose

Gets the user's name from the PAM handle or through prompting for input.

Library

PAM Library (libpam.a)

Syntax

#include <security/pam_appl.h>

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

Description

The pam_get_user subroutine returns the user name currently stored in the PAM handle, pamh. If the user name has not already been set through pam_start() or pam_set_item(), the subroutine displays the string specified by prompt, to prompt for the user name through the conversation function. If prompt is NULL, the value of PAM_USER_PROMPT set through a call to pam_set_item() is used. If both prompt and PAM_USER_PROMPT are NULL, PAM defaults to use the following string:

Please enter user name:

After the user name has been retrieved, it is set in the PAM handle and is also returned to the caller in the user argument. The caller should not change or free user, as cleanup will be handled by pam_end().

Parameters

Item Description
pamh The PAM handle representing the current user authentication session. This handle is obtained by a call to pam_start().
user The user name retrieved from the PAM handle or provided by the user.
prompt The prompt to be displayed if a user name is required and has not been already set.

Return Values

Upon successful completion, pam_get_user returns PAM_SUCCESS. Also, a reference to the user name is returned in user. If the routine fails, either PAM_SYSTEM_ERR, PAM_BUF_ERR, or PAM_CONV_ERR is returned, depending on what the actual error was, and a NULL reference in user is returned.

Error Codes

Item Description
PAM_SYSTEM_ERR A system error occurred.
PAM_BUF_ERR A memory error occurred.
PAM_CONV_ERR A conversation error or failure.