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