X-Git-Url: http://git.tuebingen.mpg.de/?p=adu.git;a=blobdiff_plain;f=select.ggo;h=d7f8c9388b3ac4d6509cb5e7e0719079b65feba7;hp=e8a5f95dffa2f0fe8d0fea2223d9599a296c38b6;hb=2e24b91148dda8ea52b308a4b5e0ef08c0f11267;hpb=de525e7c5b6592b41f8681f919d5d53406801861 diff --git a/select.ggo b/select.ggo index e8a5f95..d7f8c93 100644 --- a/select.ggo +++ b/select.ggo @@ -1,50 +1,118 @@ +option "user" u +#~~~~~~~~~~~~~~ +"users to take into account" +string typestr="user_name" +optional +multiple +details=" + This option may be given multiple times in which case all given + user names are considered admissible. See also --uid below. +" -option "uid" u +option "uid" U #~~~~~~~~~~~~~ "user id(s) to take into account" string typestr="uid_spec" optional details=" - An uid specifier may be a single number, or a range of uids. + An uid specifier may be a single uid, a range of uids, + or a comma-separated list of single uids or ranges. Example: - --uid 42 # only consider uid 42 - --uid 42- # only consider uids greater or equal than 42 - --uid 23-42 # only consider uids between 23 and 42, inclusively. - --uid 23-42,666-777,88 # consider uids 23-42, 666-777 and 88. + Only consider uid 42: + --uid 42 + + Only consider uids greater or equal than 42: + --uid 42- + + Only consider uids between 23 and 42, inclusively: + --uid 23-42 + + Consider uids 23-42, 666-777 and 88: + --uid 23-42,666-777,88 + + If no --user option is given and also --uid option is not given + (the default), all users are taken into account. " -option "limit" L +option "limit" l #~~~~~~~~~~~~~~~ "Limit output" -int typestr="num" +int typestr="num" default="-1" optional details=" Only print num lines of output. If negative (the default), - print all lines. + print all lines. This option is honored in all select modes + except global_summary (which outputs only one single line). " -option "no-headers" - -#~~~~~~~~~~~~~~~~~~~~ -"supress descriptions for listings/summaries" -flag off +option "pattern" p +#~~~~~~~~~~~~~~~~~ +"only consider matching directories" +string typestr="regex" +optional details=" - This is mostly useful to feed the output of adu to scripts. + Regular expression that must match the directory name for + the directory to be considered for the output of the query. + See regex(7) for details. + + Depending on whether --print-base-dir is given, the absolute + directory name or only the part of the directory name below + the base directory is matched against \"regex\". + + If this option is not given (the default) all directories + are taken into account. + + If \"regex\" starts with '!', directories are matched against + the remaining part of \"regex\" and the sense of matching is + reversed. +" + +option "header" H +#~~~~~~~~~~~~~~~~ +"use a customized header for listings/summaries" +string typestr="string" +optional +details=" + This option can be used to print any string instead of the + default header line (which depends on the selected mode). + + In user_list mode the header is a format string which allows + to include the uid and the user name in the header. See the + --format option for more details. + + It is possible to set this to the empty string to suppress + the header completely. This is mostly useful to feed the + output to scripts. +" + +option "trailer" T +#~~~~~~~~~~~~~~~~~ +"use a customized trailer for listings/summaries" +string typestr="string" +optional +default="" +details=" + This option can be used to print any string at the end of + the query output. + + In user_list mode the trailer is a format string with the + same semantics like the header string. " option "select-mode" m #~~~~~~~~~~~~~~~~~~~~~ "How to print the results of the query" enum typestr="" -values="global_list","global_summary","user_list","user_summary" -default="global_list" +values="user_summary","user_list","global_summary","global_list" +default="user_summary" optional details=" - global_list: List of directories, regardless of owner. - global_summary: Only print totals. + user_summary: Print totals for each admissible uid. user_list: Print a list for each admissible uid. - user_summary Print totals for each admissible uid. + global_summary: Only print totals. + global_list: List of directories, regardless of owner. " option "list-sort" s @@ -62,11 +130,36 @@ details=" option "output" o #~~~~~~~~~~~~~~~~ "file to write output to" -string typestr="" +string typestr="path" optional default="-" details=" - If empty, or not given, use stdout. + This option is only useful in interactive mode. If stdin is redirected + from a script, and the script contains several queries one can use + this option to let each query write its output to a different file. + + If the option is not given, or its argument is either \"-\" or the + empty string, stdout is assumed. The following conventions cause the + output to be written in a different way: + + \"path\" may be prepended by '>' which instructs adu to truncate + the output file to length zero. If \"path\" does not start with + '>' and \"path\" already exists, the query is aborted. Otherwise, + the file is created and truncated. The output file name \">\" is + considered invalid. + + If the first two characters of \"path\" are '>', the output file + (given by removing the leading \">>\" from \"path\") is opened in + append mode. It is no error if the output file does not exist. However, + as above the output file name \">>\" is considered invalid. + + If the first character of \"path\" is '|', a pipe is created and the + rest of \"path\" is executed with stdin redirected to the reading + end of the pipe while the query output is written to the writing end + of the pipe. Again, specifying only \"|\" is considered invalid and + causes an error. + + See the manual page for examples. " option "user-summary-sort" - @@ -97,13 +190,14 @@ option "format" f string typestr="" optional details=" + A string that specifies how the output of the select query is - goint to be formated. Depending on the chosen select-mode, + going to be formated. Depending on the chosen select-mode, several conversion specifiers are available and a different default value for this option applies. adu knows four different types of directives: string, id, - count and size. These are explained in more detail below. + count and size. These are explained in more detail below. The general syntax for string and id directives is %(name:a:w) where \"name\" is the name of the directive, \"a\" specifies @@ -113,24 +207,28 @@ details=" The alignment specifier is a single character: Either \"l\", \"r\", or \"c\" may be given to specify left, right and centered alignment respectively. The with specifier is a - positive integer. Both \"a\" and \"w\" are optional. + positive integer. Both \"a\" and \"w\" are optional. - A string directive supported by adu is \"dirname\" which is - subsitituted by the name of the directory. It is available + One string directive supported by adu is \"dirname\" which is + substituted by the name of the directory. It is available if either user_list or global_list mode was selected via --select-mode. Examples: + Print dirname without any padding: - \"%(diname)\" # print dirname without any padding - \"%(dirname:c:20)\" # center dirname in a 20 chars wide field + \"%(diname)\" - The other two types of directives, count and size, are used - for numbers. The syntax for these is %(name:a:w:u). The \"a\" - and the \"w\" specifier have the same meaning as for the string - and id directives. The additional \"u\" specifier selects a unit - in which the number that corresponds to the directive should - be formated. All three specifiers are optional. + Center dirname in a 20 chars wide field: + + \"%(dirname:c:20)\" + + The count and size directives are used for non-negative + numbers. The syntax for these is %(name:a:w:u). The \"a\" and + the \"w\" specifiers have the same meaning as for the string + and id directives. The additional \"u\" specifier selects a + unit in which the number that corresponds to the directive + should be formated. All three specifiers are optional. Possible units are the characters of the set \" bkmgtBKMGT\" specifying bytes, kilobytes, megabytes, gigabytes and @@ -151,34 +249,39 @@ details=" the output of adu to scripts that do not expect units. In order to print a percent sign, use \"%%\". Moreover, adu - understands \"\n\" and \"\t\" and outputs a newline and a + understands \"\\n\" and \"\\t\" and outputs a newline and a tab character for these combinations respectively. Examples: + Print size in gigabytes right-aligned: + \"%(size:r::G)\" + + As before, but use 5 char wide field: + \"%(size:r5::G)\" + + As before, but suppress trailing \"G\": + \"%(size:r5::*G)\" + + + The following list contains all directives known to adu, + together with their types, and for which modes each of + them may be used. + + pw_name (string): user name. Available for user_list, + user_summary and for the header in user_list mode. + + uid (id): user id. Available for user_list, + user_summary and for the header in user_list mode. + + files (count): number of files. Available for all + modes. + + dirname (string): name of the directory. Available + for user_list and global_list. + + size (size): total size/ directory size. Available + for all modes. - \"%(size:r::G)\" # print size in gigabytes right-aligned - \"%(size:r5::G)\" # as before, but use 5 char wide field - \"%(size:r5::*G)\" # as before, but supress trailing \"G\" - - List of directives and types known to adu, together with their types: - - name type meaning - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - pw_name string user name - uid id user id - files count number of files - dirname string name of the directory - size size total size/ directory size - dirs count number of directories - - Not all directives are available for each mode: - - name available in directives - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - pw_name user_list, user_summary - uid user_list, user_summary - files everywhere - dirname user_list, global_list - size everywhere - dirs suer_summary, global_summary + dirs (count): number of directories. Available + for user_summary and global_summary. "