man3/getutent.3

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