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.
  47 "
  48
  49 option "no-headers" -
  50 #~~~~~~~~~~~~~~~~~~~~
  51 "suppress descriptions for listings/summaries"
  52 flag off
  53 details="
  54         This is mostly useful to feed the output of adu to scripts.
  55 "
  56
  57 option "select-mode" m
  58 #~~~~~~~~~~~~~~~~~~~~~
  59 "How to print the results of the query"
  60 enum typestr="<key>"
  61 values="global_list","global_summary","user_list","user_summary"
  62 default="global_list"
  63 optional
  64 details="
  65         global_list: List of directories, regardless of owner.
  66         global_summary: Only print totals.
  67         user_list: Print a list for each admissible uid.
  68         user_summary Print totals for each admissible uid.
  69 "
  70
  71 option "list-sort" s
  72 #~~~~~~~~~~~~~~~~~~~
  73 "how to sort the user list or the global list"
  74 enum typestr="<key>"
  75 values="size","file_count"
  76 default="size"
  77 optional
  78 details="
  79         This option is ignored if select-mode is neither \"user_list\", nor
  80         \"global_list\".
  81 "
  82
  83 option "output" o
  84 #~~~~~~~~~~~~~~~~
  85 "file to write output to"
  86 string typestr="path"
  87 optional
  88 default="-"
  89 details="
  90         If empty, or not given, use stdout. The following conventions
  91         cause the output to be written differently:
  92
  93         An output file name of \"-\" means stdout.
  94
  95         \"path\" may be prepended by '>' which instructs adu to
  96         truncate the output file to length zero.  If \"path\" does
  97         not start with '>' and \"path\" already exists, the select
  98         query is being aborted. Otherwise, \"path\" is created and
  99         output is written to \"path\".
 100
 101         If the first two characters of \"path\" are '>', the output
 102         file (given by removing the leading \">>\" from \"path\")
 103         is being opened in append mode. It is no error if the output
 104         file does not exist but, as above, the output file name \">>\"
 105         is considered invalid.
 106
 107         If the first character of \"path\" is '|', a pipe is created
 108         and the rest of \"path\" is being executed with its standard in
 109         redirected to the reading end of the pipe. The output of adu
 110         is written to the writing end of the pipe. Again, specifying
 111         only \"|\" is considered invalid and causes an error.
 112 "
 113
 114 option "user-summary-sort" -
 115 #~~~~~~~~~~~~~~~~~~~~~~~~~~~
 116 "how to sort the user-summary"
 117 enum typestr="col_spec"
 118 values="name","uid","dir_count","file_count","size"
 119 default="size"
 120 optional
 121 details="
 122         It is enough to specify the first letter of the column specifier,
 123         e.g. \"--user-summary-sort f\" sorts by file count.
 124 "
 125
 126 option "print-base-dir" -
 127 #~~~~~~~~~~~~~~~~~~~~~~~~
 128 "whether to include the base-dir in the output"
 129 flag off
 130 details="
 131         If this flag is given, all directories printed are prefixed
 132         with the base directory. The default is to print paths relative
 133         to the base dir.
 134 "
 135
 136 option "format" f
 137 #~~~~~~~~~~~~~~~~
 138 "How to format the output"
 139 string typestr="<format_string>"
 140 optional
 141 details="
 142
 143         A string that specifies how the output of the select query is
 144         going to be formated.  Depending on the chosen select-mode,
 145         several conversion specifiers are available and a different
 146         default value for this option applies.
 147
 148         adu knows four different types of directives: string, id,
 149         count and size.  These are explained in more detail below.
 150
 151         The general syntax for string and id directives is %(name:a:w)
 152         where \"name\" is the name of the directive, \"a\" specifies
 153         the alignment and \"w\" is the width specifier which allows
 154         to give a field width.
 155
 156         The alignment specifier is a single character: Either \"l\",
 157         \"r\", or \"c\" may be given to specify left, right and
 158         centered alignment respectively. The with specifier is a
 159         positive integer.  Both \"a\" and \"w\" are optional.
 160
 161         A string directive supported by adu is \"dirname\" which is
 162         substituted by the name of the directory. It is available
 163         if either user_list or global_list mode was selected via
 164         --select-mode.
 165
 166         Examples:
 167                 Print dirname without any padding:
 168
 169                 \"%(diname)\"
 170
 171                 Center dirname in a 20 chars wide field:
 172
 173                 \"%(dirname:c:20)\"
 174
 175         The other two types of directives, count and size, are used
 176         for numbers. The syntax for these is %(name:a:w:u). The \"a\"
 177         and the \"w\" specifier have the same meaning as for the string
 178         and id directives. The additional \"u\" specifier selects a unit
 179         in which the number that corresponds to the directive should
 180         be formated. All three specifiers are optional.
 181
 182         Possible units are the characters of the set \" bkmgtBKMGT\"
 183         specifying bytes, kilobytes, megabytes, gigabytes and
 184         terabytes respectively. The difference between the lower and
 185         the upper case variants is that the lower case specifiers
 186         select 1024-based units while the upper case specifiers use
 187         1000 as the basis.
 188
 189         The whitespace character is like \"b\", but a space character
 190         is printed instead of a unit.
 191
 192         Two more characters \"h\" and \"H\" (human-readable) are also
 193         available that choose an appropriate unit depending on the
 194         size of the number being printed.
 195
 196         An asterisk prepended to the unit specifier prevents the
 197         unit from being printed. This is useful mainly for feeding
 198         the output of adu to scripts that do not expect units.
 199
 200         In order to print a percent sign, use \"%%\". Moreover, adu
 201         understands \"\\n\" and \"\\t\" and outputs a newline and a
 202         tab character for these combinations respectively.
 203
 204         Examples:
 205                 Print size in gigabytes right-aligned:
 206                         \"%(size:r::G)\"
 207
 208                 As before, but use 5 char wide field:
 209                         \"%(size:r5::G)\"
 210
 211                 As before, but suppress trailing \"G\":
 212                         \"%(size:r5::*G)\"
 213
 214
 215         The following list contains all directives known to adu,
 216         together with their types, and for which modes each of
 217         them may be used.
 218
 219                 pw_name (string): user name. Available for user_list
 220                 and user_summary
 221
 222                 uid (id): user id. Available for user_list and
 223                 user_summary.
 224
 225                 files (count): number of files. Available everywhere.
 226
 227                 dirname (string): name of the directory. Available
 228                 for user_list and global_list.
 229
 230                 size (size): total size/ directory size. Available
 231                 everywhere.
 232
 233                 dirs (count): number of directories. Available
 234                 for user_summary and global_summary.
 235 "