man3/getutent.3

   1 .\" Copyright 1995 Mark D. Roth (roth@uiuc.edu)
   2 .\"
   3 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
   4 .\" This is free documentation; you can redistribute it and/or
   5 .\" modify it under the terms of the GNU General Public License as
   6 .\" published by the Free Software Foundation; either version 2 of
   7 .\" the License, or (at your option) any later version.
   8 .\"
   9 .\" The GNU General Public License's references to "object code"
  10 .\" and "executables" are to be interpreted as the output of any
  11 .\" document formatting or typesetting system, including
  12 .\" intermediate and printed output.
  13 .\"
  14 .\" This manual is distributed in the hope that it will be useful,
  15 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17 .\" GNU General Public License for more details.
  18 .\"
  19 .\" You should have received a copy of the GNU General Public
  20 .\" License along with this manual; if not, see
  21 .\" <http://www.gnu.org/licenses/>.
  22 .\" %%%LICENSE_END
  23 .\"
  24 .\" References consulted:
  25 .\"     Linux libc source code
  26 .\"     Solaris manpages
  27 .\"
  28 .\" Modified Thu Jul 25 14:43:46 MET DST 1996 by Michael Haardt
  29 .\"     <michael@cantor.informatik.rwth-aachen.de>
  30 .\"
  31 .TH GETUTENT 3 2021-03-22 "" "Linux Programmer's Manual"
  32 .SH NAME
  33 getutent, getutid, getutline, pututline, setutent, endutent,
  34 utmpname \- access utmp file entries
  35 .SH SYNOPSIS
  36 .nf
  37 .B #include <utmp.h>
  38 .PP
  39 .B struct utmp *getutent(void);
  40 .BI "struct utmp *getutid(const struct utmp *" ut );
  41 .BI "struct utmp *getutline(const struct utmp *" ut );
  42 .PP
  43 .BI "struct utmp *pututline(const struct utmp *" ut );
  44 .PP
  45 .B void setutent(void);
  46 .B void endutent(void);
  47 .PP
  48 .BI "int utmpname(const char *" file );
  49 .fi
  50 .SH DESCRIPTION
  51 New applications should use the POSIX.1-specified "utmpx" versions of
  52 these functions; see CONFORMING TO.
  53 .PP
  54 .BR utmpname ()
  55 sets the name of the utmp-format file for the other utmp
  56 functions to access.
  57 If
  58 .BR utmpname ()
  59 is not used to set the filename
  60 before the other functions are used, they assume \fB_PATH_UTMP\fP, as
  61 defined in \fI<paths.h>\fP.
  62 .PP
  63 .BR setutent ()
  64 rewinds the file pointer to the beginning of the utmp file.
  65 It is generally a good idea to call it before any of the other
  66 functions.
  67 .PP
  68 .BR endutent ()
  69 closes the utmp file.
  70 It should be called when the user
  71 code is done accessing the file with the other functions.
  72 .PP
  73 .BR getutent ()
  74 reads a line from the current file position in the utmp file.
  75 It returns a pointer to a structure containing the fields of
  76 the line.
  77 The definition of this structure is shown in
  78 .BR utmp (5).
  79 .PP
  80 .BR getutid ()
  81 searches forward from the current file position in the utmp
  82 file based upon \fIut\fP.
  83 If \fIut\->ut_type\fP is one of \fBRUN_LVL\fP,
  84 \fBBOOT_TIME\fP, \fBNEW_TIME\fP, or \fBOLD_TIME\fP,
  85 .BR getutid ()
  86 will
  87 find the first entry whose \fIut_type\fP field matches \fIut\->ut_type\fP.
  88 If \fIut\->ut_type\fP is one of \fBINIT_PROCESS\fP, \fBLOGIN_PROCESS\fP,
  89 \fBUSER_PROCESS\fP, or \fBDEAD_PROCESS\fP,
  90 .BR getutid ()
  91 will find the
  92 first entry whose
  93 .I ut_id
  94 field matches \fIut\->ut_id\fP.
  95 .PP
  96 .BR getutline ()
  97 searches forward from the current file position in the utmp file.
  98 It scans entries whose
  99 .I ut_type
 100 is \fBUSER_PROCESS\fP
 101 or \fBLOGIN_PROCESS\fP and returns the first one whose
 102 .I ut_line
 103 field
 104 matches \fIut\->ut_line\fP.
 105 .PP
 106 .BR pututline ()
 107 writes the
 108 .I utmp
 109 structure \fIut\fP into the utmp file.
 110 It uses
 111 .BR getutid ()
 112 to search for the proper place in the file to insert
 113 the new entry.
 114 If it cannot find an appropriate slot for \fIut\fP,
 115 .BR pututline ()
 116 will append the new entry to the end of the file.
 117 .SH RETURN VALUE
 118 .BR getutent (),
 119 .BR getutid (),
 120 and
 121 .BR getutline ()
 122 return a pointer to a \fIstruct utmp\fP on success,
 123 and NULL on failure (which includes the "record not found" case).
 124 This \fIstruct utmp\fP is allocated in static storage, and may be
 125 overwritten by subsequent calls.
 126 .PP
 127 On success
 128 .BR pututline ()
 129 returns
 130 .IR ut ;
 131 on failure, it returns NULL.
 132 .PP
 133 .BR utmpname ()
 134 returns 0 if the new name was successfully stored, or \-1 on failure.
 135 .PP
 136 On failure, these functions
 137 .I errno
 138 set to indicate the error.
 139 .SH ERRORS
 140 .TP
 141 .B ENOMEM
 142 Out of memory.
 143 .TP
 144 .B ESRCH
 145 Record not found.
 146 .PP
 147 .BR setutent (),
 148 .BR pututline (),
 149 and the
 150 .BR getut* ()
 151 functions can also fail for the reasons described in
 152 .BR open (2).
 153 .SH FILES
 154 .TP
 155 .I /var/run/utmp
 156 database of currently logged-in users
 157 .TP
 158 .I /var/log/wtmp
 159 database of past user logins
 160 .SH ATTRIBUTES
 161 For an explanation of the terms used in this section, see
 162 .BR attributes (7).
 163 .ad l
 164 .nh
 165 .TS
 166 allbox;
 167 lb lb lbx
 168 l l l.
 169 Interface       Attribute       Value
 170 T{
 171 .BR getutent ()
 172 T}      Thread safety   T{
 173 MT-Unsafe init race:utent
 174 race:utentbuf sig:ALRM timer
 175 T}
 176 T{
 177 .BR getutid (),
 178 .BR getutline ()
 179 T}      Thread safety   T{
 180 MT-Unsafe init race:utent
 181 sig:ALRM timer
 182 T}
 183 T{
 184 .BR pututline ()
 185 T}      Thread safety   T{
 186 MT-Unsafe race:utent
 187 sig:ALRM timer
 188 T}
 189 T{
 190 .BR setutent (),
 191 .BR endutent (),
 192 .BR utmpname ()
 193 T}      Thread safety   MT-Unsafe race:utent
 194 .TE
 195 .hy
 196 .ad
 197 .sp 1
 198 In the above table,
 199 .I utent
 200 in
 201 .I race:utent
 202 signifies that if any of the functions
 203 .BR setutent (),
 204 .BR getutent (),
 205 .BR getutid (),
 206 .BR getutline (),
 207 .BR pututline (),
 208 .BR utmpname (),
 209 or
 210 .BR endutent ()
 211 are used in parallel in different threads of a program,
 212 then data races could occur.
 213 .SH CONFORMING TO
 214 XPG2, SVr4.
 215 .PP
 216 In XPG2 and SVID 2 the function
 217 .BR pututline ()
 218 is documented to return void, and that is what it does on many systems
 219 (AIX, HP-UX).
 220 HP-UX introduces a new function
 221 .BR _pututline ()
 222 with the prototype given above for
 223 .BR pututline ().
 224 .PP
 225 All these functions are obsolete now on non-Linux systems.
 226 POSIX.1-2001 and POSIX.1-2008, following SUSv1,
 227 does not have any of these functions, but instead uses
 228 .PP
 229 .RS 4
 230 .EX
 231 .B #include <utmpx.h>
 232 .PP
 233 .B struct utmpx *getutxent(void);
 234 .B struct utmpx *getutxid(const struct utmpx *);
 235 .B struct utmpx *getutxline(const struct utmpx *);
 236 .B struct utmpx *pututxline(const struct utmpx *);
 237 .B void setutxent(void);
 238 .B void endutxent(void);
 239 .EE
 240 .RE
 241 .PP
 242 These functions are provided by glibc,
 243 and perform the same task as their equivalents without the "x", but use
 244 .IR "struct utmpx" ,
 245 defined on Linux to be the same as
 246 .IR "struct utmp" .
 247 For completeness, glibc also provides
 248 .BR utmpxname (),
 249 although this function is not specified by POSIX.1.
 250 .PP
 251 On some other systems,
 252 the \fIutmpx\fP structure is a superset of the \fIutmp\fP structure,
 253 with additional fields, and larger versions of the existing fields,
 254 and parallel files are maintained, often
 255 .I /var/*/utmpx
 256 and
 257 .IR /var/*/wtmpx .
 258 .PP
 259 Linux glibc on the other hand does not use a parallel \fIutmpx\fP file
 260 since its \fIutmp\fP structure is already large enough.
 261 The "x" functions listed above are just aliases for
 262 their counterparts without the "x" (e.g.,
 263 .BR getutxent ()
 264 is an alias for
 265 .BR getutent ()).
 266 .SH NOTES
 267 .SS Glibc notes
 268 The above functions are not thread-safe.
 269 Glibc adds reentrant versions
 270 .PP
 271 .nf
 272 .B #include <utmp.h>
 273 .PP
 274 .BI "int getutent_r(struct utmp *" ubuf ", struct utmp **" ubufp );
 275 .BI "int getutid_r(struct utmp *" ut ,
 276 .BI "              struct utmp *" ubuf ", struct utmp **" ubufp );
 277 .BI "int getutline_r(struct utmp *" ut ,
 278 .BI "                struct utmp *" ubuf ", struct utmp **" ubufp );
 279 .fi
 280 .PP
 281 Feature Test Macro Requirements for glibc (see
 282 .BR feature_test_macros (7)):
 283 .PP
 284 .BR getutent_r (),
 285 .BR getutid_r (),
 286 .BR getutline_r ():
 287 .nf
 288     _GNU_SOURCE
 289         || /* Since glibc 2.19: */ _DEFAULT_SOURCE
 290         || /* Glibc <= 2.19: */    _SVID_SOURCE || _BSD_SOURCE
 291 .fi
 292 .PP
 293 These functions are GNU extensions, analogs of the functions of the
 294 same name without the _r suffix.
 295 The
 296 .I ubuf
 297 argument gives these functions a place to store their result.
 298 On success, they return 0, and a pointer to the result is written in
 299 .IR *ubufp .
 300 On error, these functions return \-1.
 301 There are no utmpx equivalents of the above functions.
 302 (POSIX.1 does not specify such functions.)
 303 .SH EXAMPLES
 304 The following example adds and removes a utmp record, assuming it is run
 305 from within a pseudo terminal.
 306 For usage in a real application, you
 307 should check the return values of
 308 .BR getpwuid (3)
 309 and
 310 .BR ttyname (3).
 311 .PP
 312 .EX
 313 #include <string.h>
 314 #include <stdlib.h>
 315 #include <pwd.h>
 316 #include <unistd.h>
 317 #include <utmp.h>
 318 #include <time.h>
 319
 320 int
 321 main(int argc, char *argv[])
 322 {
 323     struct utmp entry;
 324
 325     system("echo before adding entry:;who");
 326
 327     entry.ut_type = USER_PROCESS;
 328     entry.ut_pid = getpid();
 329     strcpy(entry.ut_line, ttyname(STDIN_FILENO) + strlen("/dev/"));
 330     /* only correct for ptys named /dev/tty[pqr][0\-9a\-z] */
 331     strcpy(entry.ut_id, ttyname(STDIN_FILENO) + strlen("/dev/tty"));
 332     time(&entry.ut_time);
 333     strcpy(entry.ut_user, getpwuid(getuid())\->pw_name);
 334     memset(entry.ut_host, 0, UT_HOSTSIZE);
 335     entry.ut_addr = 0;
 336     setutent();
 337     pututline(&entry);
 338
 339     system("echo after adding entry:;who");
 340
 341     entry.ut_type = DEAD_PROCESS;
 342     memset(entry.ut_line, 0, UT_LINESIZE);
 343     entry.ut_time = 0;
 344     memset(entry.ut_user, 0, UT_NAMESIZE);
 345     setutent();
 346     pututline(&entry);
 347
 348     system("echo after removing entry:;who");
 349
 350     endutent();
 351     exit(EXIT_SUCCESS);
 352 }
 353 .EE
 354 .SH SEE ALSO
 355 .BR getutmp (3),
 356 .BR utmp (5)