path: root/man1p/du.1p

.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "DU" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" du 
.SH NAME
du \- estimate file space usage
.SH SYNOPSIS
.LP
\fBdu\fP \fB[\fP\fB-a | -s\fP\fB][\fP\fB-kx\fP\fB][\fP\fB-H | -L\fP\fB][\fP\fIfile\fP
\fB\&...\fP\fB]\fP\fB\fP
.SH DESCRIPTION
.LP
By default, the \fIdu\fP utility shall write to standard output the
size of the file space allocated to, and the size of the
file space allocated to each subdirectory of, the file hierarchy rooted
in each of the specified files. By default, when a symbolic
link is encountered on the command line or in the file hierarchy,
\fIdu\fP shall count the size of the symbolic link (rather than
the file referenced by the link), and shall not follow the link to
another portion of the file hierarchy. The size of the file
space allocated to a file of type directory shall be defined as the
sum total of space allocated to all files in the file hierarchy
rooted in the directory plus the space allocated to the directory
itself.
.LP
When \fIdu\fP cannot \fIstat\fP() files or \fIstat\fP() or read directories,
it shall report an error condition and the final exit status is
affected. Files with multiple links shall be counted and written for
only one entry. The directory entry that is selected in the
report is unspecified. By default, file sizes shall be written in
512-byte units, rounded up to the next 512-byte unit.
.SH OPTIONS
.LP
The \fIdu\fP utility shall conform to the Base Definitions volume
of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
.LP
The following options shall be supported:
.TP 7
\fB-a\fP
In addition to the default output, report the size of each file not
of type directory in the file hierarchy rooted in the
specified file. Regardless of the presence of the \fB-a\fP option,
non-directories given as \fIfile\fP operands shall always be
listed.
.TP 7
\fB-H\fP
If a symbolic link is specified on the command line, \fIdu\fP shall
count the size of the file or file hierarchy referenced by
the link.
.TP 7
\fB-k\fP
Write the files sizes in units of 1024 bytes, rather than the default
512-byte units.
.TP 7
\fB-L\fP
If a symbolic link is specified on the command line or encountered
during the traversal of a file hierarchy, \fIdu\fP shall
count the size of the file or file hierarchy referenced by the link.
.TP 7
\fB-s\fP
Instead of the default output, report only the total sum for each
of the specified files.
.TP 7
\fB-x\fP
When evaluating file sizes, evaluate only those files that have the
same device as the file specified by the \fIfile\fP
operand.
.sp
.LP
Specifying more than one of the mutually-exclusive options \fB-H\fP
and \fB-L\fP shall not be considered an error. The last
option specified shall determine the behavior of the utility.
.SH OPERANDS
.LP
The following operand shall be supported:
.TP 7
\fIfile\fP
The pathname of a file whose size is to be written. If no \fIfile\fP
is specified, the current directory shall be used.
.sp
.SH STDIN
.LP
Not used.
.SH INPUT FILES
.LP
None.
.SH ENVIRONMENT VARIABLES
.LP
The following environment variables shall affect the execution of
\fIdu\fP:
.TP 7
\fILANG\fP
Provide a default value for the internationalization variables that
are unset or null. (See the Base Definitions volume of
IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables
for
the precedence of internationalization variables used to determine
the values of locale categories.)
.TP 7
\fILC_ALL\fP
If set to a non-empty string value, override the values of all the
other internationalization variables.
.TP 7
\fILC_CTYPE\fP
Determine the locale for the interpretation of sequences of bytes
of text data as characters (for example, single-byte as
opposed to multi-byte characters in arguments).
.TP 7
\fILC_MESSAGES\fP
Determine the locale that should be used to affect the format and
contents of diagnostic messages written to standard
error.
.TP 7
\fINLSPATH\fP
Determine the location of message catalogs for the processing of \fILC_MESSAGES
\&.\fP 
.sp
.SH ASYNCHRONOUS EVENTS
.LP
Default.
.SH STDOUT
.LP
The output from \fIdu\fP shall consist of the amount of space allocated
to a file and the name of the file, in the following
format:
.sp
.RS
.nf

