Ulog — C Library Procedures

NAME

Ulog − obtain or update information in the database of user logins and logouts.

SYNOPSIS

#include<ulog.h>
Ulog_Data ∗
Ulog_LastLogin(uid)
int
Ulog_GetAllLogins(numEntries, locPtr, dataArray)
int
Ulog_RecordLogin(uid, location, portID)
int
Ulog_RecordLogout(uid, portID)
int
Ulog_ClearLogins()

ARGUMENTS

int uid (in) A numerical identifier for a user for whom to retrieve or update information.

int numEntries (in) The number of Ulog_Data structures contained in dataArray.

int ∗locPtr (in/out) A pointer to an integer specifying the index of the next record in the user log to access.

Ulog_Data dataArray[] (out) A buffer to hold Ulog_Data entries returned by the Ulog_GetAllLogins routine.

char ∗location (in) String specifying location of user logging in (i.e., remote host)

int portID (in) Numerical identifier for login port.

DESCRIPTION

The ulog library provides a facility to record logins and logouts in the system, to retrieve information about the last time a user logged in or about all users logged into the system, and to clear the login entries for a host. Each host has a fixed number of entries allocated to it in the user log database file. One entry, with a portID of ULOG_LOC_CONSOLE, is reserved for the console of a host; there are (ULOG_MAX_PORTS - 1) other entries available for rlogin processes. (There is currently no facility for multiple local logins, such as over a serial line.)

The ulog library converts between the ASCII representation stored in the database and an internal C structure, known as a Ulog_Data structure. This structure contains information giving <uid,hostID,portID> corresponding to a user logged in on a particular “port” on a particular host. Each login entry also includes the time of the login, which is the tv_sec part of a time structure. It also includes any additional information for the location of the user; this is an arbitrary string that typically gives the host from which an rlogin occurs. Two database files are used: one for logins on a host/port basis, and one for the last login by each user.

A Ulog_Data structure is defined as follows: typedef struct { int uid; /∗ user identifier ∗/ int hostID; /∗ host for which data is valid ∗/ int portID; /∗ port within host ∗/ int updated; /∗ login time (in seconds since 1/1/70); 0 if invalid ∗/ char location[ULOG_LOC_LENGTH]; /∗ location of user ∗/ } Ulog_Data;

The Ulog_LastLogin() procedure returns a pointer to a statically-allocated Ulog_Data structure. Therefore, the contents of the structure may change on subsequent calls to Ulog_LastLogin(). The information returned by Ulog_LastLogin() corresponds to the most recent login by the user specified by uid.

Ulog_GetAllLogins() provides a mechanism for retrieving multiple login entries at once. The user must allocate an array of Ulog_Data structures, and pass the size of the array and a pointer to it as arguments to Ulog_GetAllLogins(). In addition, the locPtr argument specifies where in the login database to start looking. ∗locPtr should be initialized to 0 prior to the first call to Ulog_GetAllLogins(). Ulog_GetAllLogins() returns the number of entries in dataArray that were filled. If that number is less than the maximum number specified by numEntries, then all data has been returned. If it is equal to numEntries, then Ulog_GetAllLogins() should be called again to retrieve additional entries from the point at which the last call left off (given by ∗locPtr).

Ulog_RecordLogin() allows the caller to register information for a new login. The caller specifies the user ID, location, and port of the user logging in. The procedure obtains the hostID and current time, and records the login.

Ulog_RecordLogout() provides a similar facility to record logouts. It takes a user ID and port number, and it removes the corresponding loginn from the list of active logins.

Ulog_ClearLogins() may be used at boot time to clear any old entries in the user log for the current host. Note: if a host is down, it may still have entries in the user log. It is the responsibility of the user to use the migration information database to determine if a host is up, in order to validate user log entries.

DIAGNOSTICS

Ulog_RecordLogin(), Ulog_RecordLogout(), and Ulog_ClearLogins() return zero if all went well. Otherwise they return -1 and the errno variable contains additional information about what error occurred. Ulog_GetAllLogins() similarly returns -1 on error, but it returns 0 if no more records are available. Ulog_LastLogin() returns NULL on error.

FILES

/sprite/admin/data/userLog
The database of current logins on each host.

/sprite/admin/data/lastLog
The database of each user’s most recent login.

KEYWORDS

user log, user ID, sprite ID

Museum