NAME
 duc\[hy]nox \- index, query and graph disk usage
SYNOPSIS
 duc\[hy]nox <subcommand> [options]
DESCRIPTION
 Duc is a collection of tools for inspecting and visualizing disk usage.
 
 Duc maintains an indexed database of accumulated sizes of directories of your
 file system, and allows you to query this database with some tools, or create
 graphs to show you where your bytes are.

 Duc scales quite well, it has been tested on systems with more then 500 million
 files and several petabytes of storage. 
USAGE
 Duc comes with a command line tool called `duc\[hy]nox`, which is used to create,
 maintain and query the disk usage database.  run `duc\[hy]nox help` to get a list of
 available commands. `duc\[hy]nox help <subcommand>` describes the usage of a specific
 subcommand. Run `duc\[hy]nox help \[hy]\[hy]all` for an extensive list of all commands and
 their options.

 Duc allows any option to be placed either on the command line or in a
 configuration file. Options on the command line are preceded by a
 double-leading-dash (`\[hy]\[hy]option`), some options have a corresponding
 short option which can be used as well with a single leading dash. (`\[hy]o`)

 At startup duc tries to read its configuration from three locations in this
 particular order: `/etc/ducrc`, `~/.ducrc` and `./.ducrc`.

 A configuration file consists of sections and parameters. The section names
 correspond to the duc\[hy]nox subcommands for which the parameters in that
 section apply. A section begins with the name of the section in square
 brackets and continues until the next section begins.Sections contain
 parameters, one per line, which consist of a single option name for boolean
 flags, or a option name and a value for options which take a value. See the
 EXAMPLES section for an example of the configuration file format.
CREATING THE INDEX
 Duc needs an index file of the file system before it is able to show any
 information.  To create the index, run the `duc\[hy]nox index` command. For
 example, to create an index of your home directory run `duc\[hy]nox index ~`

    $ duc\[hy]nox index /usr
    Skipping lost+found: Permission denied
    Indexed 333823 files and 48200 directories, (35.0GB total)
    in 1 seconds

 The default location of the database is `$HOME/.duc.db`. To use a different
 database location, use the DUC_DATABASE environment variable or specify the
 database location with the \[hy]\[hy]database argument.

 You can run `duc\[hy] index` at any time later to rebuild the index.

 By default Duc indexes all directories it encounters during file system
 traversal traversal, including special file systems like /proc and /sys, and
 network file systems like NFS or Samba mounts. There are a few options to
 select what parts of your filesystem you want to include or exclude from the
 scan, check the documentation below for \[hy]\[hy]exclude, 
 \[hy]\[hy]fs\[hy]exclude and \[hy]\[hy]fs\[hy]include for more details.
QUERYING THE INDEX
 Duc has various subcommands for querying or exploring the index:

 * `duc\[hy]nox info` shows a list of available directory trees in the
    database, and the time and date of the last scan.

 * `duc\[hy]nox ls` lists all files and directories under the given path on
    the console.

 * `duc\[hy]nox ui` runs a ncurses based console user interface for exploring
    the file system usage
OPTIONS
 This section list all available subcommands and describes their usage and
 options.
Global options
 These options apply to all Duc subcommands:

  * \[hy]\[hy]debug:
    increase verbosity to debug level

  * \[hy]h, \[hy]\[hy]help:
    show help

  * \[hy]q, \[hy]\[hy]quiet:
    quiet mode, do not print any warning

  * \[hy]v, \[hy]\[hy]verbose:
    increase verbosity

  * \[hy]\[hy]version:
    output version information and exit

duc\[hy]nox help
 Options for command `duc\[hy]nox help [options]`:

  * \[hy]a, \[hy]\[hy]all:
    show complete help for all commands

