pam_setcred(3) -- Linux man page
pam_setcred - set the credentials for the user
int pam_setcred(pam_handle_t *pamh, int flags);
This function is used to establish, maintain and delete the credentials of a user. It should be called after a user has been authenticated and before a session is opened for the user (with pam_open_session(3)).
It should be noted that credentials come in many forms. Examples include: group memberships; ticket-files; and Linux-PAM environment variables. For this reason, it is important that the basic identity of the user is established, by the application, prior to a call to this function. For example, the default Linux-PAM environment variables should be set and also initgroups(2) (or equivalent) should have been performed.
initialize the credentials for the user.
delete the user's credentials.
delete and then initialize the user's credentials.
extend the lifetime of the existing credentials.
On success PAM_SUCCESS is returned, all other return values should be treated as errors.
ERRORSMay be translated to text with pam_strerror(3).
CONFORMING TODCE-RFC 86.0, October 1995.
Also, see the three Linux-PAM Guides, for System administrators, module developers, and application developers.