'\"! tbl | mmdoc
'\"macro stdmacro
.if n .pH g3c.getut @(#)getut	40.17 of 10/27/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} getut 3C "C Programming Language Utilities" "\&"
.if \nX=1 .ds x} getut 3C "C Programming Language Utilities"
.if \nX=2 .ds x} getut 3C "" "\&"
.if \nX=3 .ds x} getut "" "" "\&"
.TH \*(x}
.SH NAME
\f4getut\f2: \f4getutent\f1, \f4getutid\f1, \f4getutline\f1, \f4pututline\f1, \f4setutent\f1, \f4endutent\f1, \f4utmpname\f1 \- access \f4utmp\f1 file entry
.SH SYNOPSIS
.nf
\f4#include <utmp.h>\f1
.PP
\f4struct utmp \(**getutent (void);\f1
.PP
\f4struct utmp \(**getutid (const struct utmp \(**id);\f1
.PP
\f4struct utmp \(**getutline (const struct utmp \(**line);\f1
.PP
\f4struct utmp \(**pututline (const struct utmp \(**utmp);\f1
.PP
\f4void setutent (void);\f1
.PP
\f4void endutent (void);\f1
.PP
\f4int utmpname (const char \(**file);\f1
.SH DESCRIPTION
\f4getutent\fP,
\f4getutid\fP,
\f4getutline\fP,
and
\f4pututline\fP
each return a pointer to a structure with the following members:
.PP
.RS
.TS
l1 l1 l1 l.
.tr ~ 
	\f4char	ut_user[8];	~~/\(** user login name \(**/
	char	ut_id[4];	~~/\(** /sbin/inittab id (usually line #) \(**/
	char	ut_line[12];	~~/\(** device name (console, lnxx) \(**/
	short	ut_pid;  	~~/\(** process id ~~\(**/
	short	ut_type;	~~/\(** type of entry \(**/
	struct	exit_status {
	} ut_exit;		~~/\(** exit status of a process \(**/
			~~/\(** marked as \s-1DEAD_PROCESS\s+1 \(**/
	time_t	ut_time;	~~/\(** time entry was made \(**/\f1
.TE
.RE
.PP
The structure exit status includes the following members:
.RS
.PP
.TS
l1 l1 l1 l.
.tr ~ 
	\f4~~~~short	~~e_termination;	~~~~~/\(** termination status \(**/
	~~~~short	~~e_exit;	~~~~~/\(** exit status \(**/\f1
.tr ~~
.TE
.RE
.PP
\f4getutent\fP
reads in the next entry from a
\f4utmp\fP-like
file.  If the file is not already open, it opens it.  If
it reaches the end of the file, it fails.
.PP
\f4getutid\fP
searches forward from the current point in the
\f4utmp\fP
file until it
finds an entry with a
.I ut_type\^
matching
\f4id\fP->ut_type\^
if the type specified is
\f4RUN_LVL\f1,
\f4BOOT_TIME\f1,
\f4OLD_TIME\f1,
or
\f4NEW_TIME\f1.
If the type specified in
\f4id\fP
is
\f4INIT_PROCESS\f1,
\f4LOGIN_PROCESS\f1,
\f4USER_PROCESS\f1,
or
\f4DEAD_PROCESS\f1,
then
\f4getutid\fP
will return a pointer to the first entry whose type is one of these
four and whose
\f4ut_id\f1
field matches
\f4id\fP->ut_id .
If the
end of file is reached without a match, it fails.
.PP
\f4getutline\fP
searches forward from the current point in the
\f4utmp\fP
file until it
finds an entry of the type
\f4LOGIN_PROCESS\f1
or
\f4USER_PROCESS\f1
that also has a
.I ut_line\^
string matching the
\f4line\fP->ut_line\^
string.  If the end of file is reached without a match, it fails.
.PP
\f4pututline\fP
writes out the supplied
\f4utmp\fP
structure into the
\f4utmp\fP
file.  It uses
\f4getutid\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
\f4pututline\fP
will have searched for the proper entry using one of the
\f4getut\fP
routines.  If so,
\f4pututline\fP
will not search.  If
\f4pututline\fP
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
\f4utmp\fP
structure.
.PP
\f4setutent\fP
resets the input stream to the beginning of the file.  This
reset should be done before each search for a new entry if
it is desired that the entire file be examined.
.PP
\f4endutent\fP
closes the currently open file.
.PP
\f4utmpname\fP
allows the user to change the name of the file examined, from
\f4/var/adm/utmp\f1
to any other file.  It is most often expected that this other
file will be
\f4/var/adm/wtmp\f1.
If the file does not exist, this will not be apparent until the
first attempt to reference the file is made.
\f4utmpname\fP
does not open the file.  It just closes the old file if it is
currently open and saves the new file name.  If the file name
given is longer than 79 characters,
\f4utmpname\fP
returns 0.  Otherwise, it will return 1.
.SH FILES
\f4/var/adm/utmp\f1
.br
\f4/var/adm/wtmp\f1
.SH SEE ALSO
\f4ttyslot\fP(3C), \f4utmp\fP(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
\f4getutid\fP
or \f4getutline\fP,
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
\f4getutline\fP
to search for multiple occurrences, it would be necessary to zero
out the static area after each success, or
\f4getutline\fP
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
\f4pututline\fP
(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
\f4getutent\fP,
\f4getutid\fP
or
\f4getutline\fP
routines, if the user has just modified those contents and
passed the pointer back to
\f4pututline\fP.
.PP
These routines use buffered standard \s-1I/O\s+1 for input, but
\f4pututline\fP
uses an unbuffered non-standard write to avoid race conditions
between processes trying to modify the
\f4utmp\fP
and
\f4wtmp\fP
files.
.\"	@(#)getut.3c	6.2 of 10/20/83
.Ee
