pam_authenticate man page
pam_authenticate — account authentication
int pam_authenticate(pam_handle_t *pamh, int flags);
The pam_authenticate function is used to authenticate the user. The user is required to provide an authentication token depending upon the authentication service, usually this is a password, but could also be a finger print.
The PAM service module may request that the user enter their username via the conversation mechanism (see pam_start(3) and pam_conv(3)). The name of the authenticated user will be present in the PAM item PAM_USER. This item may be recovered with a call to pam_get_item(3).
The pamh argument is an authentication handle obtained by a prior call to pam_start(). The flags argument is the binary or of zero or more of the following values:
Do not emit any messages.
The PAM module service should return PAM_AUTH_ERR if the user does not have a registered authentication token.
The application should exit immediately after calling pam_end(3) first.
The user was not authenticated.
For some reason the application does not have sufficient credentials to authenticate the user.
The modules were not able to access the authentication information. This might be due to a network or hardware failure etc.
One or more of the authentication modules has reached its limit of tries authenticating the user. Do not try again.
The user was successfully authenticated.
User unknown to authentication service.
pam_start(3), pam_setcred(3), pam_chauthtok(3), pam_strerror(3), pam(8)
pam(3), PAM(8), pam_acct_mgmt(3), pam_chauthtok(3), pam_fail_delay(3), pam_filter(8), pam_setcred(3), pam_set_data(3), pam_sm_authenticate(3), pam_sm_setcred(3).