man3/getutent.3

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