PAM Library Functions                          pam_set_item(3PAM)

NAME
     pam_set_item, pam_get_item - authentication information rou-
     tines for PAM

SYNOPSIS
     cc [ flag ... ] file ... -lpam [ library ... ]
     #include <security/pam_appl.h>

     int pam_set_item(pam_handle_t *pamh,  int  item_type,  const
     void *item);

     int pam_get_item(const pam_handle_t  *pamh,  int  item_type,
     void **item);

DESCRIPTION
     The pam_get_item() and pam_set_item() functions allow appli-
     cations  and PAM service modules to access and to update PAM
     information as needed.   The  information  is  specified  by
     item_type, and can be one of the following:

     PAM_SERVICE
           The service name.

     PAM_USER
           The user name.

     PAM_AUTHTOK
           The user authentication token.

     PAM_OLDAUTHTOK
           The old user authentication token.

     PAM_TTY
           The tty name.

     PAM_RHOST
           The remote host name.

     PAM_RUSER
           The remote user name.

     PAM_CONV
           The  pam_conv structure.

     PAM_USER_PROMPT
           The default prompt used by  pam_get_user().

     For  security  reasons,  the   item_type   PAM_AUTHTOK   and
     PAM_OLDAUTHTOK  are  available only to the module providers.
     The  authentication  module,  account  module,  and  session
     management  module  should  treat PAM_AUTHTOK as the current
     authentication token and ignore PAM_OLDAUTHTOK. The password

SunOS 5.8           Last change: 13 Oct 1998                    1

PAM Library Functions                          pam_set_item(3PAM)

     management module should treat PAM_OLDAUTHTOK as the current
     authentication token and PAM_AUTHTOK as the new  authentica-
     tion token.

     The pam_set_item() function  is  passed  the  authentication
     handle,  pamh,  returned  by  pam_start(),  a pointer to the
     object,  item,  and  its  type,  item_type.  If  successful,
     pam_set_item()  copies  the item to an internal storage area
     allocated by the  authentication module and returns
      PAM_SUCCESS. An item that had been previously set  will  be
     overwritten by the new value.

     The pam_get_item() function  is  passed  the  authentication
     handle, pamh, returned by pam_start(), an item_type, and the
     address of the pointer, item, which is assigned the  address
     of  the  requested  object.  The  object data is valid until
     modified by a subsequent call to pam_set_item() for the same
     item_type, or unless it is modified by any of the underlying
     service modules. If the item has not  been  previously  set,
     pam_get_item() returns a null pointer.  An item retrieved by
     pam_get_item() should not be modified or  freed.   The  item
     will be released by pam_end().

RETURN VALUES
     Upon success, pam_get_item() returns  PAM_SUCCESS; otherwise
     it returns an error code. Refer to pam(3PAM) for information
     on error related return values.

ATTRIBUTES
     See attributes(5) for description of  the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         |  Stable                     |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe with exceptions     |
    |_____________________________|_____________________________|

SEE ALSO
     pam(3PAM),   pam_acct_mgmt(3PAM),    pam_authenticate(3PAM),
     pam_chauthtok(3PAM),                     pam_get_user(3PAM),
     pam_open_session(3PAM), pam_setcred(3PAM),  pam_start(3PAM),
     attributes(5)

NOTES
     The interfaces in  libpam are MT-Safe only  if  each  thread
     within  the  multithreaded application uses its own PAM han-
     dle.

SunOS 5.8           Last change: 13 Oct 1998                    2