lib/libulog/ulog_getutxent.3

   1 .\" Copyright (c) 2009 Ed Schouten <ed@FreeBSD.org>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd December 5, 2009
  28 .Os
  29 .Dt ULOG_GETUTXENT 3
  30 .Sh NAME
  31 .Nm ulog_getutxent ,
  32 .Nm ulog_getutxline ,
  33 .Nm ulog_pututxline ,
  34 .Nm ulog_setutxent ,
  35 .Nm ulog_endutxent
  36 .Nd read user login records
  37 .Sh LIBRARY
  38 .Lb libulog
  39 .Sh SYNOPSIS
  40 .In ulog.h
  41 .Ft struct ulog_utmpx *
  42 .Fn ulog_getutxent "void"
  43 .Ft struct ulog_utmpx *
  44 .Fn ulog_getutxline "const struct ulog_utmpx *line"
  45 .Ft struct ulog_utmpx *
  46 .Fn ulog_pututxline "const struct ulog_utmpx *utmpx"
  47 .Ft void
  48 .Fn ulog_setutxent "void"
  49 .Ft void
  50 .Fn ulog_endutxent "void"
  51 .Sh DESCRIPTION
  52 The
  53 .Fn ulog_getutxent
  54 function returns a pointer to an object, with the following structure,
  55 containing stored information of an active user login session.
  56 .Bd -literal
  57 struct ulog_utmpx {
  58         char    ut_user[];      /* Username. */
  59         char    ut_id[];        /* Private data. */
  60         char    ut_line[];      /* TTY device. */
  61         char    ut_host[];      /* Remote hostname. */
  62         pid_t   ut_pid;         /* Process identifier. */
  63         short   ut_type;        /* Type of entry. */
  64         struct timeval ut_tv;   /* Timestamp. */
  65 };
  66 .Ed
  67 .Pp
  68 The fields are as follows:
  69 .Bl -tag -width ut_user
  70 .It Fa ut_user
  71 The username of the logged in user.
  72 .It Fa ut_id
  73 Private data that can be used to later identify the record.
  74 This implementation is not capable of storing this value on disk.
  75 .It Fa ut_line
  76 The pathname of the TTY device, without the leading
  77 .Pa /dev/
  78 directory.
  79 .It Fa ut_host
  80 An optional hostname of a remote system, if the login session is
  81 provided through a networked login service.
  82 .It Fa ut_pid
  83 Process identifier of the session leader of the login session.
  84 This implementation is not capable of storing this value on disk.
  85 .It Fa ut_type
  86 The
  87 .Fa ut_type
  88 field contains the type of the message, which may have one of the
  89 following values:
  90 .Bl -tag -width SHUTDOWN_TIME
  91 .It Dv EMPTY
  92 No valid user accounting information.
  93 .It Dv BOOT_TIME
  94 Identifies time of system boot.
  95 .It Dv OLD_TIME
  96 Identifies time when system clock changed.
  97 .It Dv NEW_TIME
  98 Identifies time after system clock changed.
  99 .It Dv USER_PROCESS
 100 Identifies a process.
 101 .It Dv INIT_PROCESS
 102 Identifies a process spawned by the init process.
 103 .It Dv LOGIN_PROCESS
 104 Identifies the session leader of a logged-in user.
 105 .It Dv DEAD_PROCESS
 106 Identifies a session leader who has exited.
 107 .It Dv SHUTDOWN_TIME
 108 Identifies time when system was shut down.
 109 .El
 110 .It Fa ut_tv
 111 Timestamp indicating when the entry was last modified.
 112 .El
 113 .Pp
 114 This implementation guarantees all strings returned in the structure to
 115 be null terminated.
 116 .Pp
 117 The
 118 .Fn ulog_getutxent
 119 function reads the next entry from the utmp file, opening the file if
 120 necessary.
 121 The
 122 .Fn ulog_getutxline
 123 function reads entries from the utmp file, until finding an entry which
 124 shares the same
 125 .Fa ut_line
 126 as the structure
 127 .Fa line .
 128 The
 129 .Fn ulog_setutxent
 130 opens the file, closing it first if already opened.
 131 The
 132 .Fn ulog_endutxent
 133 function closes any open files.
 134 .Pp
 135 The
 136 .Fn ulog_getutxent
 137 and
 138 .Fn ulog_getutxline
 139 functions read from the beginning of the file until and EOF is
 140 encountered.
 141 .Pp
 142 The
 143 .Fn ulog_pututxline
 144 function writes a new entry to the file.
 145 .Sh RETURN VALUES
 146 The
 147 .Fn ulog_getutxent
 148 and
 149 .Fn ulog_getutxline
 150 functions return a null pointer on EOF or error.
 151 .Sh SEE ALSO
 152 .Xr ulog_login 3 ,
 153 .Xr ulog_setutxfile 3 ,
 154 .Xr utmp 5
 155 .Sh STANDARDS
 156 This interface is similar to
 157 .In utmpx.h
 158 described in
 159 .St -p1003.1-2008 ,
 160 but incompatible.
 161 The underlying file format does not allow a correctly behaving
 162 implementation of the standardized interface.
 163 .Pp
 164 This programming interface has been designed to ease the migration
 165 towards
 166 .In utmpx.h .
 167 If
 168 .Dv _ULOG_POSIX_NAMES
 169 is set before inclusion of
 170 .In ulog.h ,
 171 it is also possible to use the
 172 .Vt utmpx
 173 structure and the
 174 .Fn getutxent ,
 175 .Fn getutxline ,
 176 .Fn pututxline ,
 177 .Fn setutxent
 178 and
 179 .Fn endutxent
 180 functions.
 181 .Sh HISTORY
 182 These functions appeared in
 183 .Fx 9.0 .