duc\[hy] index
 The 'index' subcommand performs a recursive scan of the given paths on the
 filesystem and calculates the inclusive size of all directories. The results
 are written to the index, and can later be queried by one of the other
 duc\[hy]nox tools.

 Options for command `duc\[hy]nox index [options] PATH ...`:

  * \[hy]b, \[hy]\[hy]bytes:
    show file size in exact number of bytes

  * \[hy]d, \[hy]\[hy]database=VAL:
    use database file VAL

  * \[hy]e, \[hy]\[hy]exclude=VAL:
    exclude files matching VAL

  * \[hy]H, \[hy]\[hy]check\[hy]hard\[hy]links:
    count hard links only once. if two or more hard links point to the same
    file, only one of the hard links is displayed and counted

  * \[hy]f, \[hy]\[hy]force:
    force writing in case of corrupted db

  * \[hy]\[hy]fs\[hy]exclude=VAL
    exclude file system type VAL during indexing. VAL is a comma separated list
    of file system types as found in your systems fstab, for example ext3,
    ext4,dosfs

  * \[hy]\[hy]fs\[hy]include=VAL
    include file system type VAL during indexing. VAL is a comma separated
    list of file system types as found in your systems fstab, for example
    ext3,ext4,dosfs

  * \[hy]\[hy]hide\[hy]file\[hy]names:
    hide file names in index (privacy). the names of directories will be
    preserved, but the names of the individual files will be hidden

  * \[hy]m, \[hy]\[hy]max\[hy]depth=VAL:
    limit directory names to given depth. when this option is given
    duc\[hy]nox will traverse the complete file system, but will only the
    first VAL levels of directories in the database to reduce the size of the
    index

  * \[hy]x, \[hy]\[hy]one\[hy]file\[hy]system:
    skip directories on different file systems

  * \[hy]p, \[hy]\[hy]progress:
    show progress during indexing

  * \[hy]\[hy]uncompressed:
    do not use compression for database. Duc enables compression if the
    underlying database supports this. This reduces index size at the cost of
    slightly longer indexing time

duc\[hy]nox info
 Options for command `duc\[hy]nox info [options]`:

  * \[hy]a, \[hy]\[hy]apparent:
    show apparent instead of actual file size

  * \[hy]b, \[hy]\[hy]bytes:
    show file size in exact number of bytes

  * \[hy]d, \[hy]\[hy]database=VAL:
    select database file to use [~/.duc.db]

duc\[hy]nox ls
 The 'ls' subcommand queries the duc database and lists the inclusive size of
 all files and directories on the given path. If no path is given the current
 working directory is listed.

 Options for command `duc\[hy]nox ls [options] [PATH]`:

  * \[hy]a, \[hy]\[hy]apparent:
    show apparent instead of actual file size

  * \[hy]\[hy]ascii:
    use ASCII characters instead of UTF-8 to draw tree

  * \[hy]b, \[hy]\[hy]bytes:
    show file size in exact number of bytes

  * \[hy]F, \[hy]\[hy]classify:
    append file type indicator (one of */) to entries

  * \[hy]c, \[hy]\[hy]color:
    colorize output (only on ttys)

  * \[hy]\[hy]count
    show number of files instead of file size

  * \[hy]d, \[hy]\[hy]database=VAL:
    select database file to use [~/.duc.db]

  * \[hy]\[hy]dirs\[hy]only:
    list only directories, skip individual files

  * \[hy]l, \[hy]\[hy]levels=VAL:
    traverse up to ARG levels deep [4]

  * \[hy]R, \[hy]\[hy]recursive:
    list subdirectories in a recursive tree view

duc\[hy]nox xml
 Options for command `duc\[hy]nox xml [options] [PATH]`:

  * \[hy]d, \[hy]\[hy]database=VAL:
    select database file to use [~/.duc.db]

  * \[hy]x, \[hy]\[hy]exclude\[hy]files:
    exclude file from xml output, only include directories

  * \[hy]s, \[hy]\[hy]min_size=VAL:
    specify min size for files or directories

