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