Copyright (c) 2002 The NetBSD Foundation, Inc.
All rights reserved.
This code is derived from software contributed to The NetBSD Foundation
by Thomas Klausner.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
.Dd September 26, 2002 .Dt ENDUTXENT 3 .Os .Sh NAME .Nm endutxent , .Nm getutxent , .Nm getutxid , .Nm getutxline , .Nm pututxline , .Nm setutxent .Nd user accounting database functions .Sh LIBRARY .Lb libc .Sh SYNOPSIS n utmpx.h .Ft void .Fn endutxent void .Ft struct utmpx * .Fn getutxent void .Ft struct utmpx * .Fn getutxid "const struct utmpx *" .Ft struct utmpx * .Fn getutxline "const struct utmpx *" .Ft struct utmpx * .Fn pututxline "const struct utmpx *" .Ft void .Fn setutxent void .Sh DESCRIPTION These functions provide access to the .Xr utmpx 5 user accounting database.
p .Fn getutxent reads the next entry from the database; if the database was not yet open, it also opens it. .Fn setutxent resets the database, so that the next .Fn getutxent call will get the first entry. .Fn endutxent closes the database.
p .Fn getutxid returns the next entry of the type specified in its argument's .Va ut_type field, or .Dv NULL if none is found. .Fn getutxline returns the next .Dv LOGIN_PROCESS or .Dv USER_PROCESS entry which has the same name as specified in the .Va ut_line field, or .Dv NULL if no match is found.
p .Fn pututxline adds the argument .Xr utmpx 5 entry line to the accounting database, replacing a previous entry for the same user if it exists. .Ss The utmpx structure The .Nm utmpx structure has the following definition:
p d -literal struct utmpx { char ut_name[_UTX_USERSIZE]; /* login name */ char ut_id[_UTX_IDSIZE]; /* inittab id */ char ut_line[_UTX_LINESIZE]; /* tty name */ char ut_host[_UTX_HOSTSIZE]; /* host name */ uint16_t ut_session; /* session id used for windowing */ uint16_t ut_type; /* type of this entry */ pid_t ut_pid; /* process id creating the entry */ struct { uint16_t e_termination; /* process termination signal */ uint16_t e_exit; /* process exit status */ } ut_exit; struct sockaddr_storage ut_ss; /* address where entry was made from */ struct timeval ut_tv; /* time entry was created */ uint32_t ut_pad[10]; /* reserved for future use */ }; .Ed
p
Valid entries for
.Fa ut_type
are:
l -tag -width LOGIN_PROCESSXX -compact -offset indent t Dv BOOT_TIME Time of a system boot.
t Dv DEAD_PROCESS A session leader exited.
t Dv EMPTY No valid user accounting information.
t Dv INIT_PROCESS A process spawned by
.Xr init 8 .
t Dv LOGIN_PROCESS The session leader of a logged-in user.
t Dv NEW_TIME Time after system clock change.
t Dv OLD_TIME Time before system clock change.
t Dv RUN_LVL Run level.
Provided for compatibility, not used on
.Nx .
t Dv USER_PROCESS A user process.
.El
.Sh RETURN VALUES
.Fn getutxent
returns the next entry, or
.Dv NULL
on failure (end of database or problems reading from the database).
.Fn getutxid
and
.Fn getutxline
return the matching structure on success, or
.Dv NULL
if no match was found.
.Fn pututxline
returns the structure that was successfully written, or
.Dv NULL .
.Sh SEE ALSO
.Xr logwtmpx 3 ,
.Xr utmpx 5
.Sh STANDARDS
The
.Fn endutxent ,
.Fn getutxent ,
.Fn getutxid ,
.Fn getutxline ,
.Fn pututxline ,
.Fn setutxent
all conform to
.St -p1003.1-2001
(XSI extension), and previously to
.St -xpg4.2 .
The fields
.Fa ut_user ,
.Fa ut_id ,
.Fa ut_line ,
.Fa ut_pid ,
.Fa ut_type ,
and
.Fa ut_tv
conform to
.St -p1003.1-2001
(XSI extension), and previously to
.St -xpg4.2 .
.Fa ut_host ,
.Fa ut_session ,
.Fa ut_exit ,
and
.Fa ut_ss
are from
SVR3/4?
.Dv RUN_LVL
is for compatibility with
what exactly?
.Sh HISTORY
The
.Nm utmpx ,
.Nm wtmpx ,
and
.Nm lastlogx
files first appeared in
SVR3? 4?