X-Git-Url: http://git.tuebingen.mpg.de/?p=adu.git;a=blobdiff_plain;f=adu.ggo;h=643bbbff618728a865fd779aa29c363812b40f3c;hp=ab6e025a4ea2679f6dd75b4e1134df43a328569a;hb=2e24b91148dda8ea52b308a4b5e0ef08c0f11267;hpb=677f261ca511c8976e2945b34b9d08f06b0ce1d1 diff --git a/adu.ggo b/adu.ggo index ab6e025..643bbbf 100644 --- a/adu.ggo +++ b/adu.ggo @@ -1,10 +1,9 @@ -# Copyright (C) 2008 Andre Noll +# Copyright (C) 2008 Andre Noll # # Licensed under the GPL v2. For licencing details see COPYING. package "adu" -version "0.0.1" -purpose "advanced disk usage +purpose " adu creates a database containing disk usage statistics of a given directory. It allows to query that database to quickly retrieve @@ -15,71 +14,55 @@ usage patterns of subdirectories and/or files owned by a given user id. section "General options" ######################### -option "config-file" c -#~~~~~~~~~~~~~~~~~~~~~ -"(default='~/.adurc')" -string typestr="filename" -optional -details=" - Options may be given at the command line or in the - configuration file. As usual, if an option is given both at - the command line and in the configuration file, the command - line option takes precedence. - -" - -option "database-dir" d -#~~~~~~~~~~~~~~~~~~~~~~ -"directory containing the osl tables" -string typestr="path" -required -details=" - Full path to the directory containing the osl tables. This - directory must exist. It must be writable for the user running - adu in --create mode and readable in --select mode. - -" option "loglevel" l #~~~~~~~~~~~~~~~~~~ "Set loglevel (0-6)" int typestr="level" -default="3" +default="4" optional details=" Log messages are always written to stderr while normal output goes to stdout. Lower values mean more verbose logging. " -option "uid" u -#~~~~~~~~~~~~~ -"user id(s) to take into account" -string typestr="uid_spec" -optional -multiple -details=" - An uid specifier may be a single number, or a range of uids. - 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. - - This option may be given multiple times. An uid is taken into - account if it satisfies at least one --uid option. +defgroup "database" +#================== +groupdesc=" + There are two ways to specify a database directory. You can either + specify a full path using the database-dir option or a root path + using the database-root option. In the latter case, a directory + structure matching that of the base-dir argument is created + below the given full path. + + The advantage of using database-root is that the base-dir is + used to find the relevant database both in create and select mode + and you do not have to care for setting the database-dir explicitly. " +groupoption "database-dir" d +#~~~~~~~~~~~~~~~~~~~~~~~~~~~ +"directory containing the osl tables" +group="database" +string typestr="path" +details=" + Full path to the directory containing the osl tables. This + directory is created if it does not exist. It must be writable for the + user running adu in --create mode and readable in --select mode. +" -option "paths" p -#~~~~~~~~~~~~~~~ -"files to take into account" -string typestr="pattern" +groupoption "database-root" r +#~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +"directory containing directories containing the osl tables" +group="database" +string typestr="path" +default="/var/lib/adu" +dependon="base-dir" optional details=" - Shell wildcard pattern that must match a file in order to be - included in the database in --create mode or in the output - for --select mode. Only the part of the filename below the - base directory is matched against the pattern. The default - is to take all files into account. See fnmatch(3) for details. + Base path to the directory containing the osl tables. The real + database-dir is generated by appending base-dir. This + directory is created if it does not exist. When used in select + mode you have to specify the base-dir as well. " ############### @@ -89,10 +72,9 @@ section "Modes" defgroup "mode" #============== groupdesc=" - adu may started in one of two possible modes, each of which - corresponds to a different command line option. Exactly one - of these options must be given. - + adu may be started in one of three possible modes, each of + which corresponds to a different command line option. Exactly + one of these options must be given. " required @@ -101,10 +83,23 @@ groupoption "create" C "Create a new database" group="mode" details=" - Traverse the given directory and track disk user on a per-user - basis. Results are stored in N + 1 osl tables where N is - the number of uids that own at least one regular file in - that directory. + Traverse the given directory and track disk usage on a + per-user basis. Results are stored in N + 1 osl tables where + N is the number of uids that own at least one regular file + in that directory. +" + +groupoption "interactive" I +#~~~~~~~~~~~~~~~~~~~~~~~~~~ +"activate interactive mode" +group="mode" +details=" + In this mode, adu reads commands from stdin. This makes it + possible to run different select queries without opening the + underlying osl database for each query (which is expensive). + + In interactive mode, several subcommands are available, see + the end of this document. " groupoption "select" S @@ -112,8 +107,10 @@ groupoption "select" S "query a database previously created with --create" group="mode" details=" - This option prints statistics about matching subdirectories to - stdout. The output depends on the other options, see below. + This option prints statistics about matching subdirectories + to stdout, to an output file or pipes the output to a given + command, depending on the --output option. The output format + can be customized by specifying select options, see below. " ############################## @@ -124,40 +121,82 @@ option "base-dir" b #~~~~~~~~~~~~~~~~~~ "directory to traverse" string typestr="path" -dependon="create" -required +optional details=" The base directory to be traversed recursively. A warning message is printed for each subdirectory that could not be - read because of insufficient permission. These directories + read because of insufficient permissions. These directories will be ignored when computing statistics. " +option "one-file-system" x +#~~~~~~~~~~~~~~~~~~~~~~~~~ +"do not dive into other file systems" +flag off +dependon="create" +details=" + Skip directories that are on different file systems from the + one that the argument being processed is on. +" -############################## -section "Options for --select" -############################## +option "hash-table-bits" - +#~~~~~~~~~~~~~~~~~~~~~~~~~ +"specify the size of the uid hash table" +int typestr="num" +dependon="create" +default="10" +optional +details=" + Use a hash table of size 2^num for the uid entries. If more than + 2^num different uids own at least one regular file under base-dir, + the command fails. Increase this value if you have more than 1024 + users. Decreasing the value causes adu to use slightly less memory. +" -option "limit" L -#~~~~~~~~~~~~~~~ -"Limit output" -int typestr="num" -required -dependon="select" +option "bloom-filter-order" B +#~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +"use bloom filters for hard link detection" +int typestr="order" +dependon="create" +default="23" +optional +details=" + Allocate bloom filters of size 2^order bits. Each regular + file with hard link count greater than one is added to these + filters which allows to detect hard links on a per-user basis. + Greater values reduce the probability of false positives but + require more memory. + + Values less than 10 deactivate this feature so that no hard + links are being detected. +" + +option "num-bloom-filter-hash-functions" N +#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +"number of hash functions for the bloom filters" +int typestr="num" +dependon="create" +default="10" +optional details=" - Only print num lines of output. + Cause each entry which is added to the bloom filter to set + \"num\" bits of the bloom filter. " -option "units" U -#~~~~~~~~~~~~~~~ -"select numerical output format" -string typestr="format" +############################## +section "Options for --select" +############################## + +option "select-options" s +#~~~~~~~~~~~~~~~~~~~~~~~~~ +"Options for select mode" +string typestr="" optional +dependon="select" details=" - Print the number of files/directories and the sizes in - the given format. All sizes are output in these units: - (h)uman-readable, (b)ytes, (k)ilobytes, (m)egabytes, - (g)igabytes, (t)erabytes. Capitalise to use multiples - of 1000 (S.I.) instead of 1024. The default is \"h\", - i.e. human-readable. + This option takes a string whose content is another set of + options as described below. Select options may be specified + either directly in select mode, in which case you have use + quotes to prevent the select options from being interpreted + as adu options, or via the \"set\" command in interactive mode. "