duc\[hy]nox cgi
 Options for command `duc\[hy]nox cgi [options] [PATH]`:

  * \[hy]a, \[hy]\[hy]apparent:
    Show apparent instead of actual file size

  * \[hy]b, \[hy]\[hy]bytes:
    show file size in exact number of bytes

  * \[hy]\[hy]count
    show number of files instead of file size

  * \[hy]\[hy]css\[hy]url=VAL:
    url of CSS style sheet to use instead of default CSS

  * \[hy]d, \[hy]\[hy]database=VAL:
    select database file to use [~/.duc.db]

  * \[hy]l, \[hy]\[hy]levels=VAL:
    draw up to ARG levels deep [4]

  * \[hy]\[hy]list:
    generate table with file list

  * \[hy]\[hy]tooltip:
    enable tooltip when hovering over the graph. enabling the tooltip will
    cause an asynchronous HTTP request every time the mouse is moved and can
    greatly increas the HTTP traffic to the web server

duc\[hy]nox ui
 The 'ui' subcommand queries the duc database and runs an interactive ncurses
 utility for exploring the disk usage of the given path. If no path is given the
 current working directory is explored.

 The following keys can be used to navigate and alter the file system:

    up, pgup, j:     move cursor up
    down, pgdn, k:   move cursor down
    left, backspace: go up to parent directory (..)
    right, enter:    descent into selected directory
    a:               toggle between actual and apparent disk usage
    b:               toggle between exact and abbreviated sizes
    c:               toggle between file size and file count
    h:               show help. press 'q' to return to the main
                     screen
    q, escape:       quit


 Options for command `duc\[hy]nox ui [options] [PATH]`:

  * \[hy]a, \[hy]\[hy]apparent:
    show apparent instead of actual file size

  * \[hy]b, \[hy]\[hy]bytes:
    show file size in exact number of bytes

  * \[hy]\[hy]count
    show number of files instead of file size

  * \[hy]c, \[hy]\[hy]color:
    colorize output

  * \[hy]\[hy]no\[hy]color
    do not use colors on terminal output

  * \[hy]d, \[hy]\[hy]database=VAL:
    select database file to use [~/.duc.db]

CGI INTERFACING
 The `duc\[hy]nox` binary has support for a rudimentary CGI interface,
 currently only tested with apache.  The CGI interface generates a simple HTML
 page with a list of indexed directories. If the option `\[hy]\[hy]list` is
 given, a list of top sized files/dirs is written.

 Configuration is done by creating a simple shell script as .cgi in a directory
 which is configured for CGI execution by your web server (usually 
 `/usr/lib/cgi-bin`). The shell script should simply start duc\[hy]nox, and
 pass the location of the database to navigate.

 An example duc.cgi script would be

    #!/bin/sh
    /usr/bin/duc\[hy]nox cgi -d /home/jenny/.duc.db

    * Make sure the database file is readable by the user (usually
      www\[hy]data)
    * Debugging is best done by inspecting the web server's error log
    * Make sure the .cgi script has execute permissions
      (`chmod +x duc.cgi`)

 Some notes:

    * The HTML page is generated with a simple embedded CSS style sheet. If the
      style is not to your liking you can provide an external CSS url with the
      \[hy]\[hy]css\[hy]url option which will then be used instead of the
      embedded style definition.

    * Add the option \[hy]\[hy]list to generate a table of top sized files and
      directories in the HTML page.

 The current CGI configuration is not very flexible, nor secure. It is not
 advised to run the CGI from public reachable web servers, use at your own risk.

A NOTE ON FILE SIZE AND DISK USAGE
 The concepts of 'file size' and 'disk usage' can be a bit confusing. Files on
 disk have an apparent size, which indicates how much bytes are in the file from
 the users point of view; this is the size reported by tools like `ls \[hy]l`.
 The apparent size can be any number, from 0 bytes up to several TB.  The
 actual number of bytes which are used on the filesystem to store the file can
 differ from this apparent size for a number of reasons: disks store data in
 blocks, which cause files to always take up a multiple of the block size,
 files can have holes ('sparse' files), and other technical reasons. This
 number is always a multiple of 512, which means that the actual size used for
 a file is almost always a bit more then its apparent size.

 Duc has two modes for counting file sizes:

 \[hy] `apparent size`: this is the size as reported by `ls`. This number
 indicates the file length, which is usually smaller then the actual disk
 usage. 

 \[hy] `actual size`: this is the size as reported by `du` and `df`. The
 actual file size tells you how much disk is actually used by a file, and is
 always a multiple of 512 bytes. 

 The default mode used by duc\[hy]nox is to use the 'actual size'. Most
 duc\[hy]nox commands to report disk usage (`duc\[hy]nox ls`, etc) have an
 option to change between these two modes (usually the `\[hy]a`).

