nightly: remove unused BINARCHIVE

[unleashed.git] / share / man / man3c / getutxent.3c

'\" te
.\" Copyright 1989 AT&T.  Copyright (c) 2004 Sun Microsystems, Inc.  All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH GETUTXENT 3C "Nov 21, 2014"
.SH NAME
getutxent, getutxid, getutxline, pututxline, setutxent, endutxent, utmpxname,
getutmp, getutmpx, updwtmp, updwtmpx \- user accounting database functions
.SH SYNOPSIS
.LP
.nf
#include <utmpx.h>

\fBstruct utmpx *\fR\fBgetutxent\fR(\fBvoid\fR);
.fi

.LP
.nf
\fBstruct utmpx *\fR\fBgetutxid\fR(\fBconst struct utmpx *\fR\fIid\fR);
.fi

.LP
.nf
\fBstruct utmpx *\fR\fBgetutxline\fR(\fBconst struct utmpx *\fR\fIline\fR);
.fi

.LP
.nf
\fBstruct utmpx *\fR\fBpututxline\fR(\fBconst struct utmpx *\fR\fIutmpx\fR);
.fi

.LP
.nf
\fBvoid\fR \fBsetutxent\fR(\fBvoid\fR);
.fi

.LP
.nf
\fBvoid\fR \fBendutxent\fR(\fBvoid\fR);
.fi

.LP
.nf
\fBint\fR \fButmpxname\fR(\fBconst char *\fR\fIfile\fR);
.fi

.LP
.nf
\fBvoid\fR \fBgetutmp\fR(\fBstruct utmpx *\fR\fIutmpx\fR, \fBstruct utmp *\fR\fIutmp\fR);
.fi

.LP
.nf
\fBvoid\fR \fBgetutmpx\fR(\fBstruct utmp *\fR\fIutmp\fR, \fBstruct utmpx *\fR\fIutmpx\fR);
.fi

.LP
.nf
\fBvoid\fR \fBupdwtmp\fR(\fBchar *\fR\fIwfile\fR, \fBstruct utmp *\fR\fIutmp\fR);
.fi

.LP
.nf
\fBvoid\fR \fBupdwtmpx\fR(\fBchar *\fR\fIwfilex\fR, \fBstruct utmpx *\fR\fIutmpx\fR);
.fi

.SH DESCRIPTION
.LP
These functions provide access to the user accounting database, \fButmpx\fR
(see \fButmpx\fR(4)). Entries in the database are described by the definitions
and data structures in \fB<utmpx.h>\fR\&.
.sp
.LP
The \fButmpx\fR structure contains the following members:
.sp
.in +2
.nf
char                 ut_user[32];   /* user login name */
char                 ut_id[4];      /* /etc/inittab id */
                                    /* (usually line #) */
char                 ut_line[32];   /* device name */
                                    /* (console, lnxx) */
pid_t                ut_pid;        /* process id */
short                ut_type;       /* type of entry */
struct exit_status   ut_exit;       /* exit status of a process */
                                    /* marked as DEAD_PROCESS */
struct timeval       ut_tv;         /* time entry was made */
int                  ut_session;    /* session ID, used for */
                                    /* windowing */
short                ut_syslen;     /* significant length of */
                                    /* ut_host */
                                    /* including terminating null */
char                 ut_host[257];  /* host name, if remote */
.fi
.in -2

.sp
.LP
The \fBexit_status\fR structure includes the following members:
.sp
.in +2
.nf
short   e_termination;   /* termination status */
short   e_exit;          /* exit status */
.fi
.in -2

