d/freebsd-dev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
b1e20a1db5
freebsd-dev/lib/libc/gen/getutxent.3

479 lines
11 KiB
Groff
Raw Normal View History

Implement <utmpx.h>. The utmpx interface is the standardized interface of the user accounting database. The standard only defines a subset of the functions that were present in System V-like systems. I'd like to highlight some of the traits my implementation has: - The standard allows the on-disk format to be different than the in-memory representation (struct utmpx). Most operating systems don't do this, but we do. This allows us to keep our ABI more stable, while giving us the opportunity to modify the on-disk format. It also allows us to use a common file format across different architectures (i.e. byte ordering). - Our implementation of pututxline() also updates wtmp and lastlog (now called utx.log and utx.lastlogin). This means the databases are more likely to be in sync. - Care must be taken that our implementation discard any fields that are not applicable. For example, our DEAD_PROCESS records do not hold a TTY name. Just a time stamp, a record identifier and a process identifier. It also guarantees that strings (ut_host, ut_line and ut_user) are null terminated. ut_id is obviously not null terminated, because it's not a string. - The API and its behaviour should be conformant to POSIX, but there may be things that slightly deviate from the standard. This implementation uses separate file descriptors when writing to the log files. It also doesn't use getutxid() to search for a field to overwrite. It uses an allocation strategy similar to getutxid(), but prevents DEAD_PROCESS records from accumulating. Make sure libulog doesn't overwrite the manpages shipped with our C library. Also keep the symbol list in Symbol.map sorted. I'll bump __FreeBSD_version later this evening. I first want to convert everything to <utmpx.h> and get rid of <utmp.h>.
2010-01-13 17:29:55 +00:00
.\" Copyright (c) 2010 Ed Schouten <ed@FreeBSD.org>
.\" All rights reserved.
.\"
.\" 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 AUTHOR 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 AUTHOR 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.
.\"
.\" $FreeBSD$
.\"
Don't forget to kick the man page date.
2011-10-27 17:21:41 +00:00
.Dd October 27, 2011
Implement <utmpx.h>. The utmpx interface is the standardized interface of the user accounting database. The standard only defines a subset of the functions that were present in System V-like systems. I'd like to highlight some of the traits my implementation has: - The standard allows the on-disk format to be different than the in-memory representation (struct utmpx). Most operating systems don't do this, but we do. This allows us to keep our ABI more stable, while giving us the opportunity to modify the on-disk format. It also allows us to use a common file format across different architectures (i.e. byte ordering). - Our implementation of pututxline() also updates wtmp and lastlog (now called utx.log and utx.lastlogin). This means the databases are more likely to be in sync. - Care must be taken that our implementation discard any fields that are not applicable. For example, our DEAD_PROCESS records do not hold a TTY name. Just a time stamp, a record identifier and a process identifier. It also guarantees that strings (ut_host, ut_line and ut_user) are null terminated. ut_id is obviously not null terminated, because it's not a string. - The API and its behaviour should be conformant to POSIX, but there may be things that slightly deviate from the standard. This implementation uses separate file descriptors when writing to the log files. It also doesn't use getutxid() to search for a field to overwrite. It uses an allocation strategy similar to getutxid(), but prevents DEAD_PROCESS records from accumulating. Make sure libulog doesn't overwrite the manpages shipped with our C library. Also keep the symbol list in Symbol.map sorted. I'll bump __FreeBSD_version later this evening. I first want to convert everything to <utmpx.h> and get rid of <utmp.h>.
2010-01-13 17:29:55 +00:00
.Dt GETUTXENT 3
mdoc: order prologue macros consistently by Dd/Dt/Os Although groff_mdoc(7) gives another impression, this is the ordering most widely used and also required by mdocml/mandoc. Reviewed by: ru Approved by: philip, ed (mentors)
2010-04-14 19:08:06 +00:00
.Os
Implement <utmpx.h>. The utmpx interface is the standardized interface of the user accounting database. The standard only defines a subset of the functions that were present in System V-like systems. I'd like to highlight some of the traits my implementation has: - The standard allows the on-disk format to be different than the in-memory representation (struct utmpx). Most operating systems don't do this, but we do. This allows us to keep our ABI more stable, while giving us the opportunity to modify the on-disk format. It also allows us to use a common file format across different architectures (i.e. byte ordering). - Our implementation of pututxline() also updates wtmp and lastlog (now called utx.log and utx.lastlogin). This means the databases are more likely to be in sync. - Care must be taken that our implementation discard any fields that are not applicable. For example, our DEAD_PROCESS records do not hold a TTY name. Just a time stamp, a record identifier and a process identifier. It also guarantees that strings (ut_host, ut_line and ut_user) are null terminated. ut_id is obviously not null terminated, because it's not a string. - The API and its behaviour should be conformant to POSIX, but there may be things that slightly deviate from the standard. This implementation uses separate file descriptors when writing to the log files. It also doesn't use getutxid() to search for a field to overwrite. It uses an allocation strategy similar to getutxid(), but prevents DEAD_PROCESS records from accumulating. Make sure libulog doesn't overwrite the manpages shipped with our C library. Also keep the symbol list in Symbol.map sorted. I'll bump __FreeBSD_version later this evening. I first want to convert everything to <utmpx.h> and get rid of <utmp.h>.
2010-01-13 17:29:55 +00:00
.Sh NAME
.Nm endutxent ,
.Nm getutxent ,
.Nm getutxid ,
.Nm getutxline ,
.Nm getutxuser ,
.Nm pututxline ,
.Nm setutxdb ,
.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 getutxuser "const char *user"
.Ft struct utmpx *
.Fn pututxline "const struct utmpx *utmpx"
.Ft int
.Fn setutxdb "int type" "const char *file"
.Ft void
.Fn setutxent "void"
.Sh DESCRIPTION
These functions operate on the user accounting database which stores
records of various system activities, such as user login and logouts,
but also system startups and shutdowns and modifications to the system's
clock.
The system stores these records in three databases, each having a
different purpose:
.Bl -tag -width indent
.It Pa /var/run/utx.active
Log of currently active user login sessions.
This file is similar to the traditional
.Pa utmp
file.
This file only contains process related entries, such as user login and
logout records.
.It Pa /var/log/utx.lastlogin
Log of last user login entries per user.
This file is similar to the traditional
.Pa lastlog
file.
This file only contains user login records for users who have at least
logged in once.
.It Pa /var/log/utx.log
Log of all entries, sorted by date of addition.
This file is similar to the traditional
.Pa wtmp
file.
This file may contain any type of record described below.
.El
.Pp
Each entry in these databases is defined by the structure
.Vt utmpx
found in the include file
.In utmpx.h :
.Bd -literal -offset indent
struct utmpx {
short ut_type; /* Type of entry. */
struct timeval ut_tv; /* Time entry was made. */
char ut_id[]; /* Record identifier. */
pid_t ut_pid; /* Process ID. */
char ut_user[]; /* User login name. */
char ut_line[]; /* Device name. */
char ut_host[]; /* Remote hostname. */
};
.Ed
.Pp
The
.Fa ut_type
field indicates the type of the log entry, which can have one of the
following values:
.Bl -tag -width LOGIN_PROCESS
.It Dv EMPTY
No valid user accounting information.
.It Dv BOOT_TIME
Identifies time of system boot.
.It Dv SHUTDOWN_TIME
Identifies time of system shutdown.
.It Dv OLD_TIME
Identifies time when system clock changed.
.It Dv NEW_TIME
Identifies time after system clock changed.
.It Dv USER_PROCESS
Identifies a process.
.It Dv INIT_PROCESS
Identifies a process spawned by the init process.
.It Dv LOGIN_PROCESS
Identifies the session leader of a logged-in user.
.It Dv DEAD_PROCESS
Identifies a session leader who has exited.
.El
.Pp
Entries of type
.Dv INIT_PROCESS
and
.Dv LOGIN_PROCESS
are not processed by this implementation.
.Pp
Other fields inside the structure are:
.Bl -tag -width ut_user
.It Fa ut_tv
Spelling fixes.
2010-08-02 16:01:45 +00:00
The time the event occurred.
EMPTY records don't have a timestamp.
2010-01-23 17:58:40 +00:00
This field is used for all types of entries, except
.Dv EMPTY .
Implement <utmpx.h>. The utmpx interface is the standardized interface of the user accounting database. The standard only defines a subset of the functions that were present in System V-like systems. I'd like to highlight some of the traits my implementation has: - The standard allows the on-disk format to be different than the in-memory representation (struct utmpx). Most operating systems don't do this, but we do. This allows us to keep our ABI more stable, while giving us the opportunity to modify the on-disk format. It also allows us to use a common file format across different architectures (i.e. byte ordering). - Our implementation of pututxline() also updates wtmp and lastlog (now called utx.log and utx.lastlogin). This means the databases are more likely to be in sync. - Care must be taken that our implementation discard any fields that are not applicable. For example, our DEAD_PROCESS records do not hold a TTY name. Just a time stamp, a record identifier and a process identifier. It also guarantees that strings (ut_host, ut_line and ut_user) are null terminated. ut_id is obviously not null terminated, because it's not a string. - The API and its behaviour should be conformant to POSIX, but there may be things that slightly deviate from the standard. This implementation uses separate file descriptors when writing to the log files. It also doesn't use getutxid() to search for a field to overwrite. It uses an allocation strategy similar to getutxid(), but prevents DEAD_PROCESS records from accumulating. Make sure libulog doesn't overwrite the manpages shipped with our C library. Also keep the symbol list in Symbol.map sorted. I'll bump __FreeBSD_version later this evening. I first want to convert everything to <utmpx.h> and get rid of <utmp.h>.
2010-01-13 17:29:55 +00:00
.It Fa ut_id
An identifier that is used to refer to the entry.
This identifier can be used to remove or replace a login entry by
writing a new entry to the database containing the same value for
.Fa ut_id .
This field is only applicable to entries of type
.Dv USER_PROCESS ,
.Dv INIT_PROCESS ,
.Dv LOGIN_PROCESS
and
.Dv DEAD_PROCESS .
.It Fa ut_pid
The process identifier of the session leader of the login session.
This field is only applicable to entries of type
.Dv USER_PROCESS ,
.Dv INIT_PROCESS ,
.Dv LOGIN_PROCESS
and
.Dv DEAD_PROCESS .
.It Fa ut_user
The user login name corresponding with the login session.
This field is only applicable to entries of type
.Dv USER_PROCESS
and
.Dv INIT_PROCESS .
For
.Dv INIT_PROCESS
entries this entry typically contains the name of the login process.
.It Fa ut_line
The name of the TTY character device, without the leading
.Pa /dev/
prefix, corresponding with the device used to facilitate the user login
session.
If no TTY character device is used, this field is left blank.
This field is only applicable to entries of type
Fix whitespace inconsistencies in libc in files copyrighted by me.
2011-06-26 18:27:17 +00:00
.Dv USER_PROCESS
Perform several small cleanups to the utmpx code. - Massively reduce BSS usage. Let futx_to_utx() dynamically allocate the structure. There is only a very small amount of applications out there that needs to use the utmpx database. Wasting 1 KB on unused structures makes little sense. - Just let getutxid() search for matching ut_id's for any *PROCESS-type. This makes the code a bit more future-proof. - Fix a POSIX-mistake: when reading POSIX and the OpenSolaris implementation, getutxline() must return USER_PROCESS and LOGIN_PROCESS records whose ut_lines match. When reading POSIX, it seems LOGIN_PROCESS should not use ut_line at the first place. I have reported this issue.
2010-01-17 21:40:05 +00:00
and
.Dv LOGIN_PROCESS .
Implement <utmpx.h>. The utmpx interface is the standardized interface of the user accounting database. The standard only defines a subset of the functions that were present in System V-like systems. I'd like to highlight some of the traits my implementation has: - The standard allows the on-disk format to be different than the in-memory representation (struct utmpx). Most operating systems don't do this, but we do. This allows us to keep our ABI more stable, while giving us the opportunity to modify the on-disk format. It also allows us to use a common file format across different architectures (i.e. byte ordering). - Our implementation of pututxline() also updates wtmp and lastlog (now called utx.log and utx.lastlogin). This means the databases are more likely to be in sync. - Care must be taken that our implementation discard any fields that are not applicable. For example, our DEAD_PROCESS records do not hold a TTY name. Just a time stamp, a record identifier and a process identifier. It also guarantees that strings (ut_host, ut_line and ut_user) are null terminated. ut_id is obviously not null terminated, because it's not a string. - The API and its behaviour should be conformant to POSIX, but there may be things that slightly deviate from the standard. This implementation uses separate file descriptors when writing to the log files. It also doesn't use getutxid() to search for a field to overwrite. It uses an allocation strategy similar to getutxid(), but prevents DEAD_PROCESS records from accumulating. Make sure libulog doesn't overwrite the manpages shipped with our C library. Also keep the symbol list in Symbol.map sorted. I'll bump __FreeBSD_version later this evening. I first want to convert everything to <utmpx.h> and get rid of <utmp.h>.
2010-01-13 17:29:55 +00:00
.It Fa ut_host
The network hostname of the remote system, connecting to perform a user
login.
If the user login session is not performed across a network, this field
is left blank.
This field is only applicable to entries of type
.Dv USER_PROCESS .
.El
.Pp
This implementation guarantees all inapplicable fields are discarded.
The
.Fa ut_user ,
.Fa ut_line
and
.Fa ut_host
fields of the structure returned by the library functions are also
guaranteed to be null-terminated in this implementation.
.Pp
The
.Fn getutxent
function can be used to read the next entry from the user accounting
database.
.Pp
The
.Fn getutxid
function searches for the next entry in the database of which the
behaviour is based on the
.Fa ut_type
field of
.Fa id .
If
.Fa ut_type
has a value of
.Dv BOOT_TIME ,
.Dv SHUTDOWN_TIME ,
.Dv OLD_TIME
or
.Dv NEW_TIME ,
it will return the next entry whose
.Fa ut_type
has an equal value.
If
.Fa ut_type
has a value of
.Dv USER_PROCESS ,
.Dv INIT_PROCESS ,
.Dv LOGIN_PROCESS
or
.Dv DEAD_PROCESS ,
it will return the next entry whose
.Fa ut_type
has one of the previously mentioned values and whose
.Fa ut_id
is equal.
.Pp
The
.Fn getutxline
function searches for the next entry in the database whose
.Fa ut_type
has a value of
.Dv USER_PROCESS
or
.Dv LOGIN_PROCESS
and whose
.Fa ut_line
- change "is is" to "is" or "it is" - change "the the" to "the" Approved by: lstewart Approved by: sahil (mentor) MFC after: 3 days
2011-10-16 14:30:28 +00:00
is equal to the same field in
Implement <utmpx.h>. The utmpx interface is the standardized interface of the user accounting database. The standard only defines a subset of the functions that were present in System V-like systems. I'd like to highlight some of the traits my implementation has: - The standard allows the on-disk format to be different than the in-memory representation (struct utmpx). Most operating systems don't do this, but we do. This allows us to keep our ABI more stable, while giving us the opportunity to modify the on-disk format. It also allows us to use a common file format across different architectures (i.e. byte ordering). - Our implementation of pututxline() also updates wtmp and lastlog (now called utx.log and utx.lastlogin). This means the databases are more likely to be in sync. - Care must be taken that our implementation discard any fields that are not applicable. For example, our DEAD_PROCESS records do not hold a TTY name. Just a time stamp, a record identifier and a process identifier. It also guarantees that strings (ut_host, ut_line and ut_user) are null terminated. ut_id is obviously not null terminated, because it's not a string. - The API and its behaviour should be conformant to POSIX, but there may be things that slightly deviate from the standard. This implementation uses separate file descriptors when writing to the log files. It also doesn't use getutxid() to search for a field to overwrite. It uses an allocation strategy similar to getutxid(), but prevents DEAD_PROCESS records from accumulating. Make sure libulog doesn't overwrite the manpages shipped with our C library. Also keep the symbol list in Symbol.map sorted. I'll bump __FreeBSD_version later this evening. I first want to convert everything to <utmpx.h> and get rid of <utmp.h>.
2010-01-13 17:29:55 +00:00
.Fa line .
.Pp
The
.Fn getutxuser
function searches for the next entry in the database whose
.Fa ut_type
has a value of
.Dv USER_PROCESS
and whose
.Fa ut_user
is equal to
.Fa user .
.Pp
The previously mentioned functions will automatically try to open the
user accounting database if not already done so.
The
.Fn setutxdb
and
.Fn setutxent
functions allow the database to be opened manually, causing the offset
within the user accounting database to be rewound.
The
.Fn endutxent
function closes the database.
.Pp
The
.Fn setutxent
database always opens the active sessions database.
The
.Fn setutxdb
function opens the database identified by
.Fa type ,
whose value is either
.Dv UTXDB_ACTIVE ,
.Dv UTXDB_LASTLOGIN
or
.Dv UTXDB_LOG .
It will open a custom file with filename
.Fa file
instead of the system-default if
.Fa file
is not null.
Care must be taken that when using a custom filename,
.Fa type
still has to match with the actual format, since each database may use
its own file format.
.Pp
The
.Fn pututxline
function writes record
.Fa utmpx
to the system-default user accounting databases.
The value of
.Fa ut_type
determines which databases are modified.
.Pp
Entries of type
.Dv SHUTDOWN_TIME ,
.Dv OLD_TIME
and
.Dv NEW_TIME
will only be written to
.Pa /var/log/utx.log .
.Pp
Entries of type
.Dv USER_PROCESS
will also be written to
Just ignore the timestamps given to pututxline(). I've noticed many applications do a bad job at timekeeping, for several reasons: - Applications like screen(1) don't update time records when restoring the old user login record. - Many applications only set ut_tv.tv_sec, not ut_tv.tv_usec. This causes many problems for tools such as ac(8), which require the timestamps to be properly ordered. This is why I've decided to let the utmpx code obtain valid timestamps itself.
2010-01-23 08:43:21 +00:00
.Pa /var/run/utx.active
and
.Pa /var/log/utx.lastlogin .
Implement <utmpx.h>. The utmpx interface is the standardized interface of the user accounting database. The standard only defines a subset of the functions that were present in System V-like systems. I'd like to highlight some of the traits my implementation has: - The standard allows the on-disk format to be different than the in-memory representation (struct utmpx). Most operating systems don't do this, but we do. This allows us to keep our ABI more stable, while giving us the opportunity to modify the on-disk format. It also allows us to use a common file format across different architectures (i.e. byte ordering). - Our implementation of pututxline() also updates wtmp and lastlog (now called utx.log and utx.lastlogin). This means the databases are more likely to be in sync. - Care must be taken that our implementation discard any fields that are not applicable. For example, our DEAD_PROCESS records do not hold a TTY name. Just a time stamp, a record identifier and a process identifier. It also guarantees that strings (ut_host, ut_line and ut_user) are null terminated. ut_id is obviously not null terminated, because it's not a string. - The API and its behaviour should be conformant to POSIX, but there may be things that slightly deviate from the standard. This implementation uses separate file descriptors when writing to the log files. It also doesn't use getutxid() to search for a field to overwrite. It uses an allocation strategy similar to getutxid(), but prevents DEAD_PROCESS records from accumulating. Make sure libulog doesn't overwrite the manpages shipped with our C library. Also keep the symbol list in Symbol.map sorted. I'll bump __FreeBSD_version later this evening. I first want to convert everything to <utmpx.h> and get rid of <utmp.h>.
2010-01-13 17:29:55 +00:00
.Pp
Entries of type
.Dv DEAD_PROCESS
will only be written to
.Pa /var/log/utx.log
and
.Pa /var/run/utx.active
if a corresponding
.Dv USER_PROCESS ,
.Dv INIT_PROCESS
or
.Dv LOGIN_PROCESS
entry whose
.Fa ut_id
is equal has been found in the latter.
.Pp
In addition, entries of type
.Dv BOOT_TIME
and
.Dv SHUTDOWN_TIME
Make our utmpx more like System V. When booting the system, truncate the utx.active file, but do write the BOOT_TIME record into it afterwards. This allows one to obtain the boot time of the system as follows: struct utmpx u1 = { .ut_type = BOOT_TIME }, *u2; setutxent(); u2 = getutxid(&u1); Now, the boot time is stored in u2->ut_tv, just like on Linux and other systems. We don't open the utx.active file with O_EXLOCK. It's rather unlikely that other applications use this database at the same time and I want to prevent the possibility of deadlocks in init(8). Discussed with: pluknet
2011-10-27 17:05:18 +00:00
will cause all existing entries in
Implement <utmpx.h>. The utmpx interface is the standardized interface of the user accounting database. The standard only defines a subset of the functions that were present in System V-like systems. I'd like to highlight some of the traits my implementation has: - The standard allows the on-disk format to be different than the in-memory representation (struct utmpx). Most operating systems don't do this, but we do. This allows us to keep our ABI more stable, while giving us the opportunity to modify the on-disk format. It also allows us to use a common file format across different architectures (i.e. byte ordering). - Our implementation of pututxline() also updates wtmp and lastlog (now called utx.log and utx.lastlogin). This means the databases are more likely to be in sync. - Care must be taken that our implementation discard any fields that are not applicable. For example, our DEAD_PROCESS records do not hold a TTY name. Just a time stamp, a record identifier and a process identifier. It also guarantees that strings (ut_host, ut_line and ut_user) are null terminated. ut_id is obviously not null terminated, because it's not a string. - The API and its behaviour should be conformant to POSIX, but there may be things that slightly deviate from the standard. This implementation uses separate file descriptors when writing to the log files. It also doesn't use getutxid() to search for a field to overwrite. It uses an allocation strategy similar to getutxid(), but prevents DEAD_PROCESS records from accumulating. Make sure libulog doesn't overwrite the manpages shipped with our C library. Also keep the symbol list in Symbol.map sorted. I'll bump __FreeBSD_version later this evening. I first want to convert everything to <utmpx.h> and get rid of <utmp.h>.
2010-01-13 17:29:55 +00:00
.Pa /var/run/utx.active
to be discarded.
.Pp
All entries whose type has not been mentioned previously, are discarded
by this implementation of
.Fn pututxline .
Just ignore the timestamps given to pututxline(). I've noticed many applications do a bad job at timekeeping, for several reasons: - Applications like screen(1) don't update time records when restoring the old user login record. - Many applications only set ut_tv.tv_sec, not ut_tv.tv_usec. This causes many problems for tools such as ac(8), which require the timestamps to be properly ordered. This is why I've decided to let the utmpx code obtain valid timestamps itself.
2010-01-23 08:43:21 +00:00
This implementation also ignores the value of
.Fa ut_tv .
Implement <utmpx.h>. The utmpx interface is the standardized interface of the user accounting database. The standard only defines a subset of the functions that were present in System V-like systems. I'd like to highlight some of the traits my implementation has: - The standard allows the on-disk format to be different than the in-memory representation (struct utmpx). Most operating systems don't do this, but we do. This allows us to keep our ABI more stable, while giving us the opportunity to modify the on-disk format. It also allows us to use a common file format across different architectures (i.e. byte ordering). - Our implementation of pututxline() also updates wtmp and lastlog (now called utx.log and utx.lastlogin). This means the databases are more likely to be in sync. - Care must be taken that our implementation discard any fields that are not applicable. For example, our DEAD_PROCESS records do not hold a TTY name. Just a time stamp, a record identifier and a process identifier. It also guarantees that strings (ut_host, ut_line and ut_user) are null terminated. ut_id is obviously not null terminated, because it's not a string. - The API and its behaviour should be conformant to POSIX, but there may be things that slightly deviate from the standard. This implementation uses separate file descriptors when writing to the log files. It also doesn't use getutxid() to search for a field to overwrite. It uses an allocation strategy similar to getutxid(), but prevents DEAD_PROCESS records from accumulating. Make sure libulog doesn't overwrite the manpages shipped with our C library. Also keep the symbol list in Symbol.map sorted. I'll bump __FreeBSD_version later this evening. I first want to convert everything to <utmpx.h> and get rid of <utmp.h>.
2010-01-13 17:29:55 +00:00
.Sh RETURN VALUES
The
.Fn getutxent ,
.Fn getutxid ,
.Fn getutxline ,
and
.Fn getutxuser
functions return a pointer to an
.Vt utmpx
structure that matches the mentioned constraints on success or
.Dv NULL
when reaching the end-of-file or when an error occurs.
.Pp
The
.Fn pututxline
function returns a pointer to an
.Vt utmpx
structure containing a copy of the structure written to disk upon
success.
It returns
.Dv NULL
when the provided
.Vt utmpx
Properly styleify utmpx code and document error codes in man page. Submitted by: Garrett Cooper
2011-02-19 11:31:56 +00:00
is invalid, or
Implement <utmpx.h>. The utmpx interface is the standardized interface of the user accounting database. The standard only defines a subset of the functions that were present in System V-like systems. I'd like to highlight some of the traits my implementation has: - The standard allows the on-disk format to be different than the in-memory representation (struct utmpx). Most operating systems don't do this, but we do. This allows us to keep our ABI more stable, while giving us the opportunity to modify the on-disk format. It also allows us to use a common file format across different architectures (i.e. byte ordering). - Our implementation of pututxline() also updates wtmp and lastlog (now called utx.log and utx.lastlogin). This means the databases are more likely to be in sync. - Care must be taken that our implementation discard any fields that are not applicable. For example, our DEAD_PROCESS records do not hold a TTY name. Just a time stamp, a record identifier and a process identifier. It also guarantees that strings (ut_host, ut_line and ut_user) are null terminated. ut_id is obviously not null terminated, because it's not a string. - The API and its behaviour should be conformant to POSIX, but there may be things that slightly deviate from the standard. This implementation uses separate file descriptors when writing to the log files. It also doesn't use getutxid() to search for a field to overwrite. It uses an allocation strategy similar to getutxid(), but prevents DEAD_PROCESS records from accumulating. Make sure libulog doesn't overwrite the manpages shipped with our C library. Also keep the symbol list in Symbol.map sorted. I'll bump __FreeBSD_version later this evening. I first want to convert everything to <utmpx.h> and get rid of <utmp.h>.
2010-01-13 17:29:55 +00:00
.Fa ut_type
has a value of
.Dv DEAD_PROCESS
and an entry with an identifier with a value equal to the field
.Fa ut_id
Properly styleify utmpx code and document error codes in man page. Submitted by: Garrett Cooper
2011-02-19 11:31:56 +00:00
was not found; the global variable
.Va errno
is set to indicate the error.
Implement <utmpx.h>. The utmpx interface is the standardized interface of the user accounting database. The standard only defines a subset of the functions that were present in System V-like systems. I'd like to highlight some of the traits my implementation has: - The standard allows the on-disk format to be different than the in-memory representation (struct utmpx). Most operating systems don't do this, but we do. This allows us to keep our ABI more stable, while giving us the opportunity to modify the on-disk format. It also allows us to use a common file format across different architectures (i.e. byte ordering). - Our implementation of pututxline() also updates wtmp and lastlog (now called utx.log and utx.lastlogin). This means the databases are more likely to be in sync. - Care must be taken that our implementation discard any fields that are not applicable. For example, our DEAD_PROCESS records do not hold a TTY name. Just a time stamp, a record identifier and a process identifier. It also guarantees that strings (ut_host, ut_line and ut_user) are null terminated. ut_id is obviously not null terminated, because it's not a string. - The API and its behaviour should be conformant to POSIX, but there may be things that slightly deviate from the standard. This implementation uses separate file descriptors when writing to the log files. It also doesn't use getutxid() to search for a field to overwrite. It uses an allocation strategy similar to getutxid(), but prevents DEAD_PROCESS records from accumulating. Make sure libulog doesn't overwrite the manpages shipped with our C library. Also keep the symbol list in Symbol.map sorted. I'll bump __FreeBSD_version later this evening. I first want to convert everything to <utmpx.h> and get rid of <utmp.h>.
2010-01-13 17:29:55 +00:00
.Pp
The
.Fn setutxdb
function returns 0 if the user accounting database was opened
successfully.
Otherwise, -1 is returned and the global variable
.Va errno
is set to indicate the error.
.Sh ERRORS
In addition to the error conditions described in
Fix the manual section number for a cross-reference to open(2) and sort it. Reviewed by: ed MFC after: 3 days
2011-10-27 13:17:42 +00:00
.Xr open 2 ,
Properly styleify utmpx code and document error codes in man page. Submitted by: Garrett Cooper
2011-02-19 11:31:56 +00:00
.Xr fdopen 3 ,
.Xr fopen 3 ,
.Xr fseek 3 ,
the
.Fn pututxline
function can generate the following errors:
.Bl -tag -width Er
.It Bq Er ESRCH
The value of
.Fa ut_type
is DEAD_PROCESS, and the process entry could not be found.
.It Bq Er EINVAL
The value of
.Fa ut_type
is not supported by this implementation.
.El
In addition to the error conditions described in
Implement <utmpx.h>. The utmpx interface is the standardized interface of the user accounting database. The standard only defines a subset of the functions that were present in System V-like systems. I'd like to highlight some of the traits my implementation has: - The standard allows the on-disk format to be different than the in-memory representation (struct utmpx). Most operating systems don't do this, but we do. This allows us to keep our ABI more stable, while giving us the opportunity to modify the on-disk format. It also allows us to use a common file format across different architectures (i.e. byte ordering). - Our implementation of pututxline() also updates wtmp and lastlog (now called utx.log and utx.lastlogin). This means the databases are more likely to be in sync. - Care must be taken that our implementation discard any fields that are not applicable. For example, our DEAD_PROCESS records do not hold a TTY name. Just a time stamp, a record identifier and a process identifier. It also guarantees that strings (ut_host, ut_line and ut_user) are null terminated. ut_id is obviously not null terminated, because it's not a string. - The API and its behaviour should be conformant to POSIX, but there may be things that slightly deviate from the standard. This implementation uses separate file descriptors when writing to the log files. It also doesn't use getutxid() to search for a field to overwrite. It uses an allocation strategy similar to getutxid(), but prevents DEAD_PROCESS records from accumulating. Make sure libulog doesn't overwrite the manpages shipped with our C library. Also keep the symbol list in Symbol.map sorted. I'll bump __FreeBSD_version later this evening. I first want to convert everything to <utmpx.h> and get rid of <utmp.h>.
2010-01-13 17:29:55 +00:00
.Xr fopen 3 ,
the
.Fn setutxdb
function can generate the following errors:
.Bl -tag -width Er
.It Bq Er EINVAL
The
.Fa type
argument contains a value not supported by this implementation.
.It Bq Er EFTYPE
The file format is invalid.
.El
.Sh SEE ALSO
.Xr last 1 ,
.Xr write 1 ,
.Xr getpid 2 ,
.Xr gettimeofday 2 ,
.Xr tty 4 ,
.Xr ac 8 ,
Add a utility, utxrm(8). Most of the ports I broke when I imported utmpx, were simple management utilities for the utmp database, allowing you to add/remove entries manually. Add a small tool called utxrm(8), which allows you to remove an entry from the utmpx database by hand. This is useful when a login daemon crashes or fails to remove the entry during shutdown.
2011-02-19 11:44:04 +00:00
.Xr newsyslog 8 ,
Replace utxrm(8) by utx(8). At first, I added a utility called utxrm(8) to remove stale entries from the user accounting database. It seems there are cases in which we need to perform different operations on the database as well. Simply rename utxrm(8) to utx(8) and place the old code under the "rm" command. In addition to "rm", this tool supports "boot" and "shutdown", which are going to be used by an rc-script which I am going to commit separately.
2012-02-11 20:28:42 +00:00
.Xr utx 8
Implement <utmpx.h>. The utmpx interface is the standardized interface of the user accounting database. The standard only defines a subset of the functions that were present in System V-like systems. I'd like to highlight some of the traits my implementation has: - The standard allows the on-disk format to be different than the in-memory representation (struct utmpx). Most operating systems don't do this, but we do. This allows us to keep our ABI more stable, while giving us the opportunity to modify the on-disk format. It also allows us to use a common file format across different architectures (i.e. byte ordering). - Our implementation of pututxline() also updates wtmp and lastlog (now called utx.log and utx.lastlogin). This means the databases are more likely to be in sync. - Care must be taken that our implementation discard any fields that are not applicable. For example, our DEAD_PROCESS records do not hold a TTY name. Just a time stamp, a record identifier and a process identifier. It also guarantees that strings (ut_host, ut_line and ut_user) are null terminated. ut_id is obviously not null terminated, because it's not a string. - The API and its behaviour should be conformant to POSIX, but there may be things that slightly deviate from the standard. This implementation uses separate file descriptors when writing to the log files. It also doesn't use getutxid() to search for a field to overwrite. It uses an allocation strategy similar to getutxid(), but prevents DEAD_PROCESS records from accumulating. Make sure libulog doesn't overwrite the manpages shipped with our C library. Also keep the symbol list in Symbol.map sorted. I'll bump __FreeBSD_version later this evening. I first want to convert everything to <utmpx.h> and get rid of <utmp.h>.
2010-01-13 17:29:55 +00:00
.Sh STANDARDS
The
.Fn endutxent ,
.Fn getutxent ,
.Fn getutxid ,
Describe why pututxline() doesn't entirely conform to standards.
2010-01-22 05:09:10 +00:00
.Fn getutxline
Implement <utmpx.h>. The utmpx interface is the standardized interface of the user accounting database. The standard only defines a subset of the functions that were present in System V-like systems. I'd like to highlight some of the traits my implementation has: - The standard allows the on-disk format to be different than the in-memory representation (struct utmpx). Most operating systems don't do this, but we do. This allows us to keep our ABI more stable, while giving us the opportunity to modify the on-disk format. It also allows us to use a common file format across different architectures (i.e. byte ordering). - Our implementation of pututxline() also updates wtmp and lastlog (now called utx.log and utx.lastlogin). This means the databases are more likely to be in sync. - Care must be taken that our implementation discard any fields that are not applicable. For example, our DEAD_PROCESS records do not hold a TTY name. Just a time stamp, a record identifier and a process identifier. It also guarantees that strings (ut_host, ut_line and ut_user) are null terminated. ut_id is obviously not null terminated, because it's not a string. - The API and its behaviour should be conformant to POSIX, but there may be things that slightly deviate from the standard. This implementation uses separate file descriptors when writing to the log files. It also doesn't use getutxid() to search for a field to overwrite. It uses an allocation strategy similar to getutxid(), but prevents DEAD_PROCESS records from accumulating. Make sure libulog doesn't overwrite the manpages shipped with our C library. Also keep the symbol list in Symbol.map sorted. I'll bump __FreeBSD_version later this evening. I first want to convert everything to <utmpx.h> and get rid of <utmp.h>.
2010-01-13 17:29:55 +00:00
and
.Fn setutxent
functions are expected to conform to
.St -p1003.1-2008 .
.Pp
The
Describe why pututxline() doesn't entirely conform to standards.
2010-01-22 05:09:10 +00:00
.Fn pututxline
function deviates from the standard by writing its records to multiple
database files, depending on its
.Fa ut_type .
This prevents the need for special utility functions to update the other
databases, such as the
Also add a cross-reference to NetBSD updlastlogx().
2010-02-03 19:31:02 +00:00
.Fn updlastlogx
and
Describe why pututxline() doesn't entirely conform to standards.
2010-01-22 05:09:10 +00:00
.Fn updwtmpx
Also add a cross-reference to NetBSD updlastlogx().
2010-02-03 19:31:02 +00:00
functions which are available in other implementations.
Describe why pututxline() doesn't entirely conform to standards.
2010-01-22 05:09:10 +00:00
It also tries to replace
.Dv DEAD_PROCESS
entries in the active sessions database when storing
.Dv USER_PROCESS
entries and no entry with the same value for
.Fa ut_id
has been found.
The standard always requires a new entry to be allocated, which could
English nitpicking. Submitted by: jmallett
2010-01-22 05:19:51 +00:00
cause an unbounded growth of the database.
Describe why pututxline() doesn't entirely conform to standards.
2010-01-22 05:09:10 +00:00
.Pp
The
Implement <utmpx.h>. The utmpx interface is the standardized interface of the user accounting database. The standard only defines a subset of the functions that were present in System V-like systems. I'd like to highlight some of the traits my implementation has: - The standard allows the on-disk format to be different than the in-memory representation (struct utmpx). Most operating systems don't do this, but we do. This allows us to keep our ABI more stable, while giving us the opportunity to modify the on-disk format. It also allows us to use a common file format across different architectures (i.e. byte ordering). - Our implementation of pututxline() also updates wtmp and lastlog (now called utx.log and utx.lastlogin). This means the databases are more likely to be in sync. - Care must be taken that our implementation discard any fields that are not applicable. For example, our DEAD_PROCESS records do not hold a TTY name. Just a time stamp, a record identifier and a process identifier. It also guarantees that strings (ut_host, ut_line and ut_user) are null terminated. ut_id is obviously not null terminated, because it's not a string. - The API and its behaviour should be conformant to POSIX, but there may be things that slightly deviate from the standard. This implementation uses separate file descriptors when writing to the log files. It also doesn't use getutxid() to search for a field to overwrite. It uses an allocation strategy similar to getutxid(), but prevents DEAD_PROCESS records from accumulating. Make sure libulog doesn't overwrite the manpages shipped with our C library. Also keep the symbol list in Symbol.map sorted. I'll bump __FreeBSD_version later this evening. I first want to convert everything to <utmpx.h> and get rid of <utmp.h>.
2010-01-13 17:29:55 +00:00
.Fn getutxuser
and
.Fn setutxdb
functions,
the
.Fa ut_host
field of the
.Vt utmpx
structure and
.Dv SHUTDOWN_TIME
are extensions.
.Sh HISTORY
These functions appeared in
.Fx 9.0 .
Fix whitespace inconsistencies in libc in files copyrighted by me.
2011-06-26 18:27:17 +00:00
They replaced the
Implement <utmpx.h>. The utmpx interface is the standardized interface of the user accounting database. The standard only defines a subset of the functions that were present in System V-like systems. I'd like to highlight some of the traits my implementation has: - The standard allows the on-disk format to be different than the in-memory representation (struct utmpx). Most operating systems don't do this, but we do. This allows us to keep our ABI more stable, while giving us the opportunity to modify the on-disk format. It also allows us to use a common file format across different architectures (i.e. byte ordering). - Our implementation of pututxline() also updates wtmp and lastlog (now called utx.log and utx.lastlogin). This means the databases are more likely to be in sync. - Care must be taken that our implementation discard any fields that are not applicable. For example, our DEAD_PROCESS records do not hold a TTY name. Just a time stamp, a record identifier and a process identifier. It also guarantees that strings (ut_host, ut_line and ut_user) are null terminated. ut_id is obviously not null terminated, because it's not a string. - The API and its behaviour should be conformant to POSIX, but there may be things that slightly deviate from the standard. This implementation uses separate file descriptors when writing to the log files. It also doesn't use getutxid() to search for a field to overwrite. It uses an allocation strategy similar to getutxid(), but prevents DEAD_PROCESS records from accumulating. Make sure libulog doesn't overwrite the manpages shipped with our C library. Also keep the symbol list in Symbol.map sorted. I'll bump __FreeBSD_version later this evening. I first want to convert everything to <utmpx.h> and get rid of <utmp.h>.
2010-01-13 17:29:55 +00:00
.In utmp.h
interface.
.Sh AUTHORS
Escape "Ed"
2015-04-26 10:29:43 +00:00
.An \&Ed Schouten Aq Mt ed@FreeBSD.org
Reference in New Issue Copy Permalink