EXAMPLES
 Index the /usr directory, writing to the default database location ~/.duc.db:

    $ duc\[hy]nox index /usr

 List all files and directories under /usr/local, showing relative file sizes
 in a graph:

    $ duc\[hy]nox ls \[hy]Fg /usr/local
      4.7G lib/                 [+++++++++++++++++++++++++++++++++++++]
      3.1G share/               [+++++++++++++++++++++++++            ]
      2.7G src/                 [+++++++++++++++++++++                ]
    814.9M bin/                 [++++                                 ]
    196.6M include/             [+                                    ]
     66.6M x86_64-w64-mingw32/  [                                     ]
     59.9M local/               [                                     ]
     38.8M i686-w64-mingw32/    [                                     ]
     20.3M sbin/                [                                     ]
     13.6M lib32/               [                                     ]
     13.3M libx32/              [                                     ]

 or use the \[hy]R  options for the tree view:

    $ duc\[hy]nox ls \[hy]RF /etc/logcheck
     24.0K `+\[hy] ignore.d.server/
      4.0K  |  `+\[hy] hddtemp 
      4.0K  |   |\[hy] ntpdate 
      4.0K  |   |\[hy] lirc 
      4.0K  |   |\[hy] rsyslog 
      4.0K  |   `\[hy] libsasl2\[hy]modules 
      8.0K  |\[hy] ignore.d.workstation/
      4.0K  |   `\[hy] lirc 
      8.0K  `\[hy] ignore.d.paranoid/
      4.0K      `\[hy] lirc 

 The following sample configuration file defines default parameters for the
 `duc\[hy]nox ls` command and defines a global option to configure the
 database path which is used by all subcommands
 
    [global]
    database /var/cache/duc.db
 
    [ls]
    recursive
    classify
    color
    
    [ui]
    color
FREQUENTLY ASKED QUESTIONS
 What does the error \'Database version mismatch mean?

 The layout of the index database sometimes changes when new features are implemented\. When you get this error you have probably upgraded to a newer version\. Just remove the old database file and rebuild the index.

 Duc crashes with a segmentation fault, is it that buggy?

 By default Duc uses the Tokyocabinet database backend\. Tokyocabinet is pretty fast, stores the database in a single file and has nice compression support to keep the database small\. Unfortunately, it is not always robust and sometimes chokes on corrupt database files\. Try to remove the database and rebuild the index\. If the error persists contact the authors.

FILES
 At startup duc\[hy]nox tries to read its configuration from three locations
 in this particular order: `/etc/ducrc`, `~/.ducrc` and `./.ducrc`.

 Duc mainains an index of scanned directories, which defaults to ~/.duc.db.
 All tools take the \[hy]d/\[hy]\[hy]database option to override the database
 path.
AUTHORS
 * Ico Doornekamp <duc@zevv.nl>
 * John Stoffel <john@stoffel.org>

 Other contributers can be found in the Git log at GitHub.

 This manual page was adapt by Herbert Parentes Fortes Neto 
 <hpfn@ig.com.br> from the duc manpage of the duc project for duc-nox 
 package of the Debian project (but may be used by others)
LICENSE
 Duc is free software; you can redistribute it and/or modify it under the terms
 of the GNU General Public License as published by the Free Software Foundation;
 version 2 dated June, 1991. Duc is distributed in the hope that it will be
 useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
 License for more details.
