DU(1)

NAME
du - Summarizes disk usage.

SYNTAX
du [ -abCdfFhiklLstu ] [ -B size ] [ -U user ] [ -c n,... ] [ name ... ]

DESCRIPTION
du calculates the disk usage of each name give on the command line. If name is a directory then it is scanned recursively and the accumulated disk usage of its contents is reported. If no name is specified on the command line, then du reports the usage at the current directory.

By default, the disk usage for a directory includes not only the usage of everything in that directory, but also the usage of everything below it. This means, for example, the usage reported for the root directory ``/'' is the disk usage for the entire system.

By default, only the disk usage for directories encountered is printed. The disk usage for other filesystem entries for other filesystem entries (regular files, etc.) is accumulated but not displayed. This means that if the name specified on the command line is not a directory, then no output will be produced. This behavior may be modified with the -a and -s options.

The disk usage is reported as a number of blocks. The size of these blocks is site-specific, but is usually either 512 bytes or 1024 bytes. Use the -h option to see how your version of du is configured. There are a number of options that will report results with a different block size.

One possible source of confusion is that the word ``block'' can mean several different things. The du program reports disk usage in chunks called ``blocks''. The Unix filesystem stores data to disk in chunks also called ``blocks''. The size of the du reporting blocks and the filesystem storage blocks are not necessarily related, and almost always are different. (Historically this is not true, but it these days.) Although du performs all of its internal calculations based upon the physical filesystem block size, all values are scaled to a consistent reporting block size prior to printing. If, for example, a 1000 byte file is stored on a 1K filesystem, it will require one data block. If you look at this file with du set to a 512-byte reporting block size, it will say this file uses two blocks.

By default, du will count the disk usage of a file with multiple (hard) links only the first time the file is encountered. Several options are available to modify this behavior.

The disk usage calculated by du takes into account the ``indirect block'' overhead of very large files. The usage for such files will be the space used by the file's data blocks as well as the overhead from any indirect address blocks.

The following options modify the behavior of du:

-a  The usage of all items is reported. Normally du displays only the usage at directories. When this option is specified, the usage of all filesystem items (regular files, directories, etc.) encountered is displayed.

-b  Report disk usage in number of bytes; equivalent to ``-B 1''. Note that disk usage in bytes is not the same thing as file size. A one byte file residing on a 1K filesystem, for example, has a disk usage of 1024 bytes and not 1 byte.

-B size
    The usage is reported in terms of size byte blocks instead of the default. (The -h option will tell you what this default value is.) A size of zero means use the physical filesystem disk block size as the reporting block size. Note that this value is system dependant, and can vary across different filesystems upon the machine.

-c n,...
    The disk usage will be broken down by age and displayed in columns, one column for each value in the list. Each column shows the usage by entries n days or older. For example, the command:

        du -c 0,7,30

    displays the usage in three columns: the total usage (zero days or older), the usage by entries a week or older, and the usage by entries a month or older. The default behavior of du is equivalent to ``-c 0''. The age is based upon an entry's time of last modification.

-C  Displays a count of entries as well as the disk usage of those entries. The count includes only those items that participated in the disk usage calculation. If, for example, the -u options (to skip multiply-linked files) is also specified, multiply-linked files will be omitted not only from the usual usage calculations, but also the file count requested by the -C option.

-f  This option will prevent du from processing a directory (either scanning its contents or descending into it) if that would result in crossing a mount point, i.e. onto a different filesystem.

-F  This option will prevent du from processing a directory (either scanning its contents or descending into it) if that would result in crossing a remote mount point, i.e. onto a network filesystem. This differs from the -f option in that local filesystem mount points will be traversed when -F is specified.

-h  Displays a help summary. Will also indicate the default size of the disk blocks used in reporting.

-i  Do not accumulate subdirectories' usage into the parent directory's usage. If, for example, you run:

        du -i comp/text

    then the disk usage for a subdirectory comp/text/desktop will not be accumulated into the disk usage of comp/text.

-k  Report disk usage in number of kilobytes; equivalent to ``-B 1024''.

-l  Normally du will count a file with multiple (hard) links only once. With this option, du will count the file each time is is encountered.

-L  Count each instance of a multiply (hard) linked regular file, but average the usage over each of the links. If, for example, a 7 block file is linked to the names comp/unix/questions/13, comp/unix/programmer/12, and alt/flame/33, then du will count the file three times with usages of 3, 2, and 2 blocks, respectively.

-r  Traditionally, du does it's work silently and will not report any errors, e.g. a name specified on the command line doesn't exist, you don't have permissions to check a directory, etc. This version of du normally prints these errors to the stderr output. It can be configured, however, to be compatible with the traditional behavior and suppress error messages. If this is done, then the -r option will be available to enable these error messages. The -h option will tell you whether or not this option has been enabled.

-s  Normally du reports the disk usage for each directory it encounters. This option suppresses that information and instead reports just a total usage for each of the items specified on the command line.

-t  A grand total of all items specified on the command line will be accumulated and displayed. For example, the command

        du -st /usr/man/man*

    will show the disk usage of each manual page source directory, plus a grand total of these directories.

-u  Causes multiply linked files to be skipped entirely and omitted from the usage statistics.

-U user
    Only entries owned by the indicated user will be counted. Either a username or UID number may be specified.

SEE ALSO
df(1), dusort(1L), ls(1), mount(8), stat(2)

BUGS
Unless your system provides an st_blocks in the inode, du will report files with holes in them (sparse files) incorrectly.

Although multiply linked files are normally counted only once, you can't be sure under which directory they will be accumulated. Note that unlike some implementations of du, the only limit to the number of linked files that can be handled is set by available system memory.

If the actual filesystem block size is not an integral multiple of the reporting block size (-B) then roundoff errors will occur in the translation. du will round up in this case.

The -U option can interract with others in strange ways. For example, when combined with -a, all files will be displayed, but ones not owned by the specified user will be shown as zero sized.

If two or more directory trees specified on the command line are not disjoint, then the usage calculations will be corrupted by the presence of hard links. If, for example, /usr/foo/bar and /usr/foo/baz are links to the same file, then the command ``du /usr/foo /usr'' will report the usage of directory /usr/foo twice, and the two values will not agree.

AUTHOR
Chip Rosenthal
Unicom Systems Development, Inc.
<chip@chinacat.Unicom.COM>

Copyright 1990-1993, Unicom Systems Development, Inc. All rights reserved.

You are granted a non-exclusive license to use, modify, copy, and distribute this software subject to the following conditions. You must ensure all copyright notices and license notices remain intact in the copies you use or distribute. Any modifications, other than those in the areas clearly reserved for site-specific modifications, must be marked as such. This software is provided "as is". No warranties have been expressed or implied. Since this license was provided to you at no charge, you must assume the entire risk and liability for all use of this software.