mirror of https://github.com/mkerrisk/man-pages
357 lines
9.0 KiB
Groff
357 lines
9.0 KiB
Groff
.\" Copyright 1995 Mark D. Roth (roth@uiuc.edu)
|
|
.\"
|
|
.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
|
|
.\" 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, see
|
|
.\" <http://www.gnu.org/licenses/>.
|
|
.\" %%%LICENSE_END
|
|
.\"
|
|
.\" 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 2021-03-22 "" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
getutent, getutid, getutline, pututline, setutent, endutent,
|
|
utmpname \- access utmp file entries
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <utmp.h>
|
|
.PP
|
|
.B struct utmp *getutent(void);
|
|
.BI "struct utmp *getutid(const struct utmp *" ut );
|
|
.BI "struct utmp *getutline(const struct utmp *" ut );
|
|
.PP
|
|
.BI "struct utmp *pututline(const struct utmp *" ut );
|
|
.PP
|
|
.B void setutent(void);
|
|
.B void endutent(void);
|
|
.PP
|
|
.BI "int utmpname(const char *" file );
|
|
.fi
|
|
.SH DESCRIPTION
|
|
New applications should use the POSIX.1-specified "utmpx" versions of
|
|
these functions; see CONFORMING TO.
|
|
.PP
|
|
.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.
|
|
The definition of this structure is shown in
|
|
.BR utmp (5).
|
|
.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 (),
|
|
and
|
|
.BR getutline ()
|
|
return a pointer to a \fIstruct utmp\fP on success,
|
|
and NULL on failure (which includes the "record not found" case).
|
|
This \fIstruct utmp\fP is allocated in static storage, and may be
|
|
overwritten by subsequent calls.
|
|
.PP
|
|
On success
|
|
.BR pututline ()
|
|
returns
|
|
.IR ut ;
|
|
on failure, it returns NULL.
|
|
.PP
|
|
.BR utmpname ()
|
|
returns 0 if the new name was successfully stored, or \-1 on failure.
|
|
.PP
|
|
On failure, these functions
|
|
.I errno
|
|
set to indicate the error.
|
|
.SH ERRORS
|
|
.TP
|
|
.B ENOMEM
|
|
Out of memory.
|
|
.TP
|
|
.B ESRCH
|
|
Record not found.
|
|
.PP
|
|
.BR setutent (),
|
|
.BR pututline (),
|
|
and the
|
|
.BR getut* ()
|
|
functions can also fail for the reasons described in
|
|
.BR open (2).
|
|
.SH FILES
|
|
.TP
|
|
.I /var/run/utmp
|
|
database of currently logged-in users
|
|
.TP
|
|
.I /var/log/wtmp
|
|
database of past user logins
|
|
.SH ATTRIBUTES
|
|
For an explanation of the terms used in this section, see
|
|
.BR attributes (7).
|
|
.ad l
|
|
.nh
|
|
.TS
|
|
allbox;
|
|
lb lb lbx
|
|
l l l.
|
|
Interface Attribute Value
|
|
T{
|
|
.BR getutent ()
|
|
T} Thread safety T{
|
|
MT-Unsafe init race:utent
|
|
race:utentbuf sig:ALRM timer
|
|
T}
|
|
T{
|
|
.BR getutid (),
|
|
.BR getutline ()
|
|
T} Thread safety T{
|
|
MT-Unsafe init race:utent
|
|
sig:ALRM timer
|
|
T}
|
|
T{
|
|
.BR pututline ()
|
|
T} Thread safety T{
|
|
MT-Unsafe race:utent
|
|
sig:ALRM timer
|
|
T}
|
|
T{
|
|
.BR setutent (),
|
|
.BR endutent (),
|
|
.BR utmpname ()
|
|
T} Thread safety MT-Unsafe race:utent
|
|
.TE
|
|
.hy
|
|
.ad
|
|
.sp 1
|
|
In the above table,
|
|
.I utent
|
|
in
|
|
.I race:utent
|
|
signifies that if any of the functions
|
|
.BR setutent (),
|
|
.BR getutent (),
|
|
.BR getutid (),
|
|
.BR getutline (),
|
|
.BR pututline (),
|
|
.BR utmpname (),
|
|
or
|
|
.BR endutent ()
|
|
are used in parallel in different threads of a program,
|
|
then data races could occur.
|
|
.SH CONFORMING TO
|
|
XPG2, SVr4.
|
|
.PP
|
|
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).
|
|
HP-UX introduces a new function
|
|
.BR _pututline ()
|
|
with the prototype given above for
|
|
.BR pututline ().
|
|
.PP
|
|
All these functions are obsolete now on non-Linux systems.
|
|
POSIX.1-2001 and POSIX.1-2008, following SUSv1,
|
|
does not have any of these functions, but instead uses
|
|
.PP
|
|
.RS 4
|
|
.EX
|
|
.B #include <utmpx.h>
|
|
.PP
|
|
.B struct utmpx *getutxent(void);
|
|
.B struct utmpx *getutxid(const struct utmpx *);
|
|
.B struct utmpx *getutxline(const struct utmpx *);
|
|
.B struct utmpx *pututxline(const struct utmpx *);
|
|
.B void setutxent(void);
|
|
.B void endutxent(void);
|
|
.EE
|
|
.RE
|
|
.PP
|
|
These functions are provided by glibc,
|
|
and perform the same task as their equivalents without the "x", but use
|
|
.IR "struct utmpx" ,
|
|
defined on Linux to be the same as
|
|
.IR "struct utmp" .
|
|
For completeness, glibc also provides
|
|
.BR utmpxname (),
|
|
although this function is not specified by POSIX.1.
|
|
.PP
|
|
On some other systems,
|
|
the \fIutmpx\fP structure is a superset of the \fIutmp\fP structure,
|
|
with additional fields, and larger versions of the existing fields,
|
|
and parallel files are maintained, often
|
|
.I /var/*/utmpx
|
|
and
|
|
.IR /var/*/wtmpx .
|
|
.PP
|
|
Linux glibc on the other hand does not use a parallel \fIutmpx\fP file
|
|
since its \fIutmp\fP structure is already large enough.
|
|
The "x" functions listed above are just aliases for
|
|
their counterparts without the "x" (e.g.,
|
|
.BR getutxent ()
|
|
is an alias for
|
|
.BR getutent ()).
|
|
.SH NOTES
|
|
.SS Glibc notes
|
|
The above functions are not thread-safe.
|
|
Glibc adds reentrant versions
|
|
.PP
|
|
.nf
|
|
.B #include <utmp.h>
|
|
.PP
|
|
.BI "int getutent_r(struct utmp *" ubuf ", struct utmp **" ubufp );
|
|
.BI "int getutid_r(struct utmp *" ut ,
|
|
.BI " struct utmp *" ubuf ", struct utmp **" ubufp );
|
|
.BI "int getutline_r(struct utmp *" ut ,
|
|
.BI " struct utmp *" ubuf ", struct utmp **" ubufp );
|
|
.fi
|
|
.PP
|
|
Feature Test Macro Requirements for glibc (see
|
|
.BR feature_test_macros (7)):
|
|
.PP
|
|
.BR getutent_r (),
|
|
.BR getutid_r (),
|
|
.BR getutline_r ():
|
|
.nf
|
|
_GNU_SOURCE
|
|
|| /* Since glibc 2.19: */ _DEFAULT_SOURCE
|
|
|| /* Glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
|
|
.fi
|
|
.PP
|
|
These functions are GNU extensions, analogs of the functions of the
|
|
same name without the _r suffix.
|
|
The
|
|
.I ubuf
|
|
argument 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.
|
|
There are no utmpx equivalents of the above functions.
|
|
(POSIX.1 does not specify such functions.)
|
|
.SH EXAMPLES
|
|
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
|
|
.EX
|
|
#include <string.h>
|
|
#include <stdlib.h>
|
|
#include <pwd.h>
|
|
#include <unistd.h>
|
|
#include <utmp.h>
|
|
#include <time.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);
|
|
}
|
|
.EE
|
|
.SH SEE ALSO
|
|
.BR getutmp (3),
|
|
.BR utmp (5)
|