diff options
Diffstat (limited to 'man1p/du.1p')
| -rw-r--r-- | man1p/du.1p | 244 |
1 files changed, 244 insertions, 0 deletions
diff --git a/man1p/du.1p b/man1p/du.1p new file mode 100644 index 000000000..3f34004f8 --- /dev/null +++ b/man1p/du.1p @@ -0,0 +1,244 @@ +.\" 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 . |