diff options
Diffstat (limited to 'man/man3/getutent.3')
| -rw-r--r-- | man/man3/getutent.3 | 355 |
1 files changed, 355 insertions, 0 deletions
diff --git a/man/man3/getutent.3 b/man/man3/getutent.3 new file mode 100644 index 000000000..656a52cd2 --- /dev/null +++ b/man/man3/getutent.3 @@ -0,0 +1,355 @@ +'\" t +.\" Copyright 1995 Mark D. Roth (roth@uiuc.edu) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 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 (date) "Linux man-pages (unreleased)" +.SH NAME +getutent, getutid, getutline, pututline, setutent, endutent, +utmpname \- access utmp file entries +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <utmp.h> +.P +.B struct utmp *getutent(void); +.BI "struct utmp *getutid(const struct utmp *" ut ); +.BI "struct utmp *getutline(const struct utmp *" ut ); +.P +.BI "struct utmp *pututline(const struct utmp *" ut ); +.P +.B void setutent(void); +.B void endutent(void); +.P +.BI "int utmpname(const char *" file ); +.fi +.SH DESCRIPTION +New applications should use the POSIX.1-specified "utmpx" versions of +these functions; see STANDARDS. +.P +.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. +.P +.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. +.P +.BR endutent () +closes the utmp file. +It should be called when the user +code is done accessing the file with the other functions. +.P +.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). +.P +.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. +.P +.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. +.P +.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. +.P +On success +.BR pututline () +returns +.IR ut ; +on failure, it returns NULL. +.P +.BR utmpname () +returns 0 if the new name was successfully stored, or \-1 on failure. +.P +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. +.P +.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). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getutent () +T} Thread safety T{ +.na +.nh +MT-Unsafe init race:utent +race:utentbuf sig:ALRM timer +T} +T{ +.na +.nh +.BR getutid (), +.BR getutline () +T} Thread safety T{ +.na +.nh +MT-Unsafe init race:utent +sig:ALRM timer +T} +T{ +.na +.nh +.BR pututline () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:utent +sig:ALRM timer +T} +T{ +.na +.nh +.BR setutent (), +.BR endutent (), +.BR utmpname () +T} Thread safety MT-Unsafe race:utent +.TE +.P +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 STANDARDS +None. +.SH HISTORY +XPG2, SVr4. +.P +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 (). +.P +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 +.P +.RS 4 +.EX +.B #include <utmpx.h> +.P +.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 +.P +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. +.P +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 . +.P +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 +.P +.nf +.B #include <utmp.h> +.P +.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 +.P +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.P +.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 +.P +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). +.P +.\" SRC BEGIN (getutent.c) +.EX +#include <pwd.h> +#include <stdlib.h> +#include <string.h> +#include <time.h> +#include <unistd.h> +#include <utmp.h> +\& +int +main(void) +{ + 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")); + entry.ut_time = time(NULL); + 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 +.\" SRC END +.SH SEE ALSO +.BR getutmp (3), +.BR utmp (5) |