'\"macro stdmacro
.if n .pH g3c.getutx @(#)getutx	40.7 of 10/27/89
.\" Copyright 1989 AT&T
'\"! tbl | mmdoc
'\"macro stdmacro
.if n .pH g3c.getutx @(#)getut	31.1 of 4/5/88
.nr X
.if \nX=0 .ds x} getutx 3C "C Programming Language Utilities" "\&"
.if \nX=1 .ds x} getutx 3C "C Programming Language Utilities"
.if \nX=2 .ds x} getutx 3C "" "\&"
.if \nX=3 .ds x} getutx "" "" "\&"
.TH \*(x}
.SH NAME
getutx: \f4getutxent, getutxid, getutxline, pututxline, setutxent, endutxent, utmpxname, getutmp, getutmpx, updwtmp, updwtmpx\f1 \- access \f4utmpx\f1 file entry
.SH SYNOPSIS
.nf
\f4#include <utmpx.h>\f1
.PP
\f4struct utmpx \(**getutxent (void);\f1
.PP
\f4struct utmpx \(**getutxid (const struct utmpx \(**id);\f1
.PP
\f4struct utmpx \(**getutxline (const struct utmpx \(**line);\f1
.PP
\f4struct utmpx \(**pututxline (const struct utmpx \(**utmpx);\f1
.PP
\f4void setutxent (void);\f1
.PP
\f4void endutxent (void);\f1
.PP
\f4int utmpxname (const char \(**file);\f1
.PP
\f4void getutmp (struct utmpx \(**utmpx, struct utmp \(**utmp);\f1
.PP
\f4void getutmpx (struct utmp \(**utmp, struct utmpx \(**utmpx);\f1
.PP
\f4void updwtmp (char \(**wfile, struct utmp \(**utmp);\f1
.PP
\f4void updwtmpx (char \(**wfilex, struct utmpx \(**utmpx);\f1
.PP
.SH DESCRIPTION
\f4getutxent\f1, \f4getutxid\f1, and \f4getutxline\f1
each return a pointer to a structure of the following type:
.PP
.RS
.nf
\f4struct     utmpx {
     char     ut_user[32];  /\(** user login name \(**/
     char     ut_id[4];     /\(** /sbin/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 {
         short     e_termination; /\(** termination status \(**/
         short     e_exit;        /\(** exit status \(**/
     } ut_exit;    /\(** exit status of a process
                   /\(** marked as \s-1DEAD_PROCESS\s+1 \(**/
     struct timeval     ut_tv;     /\(** time entry was made \(**/
     short ut_syslen;     /\(** significant length of ut_host \(**/
                          /\(** including terminating null \(**/
     char     ut_host[257];     /\(** host name, if remote \(**/\f1
};
.fi
.RE
.PP
\f4getutxent\f1
reads in the next entry from a
\f4utmpx\f1-like file.
If the file is not already open, it opens it.
If it reaches the end of the file, it fails.
.PP
\f4getutxid\f1
searches forward from the current point in the
\f4utmpx\f1
file until it
finds an entry with a
\f4ut_type\f1
matching
\f2id\->\f4ut_type\f1
if the type specified is
\f4RUN_LVL,\f1
\f4BOOT_TIME,\f1
\f4OLD_TIME\f1,
or
\f4NEW_TIME.\f1
If the type specified in
\f2id\fP
is
\f4INIT_PROCESS,\f1
\f4LOGIN_PROCESS,\f1
\f4USER_PROCESS\f1,
or
\f4DEAD_PROCESS\f1,
then
\f4getutxid\f1
will return a pointer to the first entry whose type is one of these
four and whose
\f2ut_id\f1
field matches
\f2id\->\f4ut_id\f1.
If the
end of file is reached without a match, it fails.
.br
.ne 5
.PP
\f4getutxline\f1
searches forward from the current point in the
\f4utmpx\f1
file until it
finds an entry of the type
\f4LOGIN_PROCESS\f1
or
\f4USER_PROCESS\f1
which also has a
\f2ut_line\fP
string matching the
\f2line\->\f4ut_line\f1
string.  If the end of file is reached without a match, it fails.
.PP
\f4pututxline\f1
writes out the supplied
\f4utmpx\f1
structure into the
\f4utmpx\f1
file.  It uses
\f4getutxid\^\fP
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
\f4pututxline\f1
will have searched for the proper entry using one of the
\f4getutx\f1
routines.  If so,
\f4pututxline\f1
will not search.  If
\f4pututxline\f1
does not find a matching slot for the new entry, it will add
a new entry to the end of the file.  It returns a pointer to the 
\f4utmpx\f1
structure.
.PP
\f4setutxent\f1
resets the input stream to the beginning of the file.  This should
be done before each search for a new entry if it is desired that
the entire file be examined.
.PP
\f4endutxent\f1
closes the currently open file.
.PP
\f4utmpxname\f1
allows the user to change the name of the file examined, from
\f4/var/adm/utmpx\f1
to any other file.  It is most often expected that this other
file will be
\f4/var/adm/wtmpx\f1.
If the file does not exist, this will not be apparent until the
first attempt to reference the file is made.
\f4utmpxname\f1
does not open the file.  It just closes the old file if it is
currently open and saves the new file name.
The new file name must end with the ``\f4x\f1'' character to allow
the name of the corresponding \f4utmp\f1 file to be easily obtainable
(otherwise an error code of 1 is returned).
.PP
\f4getutmp\f1
copies the information stored in the fields of the
\f4utmpx\f1
structure to the corresponding fields of the
\f4utmp\f1
structure. If the information in any field of 
\f4utmpx\f1
does not fit in the
corresponding 
\f4utmp \f1
field, the data is truncated.
.PP
\f4getutmpx\f1
copies the information stored in the fields of the
\f4utmp\f1
structure to the corresponding fields of the
\f4utmpx\f1
structure.
.PP
\f4updwtmp\f1
checks the existence of
\f2wfile\f1
and its parallel file, whose name is obtained by appending an ``\f4x\f1'' to
\f2wfile\f1.
If only one of them exists, the second one is created and initialized
to reflect the state of the existing file. 
\f2utmp\f1
is written to 
\f2wfile\f1
and the corresponding 
\f4utmpx\f1
structure is written to the parallel file.
.PP
\f4updwtmpx\f1
checks the existence of
\f2wfilex\f1
and its parallel file, whose name is obtained by truncating the final ``\f4x\f1''
from
\f2wfilex.\f1
If only one of them exists, the second one is created and initialized
to reflect the state of the existing file. 
\f2utmpx\f1
is written to 
\f2wfilex\f1,
and the corresponding 
\f4utmp\f1
structure is written to the parallel file.
.SH FILES
\f4/var/adm/utmp\f1, \f4/var/adm/utmpx\f1
.br
\f4/var/adm/wtmp\f1, \f4/var/adm/wtmpx\f1
.SH SEE ALSO
\f4ttyslot\f1(3C), \f4utmp\f1(4), \f4utmpx\f1(4).
.SH DIAGNOSTICS
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 NOTES
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
\f4getutxid\f1
or
\f4getutxline\f1, the routine examines the static structure before
performing more \s-1I/O\s+1.
If the contents of the static structure match
what it is searching for, it looks no further.  For this reason,
to use
\f4getutxline\f1
to search for multiple occurrences it would be necessary to zero
out the static after each success, or
\f4getutxline\f1
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
\f4pututxline\f1
(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
\f4getutxent\f1,
\f4getutxid\f1,
or
\f4getutxline\f1
routines, if the user has just modified those contents and
passed the pointer back to
\f4pututxline\f1.
.PP
These routines use buffered standard \s-1I/O\s+1 for input, but
\f4pututxline\f1
uses an unbuffered write to avoid race conditions
between processes trying to modify the
\f4utmpx\f1
and
\f4wtmpx\f1
files.
.\"	@(#)getut.3c	6.2 of 10/20/83
.Ee
