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 None.
 200 .SH HISTORY
 201 XPG2, SVr4.
 202 .PP
 203 In XPG2 and SVID 2 the function
 204 .BR pututline ()
 205 is documented to return void, and that is what it does on many systems
 206 (AIX, HP-UX).
 207 HP-UX introduces a new function
 208 .BR _pututline ()
 209 with the prototype given above for
 210 .BR pututline ().
 211 .PP
 212 All these functions are obsolete now on non-Linux systems.
 213 POSIX.1-2001 and POSIX.1-2008, following SUSv1,
 214 does not have any of these functions, but instead uses
 215 .PP
 216 .RS 4
 217 .EX
 218 .B #include <utmpx.h>
 219 .PP
 220 .B struct utmpx *getutxent(void);
 221 .B struct utmpx *getutxid(const struct utmpx *);
 222 .B struct utmpx *getutxline(const struct utmpx *);
 223 .B struct utmpx *pututxline(const struct utmpx *);
 224 .B void setutxent(void);
 225 .B void endutxent(void);
 226 .EE
 227 .RE
 228 .PP
 229 These functions are provided by glibc,
 230 and perform the same task as their equivalents without the "x", but use
 231 .IR "struct utmpx" ,
 232 defined on Linux to be the same as
 233 .IR "struct utmp" .
 234 For completeness, glibc also provides
 235 .BR utmpxname (),
 236 although this function is not specified by POSIX.1.
 237 .PP
 238 On some other systems,
 239 the \fIutmpx\fP structure is a superset of the \fIutmp\fP structure,
 240 with additional fields, and larger versions of the existing fields,
 241 and parallel files are maintained, often
 242 .I /var/*/utmpx
 243 and
 244 .IR /var/*/wtmpx .
 245 .PP
 246 Linux glibc on the other hand does not use a parallel \fIutmpx\fP file
 247 since its \fIutmp\fP structure is already large enough.
 248 The "x" functions listed above are just aliases for
 249 their counterparts without the "x" (e.g.,
 250 .BR getutxent ()
 251 is an alias for
 252 .BR getutent ()).
 253 .SH NOTES
 254 .SS glibc notes
 255 The above functions are not thread-safe.
 256 glibc adds reentrant versions
 257 .PP
 258 .nf
 259 .B #include <utmp.h>
 260 .PP
 261 .BI "int getutent_r(struct utmp *" ubuf ", struct utmp **" ubufp );
 262 .BI "int getutid_r(struct utmp *" ut ,
 263 .BI "              struct utmp *" ubuf ", struct utmp **" ubufp );
 264 .BI "int getutline_r(struct utmp *" ut ,
 265 .BI "                struct utmp *" ubuf ", struct utmp **" ubufp );
 266 .fi
 267 .PP
 268 Feature Test Macro Requirements for glibc (see
 269 .BR feature_test_macros (7)):
 270 .PP
 271 .BR getutent_r (),
 272 .BR getutid_r (),
 273 .BR getutline_r ():
 274 .nf
 275     _GNU_SOURCE
 276         || /* Since glibc 2.19: */ _DEFAULT_SOURCE
 277         || /* glibc <= 2.19: */    _SVID_SOURCE || _BSD_SOURCE
 278 .fi
 279 .PP
 280 These functions are GNU extensions, analogs of the functions of the
 281 same name without the _r suffix.
 282 The
 283 .I ubuf
 284 argument gives these functions a place to store their result.
 285 On success, they return 0, and a pointer to the result is written in
 286 .IR *ubufp .
 287 On error, these functions return \-1.
 288 There are no utmpx equivalents of the above functions.
 289 (POSIX.1 does not specify such functions.)
 290 .SH EXAMPLES
 291 The following example adds and removes a utmp record, assuming it is run
 292 from within a pseudo terminal.
 293 For usage in a real application, you
 294 should check the return values of
 295 .BR getpwuid (3)
 296 and
 297 .BR ttyname (3).
 298 .PP
 299 .\" SRC BEGIN (getutent.c)
 300 .EX
 301 #include <pwd.h>
 302 #include <stdlib.h>
 303 #include <string.h>
 304 #include <time.h>
 305 #include <unistd.h>
 306 #include <utmp.h>
 307 \&
 308 int
 309 main(void)
 310 {
 311     struct utmp entry;
 312 \&
 313     system("echo before adding entry:;who");
 314 \&
 315     entry.ut_type = USER_PROCESS;
 316     entry.ut_pid = getpid();
 317     strcpy(entry.ut_line, ttyname(STDIN_FILENO) + strlen("/dev/"));
 318     /* only correct for ptys named /dev/tty[pqr][0\-9a\-z] */
 319     strcpy(entry.ut_id, ttyname(STDIN_FILENO) + strlen("/dev/tty"));
 320     time(&entry.ut_time);
 321     strcpy(entry.ut_user, getpwuid(getuid())\->pw_name);
 322     memset(entry.ut_host, 0, UT_HOSTSIZE);
 323     entry.ut_addr = 0;
 324     setutent();
 325     pututline(&entry);
 326 \&
 327     system("echo after adding entry:;who");
 328 \&
 329     entry.ut_type = DEAD_PROCESS;
 330     memset(entry.ut_line, 0, UT_LINESIZE);
 331     entry.ut_time = 0;
 332     memset(entry.ut_user, 0, UT_NAMESIZE);
 333     setutent();
 334     pututline(&entry);
 335 \&
 336     system("echo after removing entry:;who");
 337 \&
 338     endutent();
 339     exit(EXIT_SUCCESS);
 340 }
 341 .EE
 342 .\" SRC END
 343 .SH SEE ALSO
 344 .BR getutmp (3),
 345 .BR utmp (5)