mirror of https://github.com/mkerrisk/man-pages
244 lines
6.8 KiB
Groff
244 lines
6.8 KiB
Groff
.\" Copyright 1995 Mark D. Roth (roth@uiuc.edu)
|
|
.\"
|
|
.\" This is free documentation; you can redistribute it and/or
|
|
.\" modify it under the terms of the GNU General Public License as
|
|
.\" published by the Free Software Foundation; either version 2 of
|
|
.\" the License, or (at your option) any later version.
|
|
.\"
|
|
.\" The GNU General Public License's references to "object code"
|
|
.\" and "executables" are to be interpreted as the output of any
|
|
.\" document formatting or typesetting system, including
|
|
.\" intermediate and printed output.
|
|
.\"
|
|
.\" This manual is distributed in the hope that it will be useful,
|
|
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
.\" GNU General Public License for more details.
|
|
.\"
|
|
.\" You should have received a copy of the GNU General Public
|
|
.\" License along with this manual; if not, write to the Free
|
|
.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
|
|
.\" USA.
|
|
.\"
|
|
.\" References consulted:
|
|
.\" Linux libc source code
|
|
.\" Solaris manpages
|
|
.\"
|
|
.\" Modified Thu Jul 25 14:43:46 MET DST 1996 by Michael Haardt <michael@cantor.informatik.rwth-aachen.de>
|
|
.\"
|
|
.TH GETUTENT 3 1996-07-25 "" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
getutent, getutid, getutline, pututline, setutent, endutent, utmpname \- access utmp file entries
|
|
.SH SYNOPSIS
|
|
.B #include <utmp.h>
|
|
.sp
|
|
.B struct utmp *getutent(void);
|
|
.br
|
|
.BI "struct utmp *getutid(struct utmp *" ut );
|
|
.br
|
|
.BI "struct utmp *getutline(struct utmp *" ut );
|
|
.sp
|
|
.BI "struct utmp *pututline(struct utmp *" ut );
|
|
.sp
|
|
.B void setutent(void);
|
|
.br
|
|
.B void endutent(void);
|
|
.sp
|
|
.BI "void utmpname(const char *" file );
|
|
.SH DESCRIPTION
|
|
.BR utmpname ()
|
|
sets the name of the utmp-format file for the other utmp
|
|
functions to access.
|
|
If
|
|
.BR utmpname ()
|
|
is not used to set the filename
|
|
before the other functions are used, they assume \fB_PATH_UTMP\fP, as
|
|
defined in \fI<paths.h>\fP.
|
|
.PP
|
|
.BR setutent ()
|
|
rewinds the file pointer to the beginning of the utmp file.
|
|
It is generally a good idea to call it before any of the other
|
|
functions.
|
|
.PP
|
|
.BR endutent ()
|
|
closes the utmp file.
|
|
It should be called when the user
|
|
code is done accessing the file with the other functions.
|
|
.PP
|
|
.BR getutent ()
|
|
reads a line from the current file position in the utmp file.
|
|
It returns a pointer to a structure containing the fields of
|
|
the line.
|
|
.PP
|
|
.BR getutid ()
|
|
searches forward from the current file position in the utmp
|
|
file based upon \fIut\fP.
|
|
If \fIut\->ut_type\fP is one of \fBRUN_LVL\fP,
|
|
\fBBOOT_TIME\fP, \fBNEW_TIME\fP, or \fBOLD_TIME\fP,
|
|
.BR getutid ()
|
|
will
|
|
find the first entry whose \fIut_type\fP field matches \fIut\->ut_type\fP.
|
|
If \fIut\->ut_type\fP is one of \fBINIT_PROCESS\fP, \fBLOGIN_PROCESS\fP,
|
|
\fBUSER_PROCESS\fP, or \fBDEAD_PROCESS\fP,
|
|
.BR getutid ()
|
|
will find the
|
|
first entry whose
|
|
.I ut_id
|
|
field matches \fIut\->ut_id\fP.
|
|
.PP
|
|
.BR getutline ()
|
|
searches forward from the current file position in the utmp file.
|
|
It scans entries whose
|
|
.I ut_type
|
|
is \fBUSER_PROCESS\fP
|
|
or \fBLOGIN_PROCESS\fP and returns the first one whose
|
|
.I ut_line
|
|
field
|
|
matches \fIut\->ut_line\fP.
|
|
.PP
|
|
.BR pututline ()
|
|
writes the
|
|
.I utmp
|
|
structure \fIut\fP into the utmp file.
|
|
It uses
|
|
.BR getutid ()
|
|
to search for the proper place in the file to insert
|
|
the new entry.
|
|
If it cannot find an appropriate slot for \fIut\fP,
|
|
.BR pututline ()
|
|
will append the new entry to the end of the file.
|
|
.SH "RETURN VALUE"
|
|
.BR getutent (),
|
|
.BR getutid (),
|
|
.BR getutline ()
|
|
and
|
|
.BR pututline ()
|
|
return a pointer to a \fIstruct utmp\fP on success, and NULL on failure.
|
|
This \fIstruct utmp\fP is allocated in static storage, and may be
|
|
overwritten by subsequent calls.
|
|
.SH FILES
|
|
/var/run/utmp database of currently logged-in users
|
|
.br
|
|
/var/log/wtmp database of past user logins
|
|
.SH "CONFORMING TO"
|
|
XPG2, SVr4.
|
|
.LP
|
|
In XPG2 and SVID 2 the function
|
|
.BR pututline ()
|
|
is documented to return void, and that is what it does on many systems
|
|
(AIX, HP-UX, Linux libc5).
|
|
HP-UX introduces a new function
|
|
.BR _pututline ()
|
|
with the prototype given above for
|
|
.BR pututline ()
|
|
(also found in Linux libc5).
|
|
.LP
|
|
All these functions are obsolete now on non-Linux systems.
|
|
POSIX.1-2001, following SUSv1,
|
|
does not have any of these functions, but instead uses
|
|
.sp
|
|
.B #include <utmpx.h>
|
|
.sp
|
|
.B struct utmpx *getutxent(void);
|
|
.br
|
|
.B struct utmpx *getutxid(const struct utmpx *);
|
|
.br
|
|
.B struct utmpx *getutxline(const struct utmpx *);
|
|
.br
|
|
.B struct utmpx *pututxline(const struct utmpx *);
|
|
.br
|
|
.B void setutxent(void);
|
|
.br
|
|
.B void endutxent(void);
|
|
.sp
|
|
The \fIutmpx\fP structure is a superset of the \fIutmp\fP structure,
|
|
with additional fields, and larger versions of the existing fields.
|
|
The corresponding files are often
|
|
.I /var/*/utmpx
|
|
and
|
|
.IR /var/*/wtmpx .
|
|
.LP
|
|
Linux glibc on the other hand does not use \fIutmpx\fP since its
|
|
\fIutmp\fP structure is already large enough.
|
|
The functions \fIgetutxent\fP
|
|
etc. are aliases for \fIgetutent\fP etc.
|
|
.SH NOTES
|
|
.SS Glibc Notes
|
|
The above functions are not thread-safe.
|
|
Glibc adds reentrant versions
|
|
.sp
|
|
.nf
|
|
.BR "#define _GNU_SOURCE" " /* or _SVID_SOURCE or _BSD_SOURCE */"
|
|
.B #include <utmp.h>
|
|
.sp
|
|
.BI "int getutent_r(struct utmp *" ubuf ", struct utmp **" ubufp );
|
|
.sp
|
|
.BI "int getutid_r(struct utmp *" ut ,
|
|
.BI " struct utmp *" ubuf ", struct utmp **" ubufp );
|
|
.sp
|
|
.BI "int getutline_r(struct utmp *" ut ,
|
|
.BI " struct utmp *" ubuf ", struct utmp **" ubufp );
|
|
.fi
|
|
.sp
|
|
These functions are GNU extensions, analogs of the functions of the
|
|
same name without the _r suffix.
|
|
The
|
|
.I ubuf
|
|
parameter gives these functions a place to store their result.
|
|
On success they return 0, and a pointer to the result is written in
|
|
.IR *ubufp .
|
|
On error these functions return \-1.
|
|
.SH EXAMPLE
|
|
The following example adds and removes a utmp record, assuming it is run
|
|
from within a pseudo terminal.
|
|
For usage in a real application, you
|
|
should check the return values of
|
|
.BR getpwuid (3)
|
|
and
|
|
.BR ttyname (3).
|
|
.PP
|
|
.nf
|
|
#include <string.h>
|
|
#include <stdlib.h>
|
|
#include <pwd.h>
|
|
#include <unistd.h>
|
|
#include <utmp.h>
|
|
|
|
int
|
|
main(int argc, char *argv[])
|
|
{
|
|
struct utmp entry;
|
|
|
|
system("echo before adding entry:;who");
|
|
|
|
entry.ut_type = USER_PROCESS;
|
|
entry.ut_pid = getpid();
|
|
strcpy(entry.ut_line, ttyname(STDIN_FILENO) + strlen("/dev/"));
|
|
/* only correct for ptys named /dev/tty[pqr][0\-9a\-z] */
|
|
strcpy(entry.ut_id, ttyname(STDIN_FILENO) + strlen("/dev/tty"));
|
|
time(&entry.ut_time);
|
|
strcpy(entry.ut_user, getpwuid(getuid())\->pw_name);
|
|
memset(entry.ut_host, 0, UT_HOSTSIZE);
|
|
entry.ut_addr = 0;
|
|
setutent();
|
|
pututline(&entry);
|
|
|
|
system("echo after adding entry:;who");
|
|
|
|
entry.ut_type = DEAD_PROCESS;
|
|
memset(entry.ut_line, 0, UT_LINESIZE);
|
|
entry.ut_time = 0;
|
|
memset(entry.ut_user, 0, UT_NAMESIZE);
|
|
setutent();
|
|
pututline(&entry);
|
|
|
|
system("echo after removing entry:;who");
|
|
|
|
endutent();
|
|
exit(EXIT_SUCCESS);
|
|
}
|
|
.fi
|
|
.SH "SEE ALSO"
|
|
.BR utmp (5),
|
|
.BR feature_test_macros (7)
|