pam_get_item Subroutine

Edit online

Purpose

Retrieves an item or information for this PAM session.

Library

PAM Library (libpam.a)

Syntax

#include <security/pam_appl.h>

int pam_get_item (PAMHandle, ItemType, Item)
pam_handle_t *PAMHandle;
int ItemType;
void **Item;

Description

The pam_get_item subroutine returns the item requested by the ItemType. Any items returned by pam_get_item should not be modified or freed. They can be later used by PAM and will be cleaned-up by pam_end(). If a requested ItemType is not found, a NULL reference will be returned in Item.

Parameters

Item Description
PAMhandle The PAM handle representing the current user authentication session. This handle is obtained by a call to pam_start().
ItemType The type of item that is being requested. The following values are valid item types:
  • PAM_SERVICE
    • The service name requesting this PAM session.
  • PAM_USER
    • The user name of the user being authenticated.
  • PAM_AUTHTOK
    • The user's current authentication token (password).
  • PAM_OLDAUTHOK
    • The user's old authentication token (old password).
  • PAM_TTY
    • The terminal name.
  • PAM_RHOST
    • The name of the remote host.
  • PAM_RUSER
    • The name of the remote user.
  • PAM_CONV
    • The pam_conv structure for conversing with the user.
  • PAM_USER_PROMPT
    • The default prompt for the user (used by pam_get_user()).
For security, PAM_AUTHTOK and PAM_OLDAUTHTOK are only available to PAM modules.
Item The return value, holding a reference to a pointer of the requested ItemType.

Return Values

Upon successful completion, pam_get_item returns PAM_SUCCESS. Also, the address of a reference to the requested object is returned in Item. If the requested item was not found, a NULL reference is returned. If the routine fails, either PAM_SYSTEM_ERR or PAM_BUF_ERR is returned and Item is set to a NULL pointer.

Error Codes

Item Description
PAM_SYSTEM_ERR A system error occurred.
PAM_BUF_ERR A memory error occurred.
PAM_SYMBOL_ERR Symbol not found.