lib/libc/gen/getlastlogx.3

   1 .\"     $NetBSD: getlastlogx.3,v 1.1 2003/08/26 17:37:51 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 2003 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Thomas Klausner.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd August 26, 2003
  31 .Dt GETLASTLOGX 3
  32 .Os
  33 .Sh NAME
  34 .Nm getlastlogx ,
  35 .Nm getutmp ,
  36 .Nm getutmpx ,
  37 .Nm updlastlogx ,
  38 .Nm updwtmpx ,
  39 .Nm _updwtmpx ,
  40 .Nm utmpxname
  41 .Nd user accounting database functions
  42 .Sh LIBRARY
  43 .Lb libc
  44 .Sh SYNOPSIS
  45 .In utmpx.h
  46 .Ft struct lastlogx *
  47 .Fn getlastlogx "const char *fname" "uid_t uid" "struct lastlogx *ll"
  48 .Ft void
  49 .Fn getutmp "const struct utmpx *ux" "struct utmp *u"
  50 .Ft void
  51 .Fn getutmpx "const struct utmp *u" "struct utmpx *ux"
  52 .Ft int
  53 .Fn updlastlogx "const char *fname" "uid_t uid" "struct lastlogx *ll"
  54 .Ft void
  55 .Fn updwtmpx "const char *file" "const struct utmpx *utx"
  56 .Ft int
  57 .Fn _updwtmpx "const char *file" "const struct utmpx *utx"
  58 .Ft int
  59 .Fn utmpxname "const char *fname"
  60 .Sh DESCRIPTION
  61 The
  62 .Fn getlastlogx
  63 function looks up the entry for the user with user id
  64 .Fa uid
  65 in the
  66 .Xr lastlogx 5
  67 file given by
  68 .Fa fname
  69 and returns it in
  70 .Fa \&ll .
  71 If the provided
  72 .Fa \&ll
  73 is
  74 .Dv NULL ,
  75 the necessary space will be allocated by
  76 .Fn getlastlogx
  77 and should be
  78 .Fn free Ns d
  79 by the caller.
  80 .Pp
  81 The
  82 .Fn getutmp
  83 function fills out the entries in the struct utmp
  84 .Fa u
  85 with the data provided in the struct utmpx
  86 .Fa ux .
  87 .Fn getutmpx
  88 does the opposite, filling out the entries in the struct utmpx
  89 .Fa ux
  90 with the data provided in the struct utmp
  91 .Fa u ,
  92 and initializing all the unknown fields to 0.
  93 The sole exception is the
  94 .Fa ut_type
  95 field, which will be initialized to
  96 .Dv USER_PROCESS .
  97 .Pp
  98 The
  99 .Fn updlastlogx
 100 function tries to update the information for the user with the user id
 101 .Fa uid
 102 in the
 103 .Xr lastlogx 5
 104 file given by
 105 .Fa fname
 106 with the data supplied in
 107 .Fa \&ll .
 108 A
 109 .Ft struct lastlogx
 110 is defined like this:
 111 .Bd -literal
 112 struct lastlogx {
 113         struct timeval ll_tv;           /* time entry was created */
 114         char ll_line[_UTX_LINESIZE];    /* tty name */
 115         char ll_host[_UTX_HOSTSIZE];    /* host name */
 116         struct sockaddr_storage ll_ss;  /* address where entry was made from */
 117 };
 118 .Ed
 119 All the fields should be filled out by the caller.
 120 .Pp
 121 The
 122 .Fn updwtmpx
 123 and
 124 .Fn _updwtmpx
 125 functions update the
 126 .Xr wtmpx 5
 127 file
 128 .Fa file
 129 with the
 130 .Xr utmpx 5
 131 entry
 132 .Fa utx .
 133 .Pp
 134 The
 135 .Fn utmpxname
 136 function sets the default
 137 .Xr utmpx 5
 138 database file name to
 139 .Fa fname .
 140 .Sh RETURN VALUES
 141 .Fn getlastlogx
 142 returns the found entry on success, or
 143 .Dv NULL
 144 if it could not open the database, could not find an entry matching
 145 .Fa uid
 146 in there, or could not allocate the necessary space (in case
 147 .Fa \&ll
 148 was
 149 .Dv NULL ) .
 150 .Pp
 151 .Fn utmpxname
 152 returns 1 on success, or 0 if the supplied file name was too long or
 153 did not end with
 154 .Sq x .
 155 .Pp
 156 .Fn updlastlogx
 157 and
 158 .Fn _updwtmpx
 159 return 0 on success, or \-1 in case the database or file respectively
 160 could not be opened or the data not written into it.
 161 .Sh SEE ALSO
 162 .Xr endutxent 3 ,
 163 .Xr loginx 3 ,
 164 .Xr utmpx 5
 165 .Sh HISTORY
 166 The functions
 167 .Fn getutmp ,
 168 .Fn getutmpx ,
 169 .Fn updwtmpx ,
 170 .Fn _updwtmpx
 171 and
 172 .Fn utmpxname
 173 first appeared in
 174 .Tn Solaris .
 175 .Nm getlastlogx
 176 and
 177 .Nm updlastlogx
 178 first appeared in
 179 .Nx 2.0 .