setutxdb(3): Constify the file name argument.

[dragonfly.git] / lib / libc / gen / endutxent.3

.\"	$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.
.\"
.\" 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 August 30, 2019
.Dt ENDUTXENT 3
.Os
.Sh NAME
.Nm endutxent ,
.Nm getutxent ,
.Nm getutxid ,
.Nm getutxline ,
.Nm pututxline ,
.Nm setutxent ,
.Nm setutxdb
.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 *"
.Ft struct utmpx *
.Fn getutxline "const struct utmpx *"
.Ft struct utmpx *
.Fn pututxline "const struct utmpx *"
.Ft void
.Fn setutxent void
.Ft int
.Fn setutxdb "utx_db_t db" "const char *fname"
.Sh DESCRIPTION
These functions provide access to the
.Xr utmpx 5
and
.Xr wtmpx 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.
.Pp
By default the aforementioned functions work on the default
.Xr utmpx 5
database. The function
.Fn setutxdb
allows to change the database type being operated on, as well
as changing the path to that database.
The first parameter
.Ar db
can be
.Dv UTX_DB_UTMPX
or
.Dv UTX_DB_WTMPX
and specifies which database to open. If
.Ar fname
is
.Dv NULL
the default path for each of these is used as described in
.Xr utmpx 5
and
.Xr wtmpx 5 .
Otherwise the path specified in
.Ar fname
is used as the database.
.Ss The utmpx structure
The
.Nm utmpx
structure has the following definition:
.Bd -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 */
        short 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
.Pp
Valid entries for
.Fa ut_type
are:
.Bl -tag -width 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 on
.Nx .
.It 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 .
.Fn setutxdb
returns
.Dv 0
on success. Otherwise a negative value is returned and the global
variable
.Va errno
is set to indicate the error.
.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?