original/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 2014-05-28 "" "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 .sp
  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 .sp
  44 .BI "struct utmp *pututline(const struct utmp *" ut );
  45 .sp
  46 .B void setutent(void);
  47 .br
  48 .B void endutent(void);
  49 .sp
  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 CONFORMING TO
 159 XPG2, SVr4.
 160 .LP
 161 In XPG2 and SVID 2 the function
 162 .BR pututline ()
 163 is documented to return void, and that is what it does on many systems
 164 (AIX, HP-UX, Linux libc5).
 165 HP-UX introduces a new function
 166 .BR _pututline ()
 167 with the prototype given above for
 168 .BR pututline ()
 169 (also found in Linux libc5).
 170 .LP
 171 All these functions are obsolete now on non-Linux systems.
 172 POSIX.1-2001, following SUSv1,
 173 does not have any of these functions, but instead uses
 174 .sp
 175 .B #include <utmpx.h>
 176 .sp
 177 .B struct utmpx *getutxent(void);
 178 .br
 179 .B struct utmpx *getutxid(const struct utmpx *);
 180 .br
 181 .B struct utmpx *getutxline(const struct utmpx *);
 182 .br
 183 .B struct utmpx *pututxline(const struct utmpx *);
 184 .br
 185 .B void setutxent(void);
 186 .br
 187 .B void endutxent(void);
 188 .PP
 189 These functions are provided by glibc,
 190 and perform the same task as their equivalents without the "x", but use
 191 .IR "struct utmpx" ,
 192 defined on Linux to be the same as
 193 .IR "struct utmp" .
 194 For completeness, glibc also provides
 195 .BR utmpxname (),
 196 although this function is not specified by POSIX.1.
 197 .PP
 198 On some other systems,
 199 the \fIutmpx\fP structure is a superset of the \fIutmp\fP structure,
 200 with additional fields, and larger versions of the existing fields,
 201 and parallel files are maintained, often
 202 .I /var/*/utmpx
 203 and
 204 .IR /var/*/wtmpx .
 205 .LP
 206 Linux glibc on the other hand does not use a parallel \fIutmpx\fP file
 207 since its \fIutmp\fP structure is already large enough.
 208 The "x" functions listed above are just aliases for
 209 their counterparts without the "x" (e.g.,
 210 .BR getutxent ()
 211 is an alias for
 212 .BR getutent ()).
 213 .SH NOTES
 214 .SS Glibc notes
 215 The above functions are not thread-safe.
 216 Glibc adds reentrant versions
 217 .sp
 218 .nf
 219 .BR "#define _GNU_SOURCE" "    /* or _SVID_SOURCE or _BSD_SOURCE;
 220 .RB "\&                          see " feature_test_macros "(7) */"
 221 .B #include <utmp.h>
 222 .sp
 223 .BI "int getutent_r(struct utmp *" ubuf ", struct utmp **" ubufp );
 224 .sp
 225 .BI "int getutid_r(struct utmp *" ut ,
 226 .BI "              struct utmp *" ubuf ", struct utmp **" ubufp );
 227 .sp
 228 .BI "int getutline_r(struct utmp *" ut ,
 229 .BI "                struct utmp *" ubuf ", struct utmp **" ubufp );
 230 .fi
 231 .sp
 232 These functions are GNU extensions, analogs of the functions of the
 233 same name without the _r suffix.
 234 The
 235 .I ubuf
 236 argument gives these functions a place to store their result.
 237 On success they return 0, and a pointer to the result is written in
 238 .IR *ubufp .
 239 On error, these functions return \-1.
 240 There are no utmpx equivalents of the above functions.
 241 (POSIX.1 does not specify such functions.)
 242 .SH EXAMPLE
 243 The following example adds and removes a utmp record, assuming it is run
 244 from within a pseudo terminal.
 245 For usage in a real application, you
 246 should check the return values of
 247 .BR getpwuid (3)
 248 and
 249 .BR ttyname (3).
 250 .PP
 251 .nf
 252 #include <string.h>
 253 #include <stdlib.h>
 254 #include <pwd.h>
 255 #include <unistd.h>
 256 #include <utmp.h>
 257
 258 int
 259 main(int argc, char *argv[])
 260 {
 261     struct utmp entry;
 262
 263     system("echo before adding entry:;who");
 264
 265     entry.ut_type = USER_PROCESS;
 266     entry.ut_pid = getpid();
 267     strcpy(entry.ut_line, ttyname(STDIN_FILENO) + strlen("/dev/"));
 268     /* only correct for ptys named /dev/tty[pqr][0\-9a\-z] */
 269     strcpy(entry.ut_id, ttyname(STDIN_FILENO) + strlen("/dev/tty"));
 270     time(&entry.ut_time);
 271     strcpy(entry.ut_user, getpwuid(getuid())\->pw_name);
 272     memset(entry.ut_host, 0, UT_HOSTSIZE);
 273     entry.ut_addr = 0;
 274     setutent();
 275     pututline(&entry);
 276
 277     system("echo after adding entry:;who");
 278
 279     entry.ut_type = DEAD_PROCESS;
 280     memset(entry.ut_line, 0, UT_LINESIZE);
 281     entry.ut_time = 0;
 282     memset(entry.ut_user, 0, UT_NAMESIZE);
 283     setutent();
 284     pututline(&entry);
 285
 286     system("echo after removing entry:;who");
 287
 288     endutent();
 289     exit(EXIT_SUCCESS);
 290 }
 291 .fi
 292 .SH SEE ALSO
 293 .BR getutmp (3),
 294 .BR utmp (5)
 295 .SH COLOPHON
 296 This page is part of release 3.68 of the Linux
 297 .I man-pages
 298 project.
 299 A description of the project,
 300 information about reporting bugs,
 301 and the latest version of this page,
 302 can be found at
 303 \%http://www.kernel.org/doc/man\-pages/.