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 2, 2009
  28 .Os
  29 .Dt ULOG_GETUTXENT 3
  30 .Sh NAME
  31 .Nm ulog_getutxent ,
  32 .Nm ulog_setutxent ,
  33 .Nm ulog_endutxent
  34 .Nd read user login records
  35 .Sh LIBRARY
  36 .Lb libulog
  37 .Sh SYNOPSIS
  38 .In ulog.h
  39 .Ft struct ulog_utmpx *
  40 .Fn ulog_getutxent "void"
  41 .Ft void
  42 .Fn ulog_setutxent "void"
  43 .Ft void
  44 .Fn ulog_endutxent "void"
  45 .Sh DESCRIPTION
  46 The
  47 .Fn ulog_getutxent
  48 function returns a pointer to an object, with the following structure,
  49 containing stored information of an active user login session.
  50 .Bd -literal
  51 struct ulog_utmpx {
  52         char    *ut_user;       /* Username. */
  53         char    *ut_line;       /* TTY device. */
  54         char    *ut_host;       /* Remote hostname. */
  55         struct timeval ut_tv;   /* Timestamp. */
  56 };
  57 .Ed
  58 .Pp
  59 The fields are as follows:
  60 .Bl -tag -width ut_user
  61 .It Fa ut_user
  62 The username of the logged in user.
  63 .It Fa ut_line
  64 The pathname of the TTY device, without the leading
  65 .Pa /dev/
  66 directory.
  67 .It Fa ut_host
  68 An optional hostname of a remote system, if the login session is
  69 provided through a networked login service.
  70 .It Fa ut_tv
  71 Timestamp indicating when the entry was last modified.
  72 .El
  73 .Pp
  74 The
  75 .Fn ulog_getutxent
  76 function reads the next entry from the utmp file, opening the file if
  77 necessary.
  78 The
  79 .Fn ulog_setutxent
  80 opens the file, closing it first if already opened.
  81 The
  82 .Fn ulog_endutxent
  83 function closes any open files.
  84 .Pp
  85 The
  86 .Fn ulog_getutxent
  87 function reads from the beginning of the file until and EOF is
  88 encountered.
  89 .Sh RETURN VALUES
  90 The
  91 .Fn ulog_getutxent
  92 function returns a null pointer on EOF or error.
  93 .Sh SEE ALSO
  94 .Xr ulog_login 3 ,
  95 .Xr utmp 5
  96 .Sh HISTORY
  97 These functions appeared in
  98 .Fx 9.0 .