select.ggo

   1 option "user" u
   2 #~~~~~~~~~~~~~~
   3 "users to take into account"
   4 string typestr="user_name"
   5 optional
   6 multiple
   7 details="
   8         This option may be given multiple times in which case all given
   9         user names are considered admissible. See also --uid below.
  10 "
  11
  12 option "uid" U
  13 #~~~~~~~~~~~~~
  14 "user id(s) to take into account"
  15 string typestr="uid_spec"
  16 optional
  17 details="
  18         An uid specifier may be a single uid, a range of uids,
  19         or a comma-separated list of single uids or ranges.
  20         Example:
  21
  22         Only consider uid 42:
  23                 --uid 42
  24
  25         Only consider uids greater or equal than 42:
  26                 --uid 42-
  27
  28         Only consider uids between 23 and 42, inclusively:
  29                 --uid 23-42
  30
  31         Consider uids 23-42, 666-777 and 88:
  32                 --uid 23-42,666-777,88
  33
  34         If no --user option is given and also --uid option is not given
  35         (the default), all users are taken into account.
  36 "
  37
  38 option "limit" l
  39 #~~~~~~~~~~~~~~~
  40 "Limit output"
  41 int typestr="num"
  42 default="-1"
  43 optional
  44 details="
  45         Only print num lines of output. If negative (the default),
  46         print all lines. This option is honored in all select modes
  47         except global_summary (which outputs only one single line).
  48 "
  49
  50 option "pattern" p
  51 #~~~~~~~~~~~~~~~~~
  52 "only consider matching directories"
  53 string typestr="regex"
  54 optional
  55 details="
  56         Regular expression that must match the directory name for
  57         the directory to be considered for the output of the query.
  58         See regex(7) for details.
  59
  60         Depending on whether --print-base-dir is given, the absolute
  61         directory name or only the part of the directory name below
  62         the base directory is matched against \"regex\".
  63
  64         If this option is not given (the default) all directories
  65         are taken into account.
  66
  67         If \"regex\" starts with '!', directories are matched against
  68         the remaining part of \"regex\" and the sense of matching is
  69         reversed.
  70 "
  71
  72 option "header" H
  73 #~~~~~~~~~~~~~~~~
  74 "use a customized header for listings/summaries"
  75 string typestr="string"
  76 optional
  77 details="
  78         This option can be used to print any string instead of the
  79         default header line (which depends on the selected mode).
  80
  81         In user_list mode the header is a format string which allows
  82         to include the uid and the user name in the header. See the
  83         --format option for more details.
  84
  85         It is possible to set this to the empty string to suppress
  86         the header completely. This is mostly useful to feed the
  87         output to scripts.
  88 "
  89
  90 option "select-mode" m
  91 #~~~~~~~~~~~~~~~~~~~~~
  92 "How to print the results of the query"
  93 enum typestr="<key>"
  94 values="user_summary","user_list","global_summary","global_list"
  95 default="user_summary"
  96 optional
  97 details="
  98         user_summary: Print totals for each admissible uid.
  99         user_list: Print a list for each admissible uid.
 100         global_summary: Only print totals.
 101         global_list: List of directories, regardless of owner.
 102 "
 103
 104 option "list-sort" s
 105 #~~~~~~~~~~~~~~~~~~~
 106 "how to sort the user list or the global list"
 107 enum typestr="<key>"
 108 values="size","file_count"
 109 default="size"
 110 optional
 111 details="
 112         This option is ignored if select-mode is neither \"user_list\", nor
 113         \"global_list\".
 114 "
 115
 116 option "output" o
 117 #~~~~~~~~~~~~~~~~
 118 "file to write output to"
 119 string typestr="path"
 120 optional
 121 default="-"
 122 details="
 123         If empty, or not given, use stdout. The following conventions
 124         cause the output to be written differently:
 125
 126         An output file name of \"-\" means stdout.
 127
 128         \"path\" may be prepended by '>' which instructs adu to
 129         truncate the output file to length zero.  If \"path\" does
 130         not start with '>' and \"path\" already exists, the select
 131         query is being aborted. Otherwise, \"path\" is created and
 132         output is written to \"path\".
 133
 134         If the first two characters of \"path\" are '>', the output
 135         file (given by removing the leading \">>\" from \"path\")
 136         is being opened in append mode. It is no error if the output
 137         file does not exist but, as above, the output file name \">>\"
 138         is considered invalid.
 139
 140         If the first character of \"path\" is '|', a pipe is created
 141         and the rest of \"path\" is being executed with its standard in
 142         redirected to the reading end of the pipe. The output of adu
 143         is written to the writing end of the pipe. Again, specifying
 144         only \"|\" is considered invalid and causes an error.
 145 "
 146
 147 option "user-summary-sort" -
 148 #~~~~~~~~~~~~~~~~~~~~~~~~~~~
 149 "how to sort the user-summary"
 150 enum typestr="col_spec"
 151 values="name","uid","dir_count","file_count","size"
 152 default="size"
 153 optional
 154 details="
 155         It is enough to specify the first letter of the column specifier,
 156         e.g. \"--user-summary-sort f\" sorts by file count.
 157 "
 158
 159 option "print-base-dir" -
 160 #~~~~~~~~~~~~~~~~~~~~~~~~
 161 "whether to include the base-dir in the output"
 162 flag off
 163 details="
 164         If this flag is given, all directories printed are prefixed
 165         with the base directory. The default is to print paths relative
 166         to the base dir.
 167 "
 168
 169 option "format" f
 170 #~~~~~~~~~~~~~~~~
 171 "How to format the output"
 172 string typestr="<format_string>"
 173 optional
 174 details="
 175
 176         A string that specifies how the output of the select query is
 177         going to be formated. Depending on the chosen select-mode,
 178         several conversion specifiers are available and a different
 179         default value for this option applies.
 180
 181         adu knows four different types of directives: string, id,
 182         count and size. These are explained in more detail below.
 183
 184         The general syntax for string and id directives is %(name:a:w)
 185         where \"name\" is the name of the directive, \"a\" specifies
 186         the alignment and \"w\" is the width specifier which allows
 187         to give a field width.
 188
 189         The alignment specifier is a single character: Either \"l\",
 190         \"r\", or \"c\" may be given to specify left, right and
 191         centered alignment respectively. The with specifier is a
 192         positive integer. Both \"a\" and \"w\" are optional.
 193
 194         A string directive supported by adu is \"dirname\" which is
 195         substituted by the name of the directory. It is available
 196         if either user_list or global_list mode was selected via
 197         --select-mode.
 198
 199         Examples:
 200                 Print dirname without any padding:
 201
 202                 \"%(diname)\"
 203
 204                 Center dirname in a 20 chars wide field:
 205
 206                 \"%(dirname:c:20)\"
 207
 208         The other two types of directives, count and size, are used
 209         for numbers. The syntax for these is %(name:a:w:u). The \"a\"
 210         and the \"w\" specifier have the same meaning as for the string
 211         and id directives. The additional \"u\" specifier selects a unit
 212         in which the number that corresponds to the directive should
 213         be formated. All three specifiers are optional.
 214
 215         Possible units are the characters of the set \" bkmgtBKMGT\"
 216         specifying bytes, kilobytes, megabytes, gigabytes and
 217         terabytes respectively. The difference between the lower and
 218         the upper case variants is that the lower case specifiers
 219         select 1024-based units while the upper case specifiers use
 220         1000 as the basis.
 221
 222         The whitespace character is like \"b\", but a space character
 223         is printed instead of a unit.
 224
 225         Two more characters \"h\" and \"H\" (human-readable) are also
 226         available that choose an appropriate unit depending on the
 227         size of the number being printed.
 228
 229         An asterisk prepended to the unit specifier prevents the
 230         unit from being printed. This is useful mainly for feeding
 231         the output of adu to scripts that do not expect units.
 232
 233         In order to print a percent sign, use \"%%\". Moreover, adu
 234         understands \"\\n\" and \"\\t\" and outputs a newline and a
 235         tab character for these combinations respectively.
 236
 237         Examples:
 238                 Print size in gigabytes right-aligned:
 239                         \"%(size:r::G)\"
 240
 241                 As before, but use 5 char wide field:
 242                         \"%(size:r5::G)\"
 243
 244                 As before, but suppress trailing \"G\":
 245                         \"%(size:r5::*G)\"
 246
 247
 248         The following list contains all directives known to adu,
 249         together with their types, and for which modes each of
 250         them may be used.
 251
 252                 pw_name (string): user name. Available for user_list,
 253                 user_summary and for the header in user_list mode.
 254
 255                 uid (id): user id. Available for user_list,
 256                 user_summary and for the header in user_list mode.
 257
 258                 files (count): number of files. Available for all
 259                 modes.
 260
 261                 dirname (string): name of the directory. Available
 262                 for user_list and global_list.
 263
 264                 size (size): total size/ directory size. Available
 265                 for all modes.
 266
 267                 dirs (count): number of directories. Available
 268                 for user_summary and global_summary.
 269 "