.\"	$NetBSD: endutxent.3,v 1.4 2004/05/04 02:38:35 atatat Exp $
.\"
.\" 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.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"        This product includes software developed by the NetBSD
.\"        Foundation, Inc. and its contributors.
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
.\"    contributors may be used to endorse or promote products derived
.\"    from this software without specific prior written permission.
.\"
.\" 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 June 29, 2006
.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
.In utmpx.h
.Ft void
.Fn endutxent void
.Ft struct utmpx *
.Fn getutxent void
.Ft struct utmpx *
.Fn getutxid "const struct utmpx *id"
.Ft struct utmpx *
.Fn getutxline "const struct utmpx *line"
.Ft struct utmpx *
.Fn pututxline "const struct utmpx *utx"
.Ft void
.Fn setutxent void
.Sh DESCRIPTION
These functions provide access to the
.Xr utmpx 5
user accounting database.
.Pp
.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.
.Pp
.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.
.Pp
.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.
Only the superuser may write to the accounting database.
.Ss The utmpx structure
The
.Nm utmpx
structure has the following definition:
.Pp
.Bd -literal
struct utmpx {
	char ut_user[_UTX_USERSIZE];	/* login name */
	char ut_id[_UTX_IDSIZE];	/* id */
	char ut_line[_UTX_LINESIZE];	/* tty name */
	pid_t ut_pid;			/* process id creating the entry */
	short ut_type;			/* type of this entry */
	struct timeval ut_tv;		/* time entry was created */
	char ut_host[_UTX_HOSTSIZE];	/* host name */
	__uint32_t ut_pad[16];		/* reserved for future use */
};
.Ed
.Pp
Valid entries for
.Fa ut_type
are:
.Bl -tag -width ".Dv LOGIN_PROCESSXX" -compact -offset indent
.It Dv BOOT_TIME
Time of a system boot.
.It Dv DEAD_PROCESS
A session leader exited.
.It Dv EMPTY
No valid user accounting information.
.It Dv INIT_PROCESS
A process spawned by
.Xr init 8 .
.It Dv LOGIN_PROCESS
The session leader of a logged-in user.
.It Dv NEW_TIME
Time after system clock change.
.It Dv OLD_TIME
Time before system clock change.
.It Dv RUN_LVL
Run level.
Provided for compatibility, not used.
.It Dv USER_PROCESS
A user process.
.It Dv SHUTDOWN_TIME
Time of system shutdown (extension to the standards).
.El
.Pp
For each value of
.Fa ut_type ,
the other fields with meaningful values are as follows:
.Bl -tag -width ".Dv LOGIN_PROCESSXX" -compact -offset indent
.It Dv BOOT_TIME
.Fa ut_tv
.It Dv DEAD_PROCESS
.Fa ut_id ,
.Fa ut_pid ,
.Fa ut_tv
.It Dv EMPTY
(no others)
.It Dv INIT_PROCESS
.Fa ut_id ,
.Fa ut_pid ,
.Fa ut_tv
.It Dv LOGIN_PROCESS
.Fa ut_id ,
.Fa ut_user
(implementation-defined name of the login process),
.Fa ut_pid ,
.Fa ut_tv
.It Dv NEW_TIME
.Fa ut_tv
.It Dv OLD_TIME
.Fa ut_tv
.It Dv RUN_LVL
(no used)
.It Dv USER_PROCESS
.Fa ut_id ,
.Fa ut_user
(login name of the user),
.Fa ut_line ,
.Fa ut_pid ,
.Fa ut_host
(hostname of remote user)
.Fa ut_tv
.It Dv SHUTDOWN_TIME
.Fa ut_tv
.El
.Ss Other extensions to the standards
The
.Fa ut_tv
value may also be OR-ed with the following masks:
.Bl -tag -width XXXX -compact -offset indent
.It Dv UTMPX_AUTOFILL_MASK
Depending on the
.Fa ut_type
value, other fields are automatically filled in (as specified in the
meaningful fields table above).
In particular, the
.Fa ut_id
field will be set using the convention of the last four characters of the
.Fa ut_line
field (itself filled in automatically from the tty name of the device connected
to the standard input, output or error, whichever is available).
Note that it is more efficient to fill in as many values as are already
available beforehand, rather than have then automatically filled in.
.It Dv UTMPX_DEAD_IF_CORRESPONDING_MASK
When
.Fa ut_type
value is
.Dv DEAD_PROCESS, a call to
.Fn pututxline
will succeed only if a corresponding entry already exists with a
.Fa ut_type
value of
.Dv USER_PROCESS .
.El
.Pp
Note that the above mask values do not show up in any file format, or in
any subsequent reads of the data.
.Pp
To support
.Pa wtmpx
and
.Pa lastlogx
equivalent capability,
.Fn pututxline
automatically writes to the appropriate files.
Additional APIs to read these files is available in
.Xr endutxent_wtmp 3
and
.Xr getlastlogx 3 .
.Ss Backward compatibility
Successful calls to
.Fn pututxline
will automatically write equivalent entries into the
.Pa utmp ,
.Pa wtmp
and
.Pa lastlog
files.
Programs that read these old files should work as expected.
However, directly writing to these files does not make corresponding
entries in
.Pa utmpx
and the
.Pa wtmpx
and
.Pa lastlogx
equivalent files, so such write-access is deprecated.
.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.
.Pp
.Fn pututxline
returns the structure that was successfully written, or
.Dv NULL
is returned and the global variable
.Va errno
is set to indicate the error.
.Sh ERRORS
No errors are defined for the 
.Fn endutxent ,
.Fn getutxent ,
.Fn getutxid ,
.Fn getutxline ,
and
.Fn setutxent
functions.
.Pp
The
.Fn pututxline
function may fail if:
.Bl -tag -width Er
.It Bq Er EPERM
The process does not have appropriate privileges.
.It Bq Er EINVAL
The
.Dv UTMPX_DEAD_IF_CORRESPONDING_MASK
flags was specified along with
.Dv DEAD_PROCESS ,
but no corresponding entry with
.Dv USER_PROCESS
was found.
.El
.Pp
Other errors may be returned if
.Dv UTMPX_AUTOFILL_MASK
was specified, and a field could not be auto-filled.
.Sh SEE ALSO
.Xr endutxent_wtmp 3 ,
.Xr getlastlogx 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?