loginsuccess Subroutine

Edit online

Purpose

Records a successful log in.

Library

Security Library (libc.a)

Syntax

#include <usersec.h> int loginsuccess (User, Host, Tty, Msg) char * User; char * Host; char * Tty; char ** Msg;

Note: This subroutine is not thread-safe.

Description

The loginsuccess subroutine performs the processing necessary when a user successfully logs into the system. This subroutine updates the following attributes in the /etc/security/lastlog file for the specified user:

Item	Description
time_last_login	Contains the current time.
tty_last_login	Contains the value specified by the Tty parameter.
host_last_login	Contains the value specified by the Host parameter or the local host name if the Host parameter is a null value.
unsuccessful_login_count	Indicates the number of unsuccessful login attempts. The loginsuccess subroutine resets this attribute to a value of 0.

Additionally, a login success audit record is cut to indicate in the audit trail that this user has successfully logged in.

A message is returned in the Msg parameter that indicates the time, host, and port of the last successful and unsuccessful login. The number of unsuccessful login attempts since the last successful login is also provided to the user.

Parameters

Item	Description
User	Specifies the login name of the user who has successfully logged in.
Host	Specifies the name of the host from which the user logged in. If the Host parameter is a null value, the name of the local host is used.
Tty	Specifies the name of the terminal which the user used to log in.
Msg	Returns a message indicating the delete time, host, and port of the last successful and unsuccessful logins. The number of unsuccessful login attempts since the last successful login is also provided. Upon return, the value is either a pointer to a valid string within memory allocated storage or a null pointer. It is the responsibility of the calling program to free( ) the returned storage.

Security

Access Control: The calling process must have access to the account information in the user database.

File Accessed:

Mode	File
rw	/etc/security/lastlog

Auditing Events:

Event	Information
USER_Login	username

Return Values

Upon successful completion, the loginsuccess subroutine returns a value of 0. Otherwise, a value of -1 is returned and the errno global value is set to indicate the error.

Note: If the load module does not have interface support that is defined in the security library, the loginsuccess subroutine might return a value of 0 (success), and display ENOSYS as the errno value.

Error Codes

The loginsuccess subroutine fails if one or more of the following values is true:

Item	Description
ENOENT	The specified user does not exist.
EACCES	The current process does not have write access to the user database.
EPERM	The current process does not have permission to write an audit record.
ENOSYS	The load module does not have the required interface support defined in the security library.