HP-UX Reference (11i v2 07/12) - 3 Library Functions A-M (vol 6)

g
getuts(3C) getuts(3C)
If ut_type specified is RUN_LVL
, BOOT_TIME, OLD_TIME,orNEW_TIME,
getutsid() fetches an entry with a ut_type matching id->ut_type. If no match-
ing entry is found
getutsid() fails and returns NULL. The macro
GETUT-
SID()
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,orNEW_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.
558 Hewlett-Packard Company − 2 − HP-UX 11i Version 2: December 2007 Update