| .\" 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 2020-06-09 "" "Linux Programmer's Manual" |
| .SH NAME |
| getutent, getutid, getutline, pututline, setutent, endutent, |
| utmpname \- access utmp file entries |
| .SH SYNOPSIS |
| .B #include <utmp.h> |
| .PP |
| .B struct utmp *getutent(void); |
| .br |
| .BI "struct utmp *getutid(const struct utmp *" ut ); |
| .br |
| .BI "struct utmp *getutline(const struct utmp *" ut ); |
| .PP |
| .BI "struct utmp *pututline(const struct utmp *" ut ); |
| .PP |
| .B void setutent(void); |
| .br |
| .B void endutent(void); |
| .PP |
| .BI "int utmpname(const char *" file ); |
| .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 |
| In the event of an error, these functions |
| .I errno |
| set to indicate the cause. |
| .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). |
| .TS |
| allbox; |
| lb lb lbw28 |
| l l l. |
| Interface Attribute Value |
| T{ |
| .BR getutent () |
| T} Thread safety T{ |
| MT-Unsafe init race:utent |
| .br |
| race:utentbuf sig:ALRM timer |
| T} |
| T{ |
| .BR getutid (), |
| .br |
| .BR getutline () |
| T} Thread safety T{ |
| MT-Unsafe init race:utent |
| .br |
| sig:ALRM timer |
| T} |
| T{ |
| .BR pututline () |
| T} Thread safety T{ |
| MT-Unsafe race:utent |
| .br |
| sig:ALRM timer |
| T} |
| T{ |
| .BR setutent (), |
| .br |
| .BR endutent (), |
| .br |
| .BR utmpname () |
| T} Thread safety MT-Unsafe race:utent |
| .TE |
| .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 |
| .in +4n |
| .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 |
| .in |
| .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 |
| .in +4n |
| .EX |
| .B #include <utmp.h> |
| .PP |
| .BI "int getutent_r(struct utmp *" ubuf ", struct utmp **" ubufp ); |
| .PP |
| .BI "int getutid_r(struct utmp *" ut , |
| .BI " struct utmp *" ubuf ", struct utmp **" ubufp ); |
| .PP |
| .BI "int getutline_r(struct utmp *" ut , |
| .BI " struct utmp *" ubuf ", struct utmp **" ubufp ); |
| .EE |
| .in |
| .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) |