.SS "\fBgetutxent()\fR"
.LP
The \fBgetutxent()\fR function reads in the next entry from a \fButmpx\fR
database. If the database is not already open, it opens it. If it reaches the
end of the database, it fails.
.SS "\fBgetutxid()\fR"
.LP
The \fBgetutxid()\fR function searches forward from the current point in the
\fButmpx\fR database until it finds an entry with a \fBut_type\fR matching
\fIid\fR->\fBut_type\fR, if the type specified is \fBRUN_LVL\fR,
\fBBOOT_TIME\fR, \fBDOWN_TIME\fR, \fBOLD_TIME\fR, or \fBNEW_TIME\fR. If the
type specified in \fIid\fR is \fBINIT_PROCESS\fR, \fBLOGIN_PROCESS\fR,
\fBUSER_PROCESS\fR, or \fBDEAD_PROCESS\fR, then \fBgetutxid()\fR will return a
pointer to the first entry whose type is one of these four and whose
\fBut_id\fR member matches \fIid\fR->\fBut_id\fR. If the end of database is
reached without a match, it fails.
.SS "\fBgetutxline()\fR"
.LP
The \fBgetutxline()\fR function searches forward from the current point in the
\fButmpx\fR database until it finds an entry of the type \fBLOGIN_PROCESS\fR or
\fBUSER_PROCESS\fR which also has a \fIut_line\fR string matching the
\fIline\fR->\fBut_line\fR string.  If the end of the database is reached
without a match, it fails.
.SS "\fBpututxline()\fR"
.LP
The \fBpututxline()\fR function writes the supplied \fButmpx\fR structure into
the \fButmpx\fR database.  It uses \fBgetutxid()\fR to search forward for the
proper place if it finds that it is not already at the proper place.  It is
expected that normally the user of \fBpututxline()\fR will have searched for
the proper entry using one of the \fBgetutx()\fR routines.  If so,
\fBpututxline()\fR will not search.  If \fBpututxline()\fR does not find a
matching slot for the new entry, it will add a new entry to the end of the
database.  It returns a pointer to the  \fButmpx\fR structure. When called by a
non-root user, \fBpututxline()\fR invokes a \fBsetuid()\fR root program to
verify and write the entry, since the \fButmpx\fR database is normally writable
only by root.  In this event, the \fBut_name\fR member must correspond to the
actual user name associated with the process; the  \fBut_type\fR member must be
either \fBUSER_PROCESS\fR or \fBDEAD_PROCESS\fR; and the \fBut_line\fR member
must be a device special file and be writable by the user.
.SS "\fBsetutxent()\fR"
.LP
The \fBsetutxent()\fR function resets the input stream to the beginning. This
should be done before each search for a new entry if it is desired that the
entire database be examined.
.SS "\fBendutxent()\fR"
.LP
The \fBendutxent()\fR function closes the currently open database.
.SS "\fButmpxname()\fR"
.LP
The \fButmpxname()\fR function allows the user to change the name of the
database file examined from \fB/var/adm/utmpx\fR to any other file, most often
\fB/var/adm/wtmpx\fR. If the file does not exist, this will not be apparent
until the first attempt to reference the file is made.  The \fButmpxname()\fR
function does not open the file, but closes the old file if it is currently
open and saves the new file name. The new file name must end with the "x"
character to allow the name of the corresponding \fButmp\fR file to be easily
obtainable.; otherwise, an error value of \fB0\fR is returned. The function
returns \fB1\fR on success.
.SS "\fBgetutmp()\fR"
.LP
The \fBgetutmp()\fR function copies the information stored in the members of
the \fButmpx\fR structure to the corresponding members of the \fButmp\fR
structure. If the information in any member of  \fButmpx\fR does not fit in the
corresponding \fButmp\fR member, the data is silently truncated. (See
\fBgetutent\fR(3C) for  \fButmp\fR structure)
.SS "\fBgetutmpx()\fR"
.LP
The \fBgetutmpx()\fR function copies the information stored in the members of
the \fButmp\fR structure to the corresponding members of the \fButmpx\fR
structure. (See \fBgetutent\fR(3C) for  \fButmp\fR structure)
.SS "\fBupdwtmp()\fR"
.LP
The \fBupdwtmp()\fR function can be used in two ways.
.sp
.LP
If \fIwfile\fR is \fB/var/adm/wtmp\fR, the \fButmp\fR format record supplied by
the caller is converted to a \fButmpx \fRformat record and the
\fB/var/adm/wtmpx\fR file is updated (because the \fB/var/adm/wtmp\fR file no
longer exists, operations on \fBwtmp\fR are converted to operations on
\fBwtmpx\fR by the library functions.
.sp
.LP
If \fIwfile\fR is a file other than \fB/var/adm/wtmp\fR, it is assumed to be an
old file in \fButmp\fR format and is updated directly with the \fButmp\fR
format record supplied by the caller.
.SS "\fBupdwtmpx()\fR"
.LP
The \fBupdwtmpx()\fR function writes the contents of the \fButmpx\fR structure
pointed to by \fIutmpx\fR to the database.
.SS "\fButmpx\fR structure"
.LP
The values of the \fBe_termination\fR and \fBe_exit\fR members of the
\fBut_exit\fR structure are valid only for records of type \fBDEAD_PROCESS\fR.
For \fButmpx\fR entries created by \fBinit\fR(8),  these values are set
according to the result of the \fBwait()\fR call that \fBinit\fR performs on
the process when the process exits. See the \fBwait\fR(3C), manual page for the
values \fBinit\fR uses. Applications creating \fButmpx\fR entries can set
\fBut_exit\fR values using the following code example:
.sp
.in +2
.nf
u->ut_exit.e_termination = WTERMSIG(process->p_exit)
u->ut_exit.e_exit = WEXITSTATUS(process->p_exit)
.fi
.in -2

.sp
.LP
See \fBwait.h\fR(3HEAD) for descriptions of the \fBWTERMSIG\fR and
\fBWEXITSTATUS\fR macros.
.sp
.LP
The \fBut_session\fR member is not acted upon by the operating system. It is
used by applications interested in creating \fButmpx\fR entries.
.sp
.LP
For records of type \fBUSER_PROCESS\fR, the \fBnonuserx()\fR macro uses
value of the \fBut_exit.e_exit\fR member to mark \fButmpx\fR entries as real
logins (as opposed to multiple xterms started by the same user on a window
system). This allows the system utilities that display users to obtain an
accurate indication of the number of actual users, while still permitting each
\fBpty\fR to have a \fButmpx\fR record (as most applications expect). The
\fBNONROOT_USRX\fR macro defines the value that \fBlogin\fR places in the
\fBut_exit.e_exit\fR member.
.SH RETURN VALUES
.LP
Upon successful completion, \fBgetutxent()\fR, \fBgetutxid()\fR, and
\fBgetutxline()\fR each return a pointer to a \fButmpx\fR structure containing
a copy of the requested entry in the user accounting database.  Otherwise a
null pointer is returned.
.sp
.LP
The return value may point to a static area which is overwritten by a
subsequent call to \fBgetutxid ()\fR or \fBgetutxline()\fR.
.sp
.LP
Upon successful completion, \fBpututxline()\fR returns a pointer to a
\fButmpx\fR structure containing a copy of the entry added to the user
accounting database.  Otherwise a null pointer is returned.
.sp
.LP
The \fBendutxent()\fR and \fBsetutxent()\fR functions return no value.
.sp
.LP
A null pointer is returned upon failure to read, whether for permissions or
having reached the end of file, or upon failure to write.
.SH USAGE
.LP
These functions use buffered standard I/O for input, but \fBpututxline()\fR
uses an unbuffered write to avoid race conditions between processes trying to
modify the \fButmpx\fR and \fBwtmpx\fR files.
.sp
.LP
Applications should not access the \fButmpx\fR and \fBwtmpx\fR databases
directly, but should use these functions to ensure that these databases are
maintained consistently.
.SH FILES
.ne 2
.na
\fB\fB/var/adm/utmpx\fR\fR
.ad
.RS 18n
user access and accounting information
.RE

.sp
.ne 2
.na
\fB\fB/var/adm/wtmpx\fR\fR
.ad
.RS 18n
history of user access and accounting information
.RE

.SH ATTRIBUTES
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE  ATTRIBUTE VALUE
_
Interface Stability     See below.
_
MT-Level        Unsafe
.TE

.sp
.LP
The \fBendutxent()\fR, \fBgetutxent()\fR, \fBgetutxid()\fR, \fBgetutxline()\fR,
\fBpututxline()\fR, and \fBsetutxent()\fR functions are Standard.
.SH SEE ALSO
.LP
\fBgetutent\fR(3C), \fBttyslot\fR(3C), \fBwait\fR(3C), \fBwait.h\fR(3HEAD),
\fButmpx\fR(4), \fBattributes\fR(5), \fBstandards\fR(5)
.SH NOTES
.LP
The most current entry is saved in a static structure.  Multiple accesses
require that it be copied before further accesses are made. On each call to
either \fBgetutxid()\fR or \fBgetutxline()\fR, the routine examines the static
structure before performing more I/O. If the contents of the static structure
match what it is searching for, it looks no further. For this reason, to use
\fBgetutxline()\fR to search for multiple occurrences it would be necessary to
zero out the static after each success, or \fBgetutxline()\fR would just return
the same structure over and over again. There is one exception to the rule
about emptying the structure before further reads are done.  The implicit read
done by \fBpututxline()\fR (if it finds that it is not already at the correct
place in the file) will not hurt the contents of the static structure returned
by the \fBgetutxent()\fR, \fBgetutxid()\fR, or \fBgetutxline()\fR routines, if
the user has just modified those contents and passed the pointer back to
\fBpututxline()\fR.