\fB"%d %s\\n", <\fP\fIsize\fP\fB>, <\fP\fIpathname\fP\fB>
\fP
.fi
.RE
.SH STDERR
.LP
The standard error shall be used only for diagnostic messages.
.SH OUTPUT FILES
.LP
None.
.SH EXTENDED DESCRIPTION
.LP
None.
.SH EXIT STATUS
.LP
The following exit values shall be returned:
.TP 7
\ 0
Successful completion.
.TP 7
>0
An error occurred.
.sp
.SH CONSEQUENCES OF ERRORS
.LP
Default.
.LP
\fIThe following sections are informative.\fP
.SH APPLICATION USAGE
.LP
None.
.SH EXAMPLES
.LP
None.
.SH RATIONALE
.LP
The use of 512-byte units is historical practice and maintains compatibility
with \fIls\fP
and other utilities in this volume of IEEE\ Std\ 1003.1-2001. This
does not mandate that the file system itself be based on
512-byte blocks. The \fB-k\fP option was added as a compromise measure.
It was agreed by the standard developers that 512 bytes
was the best default unit because of its complete historical consistency
on System V (\fIversus\fP the mixed 512/1024-byte usage
on BSD systems), and that a \fB-k\fP option to switch to 1024-byte
units was a good compromise. Users who prefer the 1024-byte
quantity can easily alias \fIdu\fP to \fIdu\fP \fB-k\fP without breaking
the many historical scripts relying on the 512-byte
units.
.LP
The \fB-b\fP option was added to an early proposal to provide a resolution
to the situation where System V and BSD systems give
figures for file sizes in \fIblocks\fP, which is an implementation-defined
concept. (In common usage, the block size is 512 bytes
for System V and 1024 bytes for BSD systems.) However, \fB-b\fP was
later deleted, since the default was eventually decided as
512-byte units.
.LP
Historical file systems provided no way to obtain exact figures for
the space allocation given to files. There are two known
areas of inaccuracies in historical file systems: cases of \fIindirect
blocks\fP being used by the file system or \fIsparse\fP
files yielding incorrectly high values. An indirect block is space
used by the file system in the storage of the file, but that
need not be counted in the space allocated to the file. A \fIsparse\fP
file is one in which an \fIlseek\fP() call has been made to a position
beyond the end of the file and data has subsequently
been written at that point. A file system need not allocate all the
intervening zero-filled blocks to such a file. It is up to the
implementation to define exactly how accurate its methods are.
.LP
The \fB-a\fP and \fB-s\fP options were mutually-exclusive in the original
version of \fIdu\fP. The POSIX Shell and Utilities
description is implied by the language in the SVID where \fB-s\fP
is described as causing "only the grand total" to be reported.
Some systems may produce output for \fB-sa\fP, but a Strictly Conforming
POSIX Shell and Utilities Application cannot use that
combination.
.LP
The \fB-a\fP and \fB-s\fP options were adopted from the SVID except
that the System V behavior of not listing non-directories
explicitly given as operands, unless the \fB-a\fP option is specified,
was considered a bug; the BSD-based behavior (report for
all operands) is mandated. The default behavior of \fIdu\fP in the
SVID with regard to reporting the failure to read files (it
produces no messages) was considered counter-intuitive, and thus it
was specified that the POSIX Shell and Utilities default
behavior shall be to produce such messages. These messages can be
turned off with shell redirection to achieve the System V
behavior.
.LP
The \fB-x\fP option is historical practice on recent BSD systems.
It has been adopted by this volume of
IEEE\ Std\ 1003.1-2001 because there was no other historical method
of limiting the \fIdu\fP search to a single file
hierarchy. This limitation of the search is necessary to make it possible
to obtain file space usage information about a file
system on which other file systems are mounted, without having to
resort to a lengthy \fIfind\fP and \fIawk\fP script.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIls\fP , the System Interfaces volume of IEEE\ Std\ 1003.1-2001,
\fIstat\fP()
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .