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 2016-10-08 "" "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
  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
 128 On success
 129 .BR pututline ()
 130 returns
 131 .IR ut ;
 132 on failure, it returns NULL.
 133
 134 .BR utmpname ()
 135 returns 0 if the new name was successfully stored, or \-1 on failure.
 136
 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 /var/run/utmp   database of currently logged-in users
 156 .br
 157 /var/log/wtmp   database of past user logins
 158 .SH ATTRIBUTES
 159 For an explanation of the terms used in this section, see
 160 .BR attributes (7).
 161 .TS
 162 allbox;
 163 lb lb lbw28
 164 l l l.
 165 Interface       Attribute       Value
 166 T{
 167 .BR getutent ()
 168 T}      Thread safety   T{
 169 MT-Unsafe init race:utent
 170 .br
 171 race:utentbuf sig:ALRM timer
 172 T}
 173 T{
 174 .BR getutid (),
 175 .br
 176 .BR getutline ()
 177 T}      Thread safety   T{
 178 MT-Unsafe init race:utent
 179 .br
 180 sig:ALRM timer
 181 T}
 182 T{
 183 .BR pututline ()
 184 T}      Thread safety   T{
 185 MT-Unsafe race:utent
 186 .br
 187 sig:ALRM timer
 188 T}
 189 T{
 190 .BR setutent (),
 191 .br
 192 .BR endutent (),
 193 .br
 194 .BR utmpname ()
 195 T}      Thread safety   MT-Unsafe race:utent
 196 .TE
 197
 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 .LP
 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 .LP
 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 .sp
 229 .B #include <utmpx.h>
 230 .sp
 231 .B struct utmpx *getutxent(void);
 232 .br
 233 .B struct utmpx *getutxid(const struct utmpx *);
 234 .br
 235 .B struct utmpx *getutxline(const struct utmpx *);
 236 .br
 237 .B struct utmpx *pututxline(const struct utmpx *);
 238 .br
 239 .B void setutxent(void);
 240 .br
 241 .B void endutxent(void);
 242 .PP
 243 These functions are provided by glibc,
 244 and perform the same task as their equivalents without the "x", but use
 245 .IR "struct utmpx" ,
 246 defined on Linux to be the same as
 247 .IR "struct utmp" .
 248 For completeness, glibc also provides
 249 .BR utmpxname (),
 250 although this function is not specified by POSIX.1.
 251 .PP
 252 On some other systems,
 253 the \fIutmpx\fP structure is a superset of the \fIutmp\fP structure,
 254 with additional fields, and larger versions of the existing fields,
 255 and parallel files are maintained, often
 256 .I /var/*/utmpx
 257 and
 258 .IR /var/*/wtmpx .
 259 .LP
 260 Linux glibc on the other hand does not use a parallel \fIutmpx\fP file
 261 since its \fIutmp\fP structure is already large enough.
 262 The "x" functions listed above are just aliases for
 263 their counterparts without the "x" (e.g.,
 264 .BR getutxent ()
 265 is an alias for
 266 .BR getutent ()).
 267 .SH NOTES
 268 .SS Glibc notes
 269 The above functions are not thread-safe.
 270 Glibc adds reentrant versions
 271 .sp
 272 .nf
 273 .B #include <utmp.h>
 274 .sp
 275 .BI "int getutent_r(struct utmp *" ubuf ", struct utmp **" ubufp );
 276 .sp
 277 .BI "int getutid_r(struct utmp *" ut ,
 278 .BI "              struct utmp *" ubuf ", struct utmp **" ubufp );
 279 .sp
 280 .BI "int getutline_r(struct utmp *" ut ,
 281 .BI "                struct utmp *" ubuf ", struct utmp **" ubufp );
 282 .fi
 283 .sp
 284 .in -4n
 285 Feature Test Macro Requirements for glibc (see
 286 .BR feature_test_macros (7)):
 287 .in
 288 .sp
 289 .BR getutent_r (),
 290 .BR getutid_r (),
 291 .BR getutline_r ():
 292 .nf
 293     _GNU_SOURCE
 294     || /* since glibc 2.19: */ _DEFAULT_SOURCE
 295     || /* glibc <= 2.19: */    _SVID_SOURCE || _BSD_SOURCE
 296 .fi
 297 .sp
 298 These functions are GNU extensions, analogs of the functions of the
 299 same name without the _r suffix.
 300 The
 301 .I ubuf
 302 argument gives these functions a place to store their result.
 303 On success, they return 0, and a pointer to the result is written in
 304 .IR *ubufp .
 305 On error, these functions return \-1.
 306 There are no utmpx equivalents of the above functions.
 307 (POSIX.1 does not specify such functions.)
 308 .SH EXAMPLE
 309 The following example adds and removes a utmp record, assuming it is run
 310 from within a pseudo terminal.
 311 For usage in a real application, you
 312 should check the return values of
 313 .BR getpwuid (3)
 314 and
 315 .BR ttyname (3).
 316 .PP
 317 .nf
 318 #include <string.h>
 319 #include <stdlib.h>
 320 #include <pwd.h>
 321 #include <unistd.h>
 322 #include <utmp.h>
 323
 324 int
 325 main(int argc, char *argv[])
 326 {
 327     struct utmp entry;
 328
 329     system("echo before adding entry:;who");
 330
 331     entry.ut_type = USER_PROCESS;
 332     entry.ut_pid = getpid();
 333     strcpy(entry.ut_line, ttyname(STDIN_FILENO) + strlen("/dev/"));
 334     /* only correct for ptys named /dev/tty[pqr][0\-9a\-z] */
 335     strcpy(entry.ut_id, ttyname(STDIN_FILENO) + strlen("/dev/tty"));
 336     time(&entry.ut_time);
 337     strcpy(entry.ut_user, getpwuid(getuid())\->pw_name);
 338     memset(entry.ut_host, 0, UT_HOSTSIZE);
 339     entry.ut_addr = 0;
 340     setutent();
 341     pututline(&entry);
 342
 343     system("echo after adding entry:;who");
 344
 345     entry.ut_type = DEAD_PROCESS;
 346     memset(entry.ut_line, 0, UT_LINESIZE);
 347     entry.ut_time = 0;
 348     memset(entry.ut_user, 0, UT_NAMESIZE);
 349     setutent();
 350     pututline(&entry);
 351
 352     system("echo after removing entry:;who");
 353
 354     endutent();
 355     exit(EXIT_SUCCESS);
 356 }
 357 .fi
 358 .SH SEE ALSO
 359 .BR getutmp (3),
 360 .BR utmp (5)