adu.ggo

   1 # Copyright (C) 2008 Andre Noll <maan@systemlinux.org>
   2 #
   3 # Licensed under the GPL v2. For licencing details see COPYING.
   4
   5 package "adu"
   6 purpose "
   7
   8 adu creates a database containing disk usage statistics of a given
   9 directory. It allows to query that database to quickly retrieve
  10 usage patterns of subdirectories and/or files owned by a given user id.
  11 "
  12
  13 #########################
  14 section "General options"
  15 #########################
  16
  17 option "config-file" c
  18 #~~~~~~~~~~~~~~~~~~~~~
  19 "(default='~/.adurc')"
  20 string typestr="filename"
  21 optional
  22 details="
  23         Options may be given at the command line or in the
  24         configuration file. As usual, if an option is given both at
  25         the command line and in the configuration file, the command
  26         line option takes precedence.
  27 "
  28
  29 option "database-dir" d
  30 #~~~~~~~~~~~~~~~~~~~~~~
  31 "directory containing the osl tables"
  32 string typestr="path"
  33 required
  34 details="
  35         Full path to the directory containing the osl tables. This
  36         directory must exist. It must be writable for the user running
  37         adu in --create mode and readable in --select mode.
  38
  39 "
  40 option "loglevel" l
  41 #~~~~~~~~~~~~~~~~~~
  42 "Set loglevel (0-6)"
  43 int typestr="level"
  44 default="4"
  45 optional
  46 details="
  47         Log messages are always written to stderr while normal output
  48         goes to stdout. Lower values mean more verbose logging.
  49 "
  50
  51 option "paths" p
  52 #~~~~~~~~~~~~~~~
  53 "files to take into account"
  54 string typestr="pattern"
  55 optional
  56 details="
  57         Shell wildcard pattern that must match a file in order to be
  58         included in the database in --create mode or in the output
  59         for --select mode. Only the part of the filename below the
  60         base directory is matched against the pattern. The default
  61         is to take all files into account. See fnmatch(3) for details.
  62 "
  63
  64 ###############
  65 section "Modes"
  66 ###############
  67
  68 defgroup "mode"
  69 #==============
  70 groupdesc="
  71         adu may be started in one of three possible modes, each of
  72         which corresponds to a different command line option. Exactly
  73         one of these options must be given.
  74
  75 "
  76 required
  77
  78 groupoption "create" C
  79 #~~~~~~~~~~~~~~~~~~~~~
  80 "Create a new database"
  81 group="mode"
  82 details="
  83         Traverse the given directory and track disk user on a per-user
  84         basis. Results are stored in N + 1 osl tables where N is
  85         the number of uids that own at least one regular file in
  86         that directory.
  87 "
  88
  89 groupoption "interactive" I
  90 #~~~~~~~~~~~~~~~~~~~~~~~~~~
  91 "activate interactive mode"
  92 group="mode"
  93 details="
  94         In this mode, adu reads commands from stdin.  This makes it
  95         possible to run different select queries without opening the
  96         underlying osl database for each query (which is expensive).
  97
  98         In interactive mode, several subcommands are available, see
  99         the end of this document.
 100 "
 101
 102 groupoption "select" S
 103 #~~~~~~~~~~~~~~~~~~~~~
 104 "query a database previously created with --create"
 105 group="mode"
 106 details="
 107         This option prints statistics about matching subdirectories
 108         to stdout. The output can be customized by specifying select
 109         options, see below.
 110 "
 111
 112 ##############################
 113 section "Options for --create"
 114 ##############################
 115
 116 option "base-dir" b
 117 #~~~~~~~~~~~~~~~~~~
 118 "directory to traverse"
 119 string typestr="path"
 120 dependon="create"
 121 optional
 122 details="
 123         The base directory to be traversed recursively. Must be
 124         given if --create mode was selected. A warning message is
 125         printed for each subdirectory that could not be read because
 126         of insufficient permission. These directories will be ignored
 127         when computing statistics.
 128 "
 129
 130 option "one-file-system" x
 131 #~~~~~~~~~~~~~~~~~~~~~~~~~
 132 "do not dive into other file systems"
 133 flag off
 134 dependon="create"
 135 details="
 136         Skip directories that are on different file systems from the
 137         one that the argument being processed is on.
 138 "
 139
 140 option "hash-table-bits" -
 141 #~~~~~~~~~~~~~~~~~~~~~~~~~
 142 "specify the size of the uid hash table"
 143 int typestr="num"
 144 dependon="create"
 145 default="10"
 146 optional
 147 details="
 148         Use a hash table of size 2^num for the uid entries. If more than
 149         2^num different uids own at least one regular file under base-dir,
 150         the command fails. Increase this value if you have more than 1024
 151         users. Decreasing the value causes adu to use slightly less memory.
 152 "
 153
 154 ##############################
 155 section "Options for --select"
 156 ##############################
 157
 158 option "select-options" s
 159 #~~~~~~~~~~~~~~~~~~~~~~~~~
 160 "Options for select mode"
 161 string typestr="<options>"
 162 optional
 163 dependon="select"
 164 details="
 165         This option takes a string whose content is another set of
 166         options as described below.  Select options may be specified
 167         either directly in select mode, in which case you have use
 168         quotes to prevent the select options from being interpreted
 169         as adu options, or via the \"set\" command in interactive mode.
 170 "