pam_open_session(3)

NAME
     pam_open_session, pam_close_session - perform PAM session creation and ter-
     mination operations

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

     int pam_open_session(pam_handle_t *pamh, int flags);

     int pam_close_session(pam_handle_t *pamh, int flags);

DESCRIPTION
     pam_open_session()  is  called after a user has been successfully authenti-
     cated (refer to pam_authenticate(3) and pam_acct_mgmt(3)) and  is  used  to
     notify the session modules that a new session has been initiated.  All pro-
     grams that use the pam(3) library should invoke pam_open_session() when be-
     ginning  a  new session.  Upon termination of this activity, pam_close_ses-
     sion() should be invoked to inform pam(3) that the session has terminated.

     The pamh argument is an authentication handle obtained by a prior  call  to
     pam_start().   The  following  flag  may  be  set  in  the  flags field for
     pam_open_session() and pam_close_session():

            PAM_SILENT      The session service should not generate any messages


NOTES
     In many instances, the pam_open_session() and pam_close_session() calls may
     be made by different processes.  For example, in  UNIX  the  login  process
     opens  a session, while the init process closes the session.  In this case,
     UTMP/WTMP entries may be used to link the call to pam_close_session()  with
     an  earlier call to pam_open_session().  This is possible because UTMP/WTMP
     entries are uniquely identified by a combination of  attributes,  including
     the  user  login name and device name, which are accessible through the pam
     handle, pamh.  The call to pam_open_session() should precede UTMP/WTMP  en-
     try  management and the call to pam_close_session() should follow UTMP/WTMP
     exit management.

RETURN VALUES
     Upon successful completion, PAM_SUCCESS is returned.  In  addition  to  the
     return values defined in pam(3), the following value may be returned on er-
     ror:

            PAM_SESSION_ERR       Can not make/remove an entry for the specified
                                  session

SEE ALSO
     pam(3), pam_start(3), pam_authenticate(3), pam_acct_mgmt(3), getutxent(3C)