loginsuccess Subroutine

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.

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.