.TH getutid() "" "" "General Function (libc)"
.PC "Find a record in login logging file by login identifier"
.B "#include <utmp.h>
\fBstruct utmp *getutid(\fIid\^\fB)\fR
\fBstruct utmp *\fBid\^\fB;\fR
.PP
.II utmp
Function
.B getutid()
searches a login file for a record with a given type, or for a user with
a given login identifier.
.PP
.I id
is the address of an object type
.BR utmp ,
which is a structure whose fields describe a login event.
(For a detailed description of this structure, see the Lexicon entry for
.BR utmp.h ).
Before you call
.BR getutid() ,
initialize
.IR id 's
fields as follows:
.IP \(bu 0.3i
Set field \fIid\fB.ut_type\fR
to the type of record you wish to retrieve.
The type can be one of the following:
.DS
.ta 0.5i 2.0i
	\fBEMPTY\fR	An empty entry
	\fBRUN_LVL\fR	Run level
	\fBBOOT_TIME\fR	Boot time
	\fBOLD_TIME\fR	
	\fBNEW_TIME\fR	
	\fBINIT_PROCESS\fR	Process spawned by \fBinit\fR
	\fBLOGIN_PROCESS\fR	A \fBgetty\fR waiting for a login
	\fBUSER_PROCESS\fR	A user process
	\fBDEAD_PROCESS\fR	
	\fBACCOUNTING\fR	
.DE
.IP \(bu
If you initialize field \fIid\fB.ut_type\fR
to
.BR INIT_PROCESS ,
.BR LOGIN_PROCESS ,
.BR USER_PROCESS ,
or
.BR DEAD_PROCESS ,
initialize field \fIid\fB.ut_id\fR
to the identifier of the user whose login event you are seeking.
Note that this must be the identifier as set by
.BR /etc/init ,
.I not
the login identifier that the user types to log into your system.
.PP
If you initialize field
.B ut_type
to
.BR INIT_PROCESS ,
.BR LOGIN_PROCESS ,
.BR USER_PROCESS ,
or
.BR DEAD_PROCESS ,
.B getutid()
seeks the first record that matches both the type and the identifier
that you set in
.BR id .
If you initialize field
.B ut_type
to any other type, it seeks the first record that matches the type you
requested.
.PP
If it finds a record that matches your request,
.B getutid()
copies it into a static portion of memory and returns the address of that
memory.
It returns NULL if it fails to find a record of the type you requested,
or if it cannot open the login file.
.PP
By default,
.B getutid()
reads records from
.BR /etc/utmp .
If you wish to read records from another file, call
.B utmpname()
before you call
.BR getutid() .
.SH "See Also"
.Xr "libc," libc
.Xr "utmp.h" utmp.h
