doc/ui.1

   1 .\" Copyright (C) 2001-2006  Ben Kibbey <bjk@luxsci.net>
   2 .\"
   3 .\" This program is free software; you can redistribute it and/or modify
   4 .\" it under the terms of the GNU General Public License as published by
   5 .\" the Free Software Foundation; either version 2 of the License, or
   6 .\" (at your option) any later version.
   7 .\"
   8 .\" This program is distributed in the hope that it will be useful,
   9 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  10 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11 .\" GNU General Public License for more details.
  12 .\"
  13 .\" You should have received a copy of the GNU General Public License
  14 .\" along with this program; if not, write to the Free Software
  15 .\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  16 .
  17 .Dd December 05, 2004
  18 .Dt UI 1
  19 .Os
  20 .
  21 .Sh NAME
  22 .
  23 .Nm ui
  24 .Nd show information about local users
  25 .
  26 .Sh SYNOPSIS
  27 .
  28 .Nm ui
  29 .Op Fl hvVL
  30 .Op Fl F Ar separator
  31 .Op Fl m Ar separator
  32 .Op Fl t Ar format
  33 .Op Fl d
  34 .Op Oo Fl xXO Oc Ar module1.so Oo options Oc Oo Fl - Op Fl xXO Oc Ar module2.so Oo options Oc Op ...
  35 .Op Fl c Ar filename
  36 .Op user
  37 |
  38 .Op Fl f Ar filename
  39 .Op ...
  40 .
  41 .Sh DESCRIPTION
  42 .
  43 .Nm ui
  44 uses loadable modules to display various information about a local user.
  45 Multiple usernames or filenames (see
  46 .Fl f )
  47 may be specified. If no arguments are given or a username or filename is
  48 .Sq \- ,
  49 then arguments are read via standard input.
  50 .
  51 .Bl -tag -width
  52 .It Fl d
  53 Load the default modules (passwd.so, mail.so and login.so). This can be used
  54 anywhere in the module list.
  55 .It Fl t Ar format
  56 Specify an alternate time format for modules which have time values. See the
  57 .Xr strftime 3
  58 manual page for
  59 .Ar format
  60 syntax.
  61 .It Fl c Ar filename
  62 Load a configuration file. May be used more than once. See below for details.
  63 .It Fl O Ar filename
  64 Load a module. The remaining switches are to be options for this
  65 module. End options for this module by specifying
  66 .Fl - .
  67 This option may by used more than once. Due to the way module chaining is
  68 implemented, the same module may be loaded more than once.
  69 .It Fl x Ar filename
  70 Like
  71 .Fl O
  72 but chain
  73 .Ar module1.so
  74 output to
  75 .Ar module2.so
  76 input. This will only work if the module is chainable. You can specify this
  77 option more than once for unlimited chaining.
  78 .It Fl X Ar filename
  79 The same as
  80 .Fl x
  81 but don't output
  82 .Ar module1.so
  83 info, only pass the strings to
  84 .Ar module2.so
  85 for processing.
  86 .It Fl F Ar separator
  87 Alternate character used to separate fields. Standard escape sequences
  88 are supported.
  89 .It Fl m Ar separator
  90 Alternate character used to separate multi string values. Standard escape
  91 sequences are supported.
  92 .It Fl f
  93 Get information for the owners of the specified files.
  94 .It Fl L
  95 If the
  96 .Fl f
  97 option is specified and the file is a symbolic link, get owner
  98 information for the file the link points to and not the link itself.
  99 .It Fl v
 100 Be verbose when possible. Some modules may limit their display. This should
 101 show everything available. This is reset for each loaded module unless
 102 specified twice.
 103 .It Fl h
 104 Display help text. A module must be specified either with the
 105 .Fl O
 106 command line option or loaded via configuration file
 107 .Fl c
 108 for a modules help text to be displayed.
 109 .It Fl V
 110 Version information.
 111 .El
 112 .
 113 .Sh RETURN VALUES
 114 .
 115 Returns 1 on failure and 0 on success. Note that a modules return value
 116 affects this exit status.
 117 .
 118 .Sh FILES
 119 .
 120 .Pa PREFIX/lib/userinfo
 121 Default location of loadable modules.
 122 .
 123 .Sh EXAMPLES
 124 The following will load two modules, specify module options and load a
 125 configuration file. Module options end when
 126 .Fl -
 127 is reached.
 128 .Pp
 129 .
 130 .Nm ui
 131 .Fl O
 132 module.so
 133 .Fl switches
 134 .Fl -
 135 .Fl O
 136 another.so
 137 .Fl -
 138 .Fl c Ar filename
 139 `users`
 140 .
 141 .Sh SEE ALSO
 142 .
 143 .Xr strftime 3 ,
 144 .Xr passwd 5 ,
 145 .Xr aliases 5 ,
 146 .Xr forward 5 ,
 147 .Xr utmp 5 ,
 148 .Xr lastlog 5 ,
 149 .Xr ld.so 8
 150 .Xr dlopen 3
 151 .
 152 .Sh CONFIGURATION FILE SYNTAX
 153 .
 154 There is no default configuration file that will be loaded so you'll have to
 155 create one and load it with the
 156 .Fl c
 157 command-line option. Empty lines and everything to the right of a '#' are
 158 ignored. If you need a '#' in your options, escape it with a '\\'. This file
 159 should contain any modules you want loaded and their options separated by one
 160 or more whitespace characters on one line per module.
 161 .Pp
 162 Each module should
 163 have a .so filename extension. If a module filename begins with a ~, it will
 164 be expanded to your home directory. Some module options may require quoting.
 165 Single and double quotes are supported and may also be escaped with a
 166 backslash character. Multiple configuration files may be specified and may
 167 also be used with the
 168 .Fl O
 169 command-line option. The order of module loading and output is dependent on
 170 the order of the module stack and any module options.
 171 .Pp
 172 If you want module chaining, put a '>' or '-' at the beginning of the module
 173 name before any '~'. This is the same as specifying
 174 .Fl x
 175 or
 176 .Fl X
 177 on the command line, respectively. The following module, which may also be
 178 chained, will be chained to this module.
 179 .
 180 .Sh AUTHORS
 181 .
 182 .An "Ben Kibbey" Aq bjk@luxsci.net