authenticate_user(3x)													     authenticate_user(3x)

Name
       authenticate_user - authenticate user

Syntax
       #include <pwd.h>
       #include <auth.h>   /* For error codes */

       int authenticate_user(user, password, line)
       struct passwd *user;
       char *password;
       char *line;

Arguments
       user
	 A pointer to the passwd entry.

       password
	 A pointer to the password.

       line
	 The name of the terminal line as it is listed in the file.

Description
       The  routine authenticates a user name or UID against a supplied password and returns a nonnegative integer on success.	The value returned
       is the number of failed login authentication attempts since the last successful login authentication  (or  zero	if  this  feature  is  not
       enabled).  This routine is found in the library and loaded with the -lauth option.

       At all security levels higher than BSD, the login fail count in the auth database is incremented if authentication fails, and cleared if it
       succeeds.  In addition, the account must be marked enabled for logins as defined by the Account Mask value for A_LOGIN.	See  for  informa-
       tion about the Account Mask values.

       If  a  non-NULL	value is supplied for the argument and the argument is not the empty string, the function also verifies that the specified
       user is allowed access through that line. In particular, accounts with a UID equal to zero will return success only if the  specified  line
       is marked secure in the file.

Restrictions
       The process must have read access to the auth database to authenticate users in a secure environment.

       The process must have read/write access to the auth database to update the authentication fail count.

       If auth information is being served through BIND, the process is required to obtain a Kerberos ticket for that service before invoking this
       function.

Example
       extern int errno;
       struct passwd *pwd;
       int status;

       pwd = getpwnam("root");
       status = authenticate_user(pwd, "rootpass", "/dev/console");
       if(status < 0)
	    if(errno == EPERM)
		 puts("Login failed");
	    else
		 perror("authenticate_user");
       else
	    if(status > 0)
		 printf("%d failed attempts
", status);

Return Values
       When successful, the routine returns the number of failed login authentication attempts since last successful login authentication.

       When an error occurs, errno is set and a negative error code is returned. The error code returned may be the same as errno or it may be	an
       extended error code defined in

Diagnostics
       On error return errno may be set to one of the following values:

       [EPERM]		 Either  the  password	is  incorrect,	the  password is expired, the specified line needs to be secure and is not, or the
			 account is disabled and a login authentication is required.

       [EINVAL] 	 No authentication information for user.

       [ENOSYS] 	 Security subsystem not configured correctly.

       [EACCES] 	 Process does not have read access to the necessary information.

       On error return the return value may be the same as errno or, if errno is [EPERM], it may be one of the following additional values defined
       in

       [A_EBADPASS]	 The supplied password was incorrect.

       [A_ESOFTEXP]	 The account's password expired recently.

       [A_EHARDEXP]	 The account's password expired quite some time ago.

       [A_ENOLOGIN]	 The account is not enabled.

       [A_EOPENLINE]	 The account requires a secure line and the specified line was not marked that way in the file.

Files
Environment
       If  the	system	is  operating in the BSD security level, the password expiration, login fail count, and account disabling features are not
       available (and therefore are not used in authentication computations).

See Also
       getauthent(3x), getpwent(3), auth(5), passwd(5yp), ttys(5)

															     authenticate_user(3x)