getuts(3C)

NAME

getuts: endutsent(), getutsent(), getutsid(), getutsline(), pututsline(), setutsent(), ENDUTSENT(), GETUTSENT(), GETUTSID(), GETUTSLINE(), PUTUTSLINE(), SETUTSENT(), — access and update routines for user-accounting database maintained by utmpd

SYNOPSIS

#include <utmps.h>

struct utmps * getutsent(size_t utmps_size):

struct utmps * getutsid(const struct utmps *id, size_t utmps_size):

struct utmps * getutsline(const struct utmps *line, size_t utmps_size):

struct utmps * pututsline(const struct utmps *utmps, size_t utmps_size):

struct utmps * getutspid( pid_t pid, size_t utmps_size):

void setutsent(void):

void endutsent(void):

Remarks

The size of the utmps structure (for example sizeof(struct utmps)) is passed as utmps_size parameter in the above calls.

A macro equivalent exists for each of the above function calls. These macros provide a shorthand way of calling getuts(3C) functions, by implicitly passing the utmps_size parameter to the corresponding getuts(3C) function.

struct utmps * GETUTSENT():

struct utmps * GETUTSID(const struct utmps *id):

struct utmps * GETUTSLINE(const struct utmps *line):

struct utmps * PUTUTSLINE(const struct utmps * utmps):

struct utmps * GETUTSPID( pid_t pid):

void SETUTSENT(void):

void ENDUTSENT(void):

DESCRIPTION

getutsent(), getutsid(), and getutsline() each return a pointer to a utmps structure, the key elements of the utmps structure are

char ut_user[]           User login name
char ut_id[]             Unique Id to distinguish an entry
char ut_line[]           Device name
pid_t ut_pid             Process Id
short ut_type            Type of Entry
struct ut_exit           The exit status of a process
struct timeval ut_tv     Time entry was made
char ut_host[]           Host name, if remote
uint8_t ut_addr[]        Internet Address of the Host,
                           if remote
short ut_addr_type       Flag to identify type of address
                           in ut_addr

Routines

getutsent()

This call returns the next record from the in-memory user accounting database maintained by utmpd(1M). When the end of the utmpd's database is reached getutsent() fails and returns NULL. The macro GETUTSENT() is a wrapper around getutsent() and implicitly passes the utmps_size parameter.

getutsid()

For entries of ut_type matching INIT_PROCESS, LOGIN_PROCESS, USER_PROCESS and DEAD_PROCESS, getutsid() searches the utmpd's database for an entry matching id->ut_id field. The record is fetched irrespective of the current position in the internal ordering and does not alter the current position in the internal ordering for the getutsent() API.

If ut_type specified is RUN_LVL, BOOT_TIME, OLD_TIME, or NEW_TIME, getutsid() fetches an entry with a ut_type matching id->ut_type. If no matching entry is found getutsid() fails and returns NULL. The macro GETUTSID() is a wrapper around getutsid() and implicitly passes the utmps_size parameter to getutsid().

getutsline()

This is similar to getutsid(). It searches the utmpd(1M)'s database for an entry of type LOGIN_PROCESS or USER_PROCESS that also has the ut_line field matching the line->ut_line string. If the entry is not found in the utmpd()'s database, getutsline() fails and returns NULL. The record is fetched irrespective of the current position in the internal ordering and does not alter the internal ordering for the getutsent() API. The macro GETUTSLINE() is a wrapper around getutsline() and implicitly passes the utmps_size parameter to getutsline().

pututsline()

Writes out the supplied utmps structure into the in-memory user accounting database maintained by utmpd(1M). For entries of ut_type matching INIT_PROCESS, LOGIN_PROCESS, USER_PROCESS and DEAD_PROCESS, pututsline() searches the utmpd(1M)'s database for an entry matching utmps->ut_id field. If the entry already exists in the utmpd(1M)'s database, this API updates the entry already present. Otherwise, pututsline() adds a new entry into the utmpd(1M)'s database.

If ut_type specified is RUN_LVL, BOOT_TIME, OLD_TIME, or NEW_TIME, pututsline() updates the entry with ut_type matching utmps->ut_type. The macro PUTUTSLINE() is a wrapper around pututsline() and implicitly passes the utmps_size parameter to pututsline().

getutspid()

This API searches the utmpd(1M)'s database for an entry with ut_pid matching the pid argument. Since pid has significance only for currently ACTIVE processes, matching is done only for entries of type INIT_PROCESS, LOGIN_PROCESS, or USER_PROCESS. On finding a matching entry, getutspid() returns the corresponding entry; otherwise, getutspid() fails and returns NULL. The macro GETUTSPID() is a wrapper around getutspid() and implicitly passes the utmps_size parameter to getutspid().

setutsent()

Resets the requests for getutsent() to begin from the start of the utmpd(1M)'s database. It also clears out the static structure. The macro SETUTSENT() is a wrapper around setutsent().

endutsent()

It closes any open file descriptors and clears out the static structure. The macro ENDUTSENT() is a wrapper around endutsent().

The specific calling convention of passing the expected data structure size is used in order to allow for future expansion of the interface, and the utmps structure while preserving backward compatibility for programs written using the getuts(3C) interfaces.

The interfaces encode the version information of the utmps structure in the utmps_size parameter. Should the utmps structure change in a future release, utmpd(1M) and libc interfaces detect the version of the utmps structure the application was compiled with based on the utmps_size parameter and return the appropriate utmps structure.

The getuts(3C) interfaces use /etc/utmps file only when the utmpd(1M) is not running. This feature may be discontinued in a future release. The ut_addr field in the utmps structure can hold a 16 byte IPv6 address. In case applications want to write a four byte IPv4 address into this field, they must initialize the ut_addr_type field to IPV4_ADDRESS and use the last four bytes of the ut_addr field. Applications which write an IPv6 address into the ut_addr field must initialize the ut_addr_type to IPV6_ADDRESS. IPV4_ADDRESS and IPV6_ADDRESS are macros defined in utmps.h header file.

RETURN VALUE

getutsent(), getutsid(), getutsline(), pututsline(), and getutspid() return a pointer to static utmps structure on success. On failure they return NULL.

ERRORS

EINVAL: The size parameter passed to the getuts functions does not match any of the structure sizes supported by the server.

WARNINGS

If the size of a member of the utmps structure changes in a future release, applications compiled with older version of the utmps structure will get truncated information for the structure fields that have expanded. To get the complete information, the applications have to be re-compiled.

The value returned by getutsent(), getutsid(), getutsline(), pututsline(), and getutspid() points to a single static area that is overwritten by each call to any of the functions, so it must be copied if it is to be saved.

AUTHOR

The getuts() routines were developed by Hewlett-Packard Company.

FILES

/etc/utmps