Technical Reference: Base Operating System and Extensions, Volume 1

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:

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

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:

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.

Related Information

The authenticate (authenticate Subroutine) subroutine, getpcred (getpcred Subroutine) subroutine, getpenv (getpenv Subroutine) subroutine, loginfailed (loginfailed Subroutine) subroutine, loginrestrictions (loginrestrictions Subroutine) subroutine, setpcred subroutine, setpenv subroutine.

List of Security and Auditing Services in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.

Subroutines Overview in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.