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 "trailer" T
  91 #~~~~~~~~~~~~~~~~~
  92 "use a customized trailer for listings/summaries"
  93 string typestr="string"
  94 optional
  95 default=""
  96 details="
  97         This option can be used to print any string at the end of
  98         the query output.
  99
 100         In user_list mode the trailer is a format string with the
 101         same semantics like the header string.
 102 "
 103
 104 option "select-mode" m
 105 #~~~~~~~~~~~~~~~~~~~~~
 106 "How to print the results of the query"
 107 enum typestr="<key>"
 108 values="user_summary","user_list","global_summary","global_list"
 109 default="user_summary"
 110 optional
 111 details="
 112         user_summary: Print totals for each admissible uid.
 113         user_list: Print a list for each admissible uid.
 114         global_summary: Only print totals.
 115         global_list: List of directories, regardless of owner.
 116 "
 117
 118 option "list-sort" s
 119 #~~~~~~~~~~~~~~~~~~~
 120 "how to sort the user list or the global list"
 121 enum typestr="<key>"
 122 values="size","file_count"
 123 default="size"
 124 optional
 125 details="
 126         This option is ignored if select-mode is neither \"user_list\", nor
 127         \"global_list\".
 128 "
 129
 130 option "output" o
 131 #~~~~~~~~~~~~~~~~
 132 "file to write output to"
 133 string typestr="path"
 134 optional
 135 default="-"
 136 details="
 137         This option is only useful in interactive mode. If stdin is redirected
 138         from a script, and the script contains several queries one can use
 139         this option to let each query write its output to a different file.
 140
 141         If the option is not given, or its argument is either \"-\" or the
 142         empty string, stdout is assumed. The following conventions cause the
 143         output to be written in a different way:
 144
 145         \"path\" may be prepended by '>' which instructs adu to truncate
 146         the output file to length zero. If \"path\" does not start with
 147         '>' and \"path\" already exists, the query is aborted. Otherwise,
 148         the file is created and truncated. The output file name \">\" is
 149         considered invalid.
 150
 151         If the first two characters of \"path\" are '>', the output file
 152         (given by removing the leading \">>\" from \"path\") is opened in
 153         append mode. It is no error if the output file does not exist. However,
 154         as above the output file name \">>\" is considered invalid.
 155
 156         If the first character of \"path\" is '|', a pipe is created and the
 157         rest of \"path\" is executed with stdin redirected to the reading
 158         end of the pipe while the query output is written to the writing end
 159         of the pipe. Again, specifying only \"|\" is considered invalid and
 160         causes an error.
 161
 162         See the manual page for examples.
 163 "
 164
 165 option "user-summary-sort" -
 166 #~~~~~~~~~~~~~~~~~~~~~~~~~~~
 167 "how to sort the user-summary"
 168 enum typestr="col_spec"
 169 values="name","uid","dir_count","file_count","size"
 170 default="size"
 171 optional
 172 details="
 173         It is enough to specify the first letter of the column specifier,
 174         e.g. \"--user-summary-sort f\" sorts by file count.
 175 "
 176
 177 option "print-base-dir" -
 178 #~~~~~~~~~~~~~~~~~~~~~~~~
 179 "whether to include the base-dir in the output"
 180 flag off
 181 details="
 182         If this flag is given, all directories printed are prefixed
 183         with the base directory. The default is to print paths relative
 184         to the base dir.
 185 "
 186
 187 option "format" f
 188 #~~~~~~~~~~~~~~~~
 189 "How to format the output"
 190 string typestr="<format_string>"
 191 optional
 192 details="
 193
 194         A string that specifies how the output of the select query is
 195         going to be formated. Depending on the chosen select-mode,
 196         several conversion specifiers are available and a different
 197         default value for this option applies.
 198
 199         adu knows four different types of directives: string, id,
 200         count and size. These are explained in more detail below.
 201
 202         The general syntax for string and id directives is %(name:a:w)
 203         where \"name\" is the name of the directive, \"a\" specifies
 204         the alignment and \"w\" is the width specifier which allows
 205         to give a field width.
 206
 207         The alignment specifier is a single character: Either \"l\",
 208         \"r\", or \"c\" may be given to specify left, right and
 209         centered alignment respectively. The with specifier is a
 210         positive integer. Both \"a\" and \"w\" are optional.
 211
 212         One string directive supported by adu is \"dirname\" which is
 213         substituted by the name of the directory. It is available
 214         if either user_list or global_list mode was selected via
 215         --select-mode.
 216
 217         Examples:
 218                 Print dirname without any padding:
 219
 220                 \"%(diname)\"
 221
 222                 Center dirname in a 20 chars wide field:
 223
 224                 \"%(dirname:c:20)\"
 225
 226         The count and size directives are used for non-negative
 227         numbers. The syntax for these is %(name:a:w:u). The \"a\" and
 228         the \"w\" specifiers have the same meaning as for the string
 229         and id directives. The additional \"u\" specifier selects a
 230         unit in which the number that corresponds to the directive
 231         should be formated. All three specifiers are optional.
 232
 233         Possible units are the characters of the set \" bkmgtBKMGT\"
 234         specifying bytes, kilobytes, megabytes, gigabytes and
 235         terabytes respectively. The difference between the lower and
 236         the upper case variants is that the lower case specifiers
 237         select 1024-based units while the upper case specifiers use
 238         1000 as the basis.
 239
 240         The whitespace character is like \"b\", but a space character
 241         is printed instead of a unit.
 242
 243         Two more characters \"h\" and \"H\" (human-readable) are also
 244         available that choose an appropriate unit depending on the
 245         size of the number being printed.
 246
 247         An asterisk prepended to the unit specifier prevents the
 248         unit from being printed. This is useful mainly for feeding
 249         the output of adu to scripts that do not expect units.
 250
 251         In order to print a percent sign, use \"%%\". Moreover, adu
 252         understands \"\\n\" and \"\\t\" and outputs a newline and a
 253         tab character for these combinations respectively.
 254
 255         Examples:
 256                 Print size in gigabytes right-aligned:
 257                         \"%(size:r::G)\"
 258
 259                 As before, but use 5 char wide field:
 260                         \"%(size:r5::G)\"
 261
 262                 As before, but suppress trailing \"G\":
 263                         \"%(size:r5::*G)\"
 264
 265
 266         The following list contains all directives known to adu,
 267         together with their types, and for which modes each of
 268         them may be used.
 269
 270                 pw_name (string): user name. Available for user_list,
 271                 user_summary and for the header in user_list mode.
 272
 273                 uid (id): user id. Available for user_list,
 274                 user_summary and for the header in user_list mode.
 275
 276                 files (count): number of files. Available for all
 277                 modes.
 278
 279                 dirname (string): name of the directory. Available
 280                 for user_list and global_list.
 281
 282                 size (size): total size/ directory size. Available
 283                 for all modes.
 284
 285                 dirs (count): number of directories. Available
 286                 for user_summary and global_summary.
 287 "