df.1p (9804B)
- '\" et
- .TH DF "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- This manual page is part of the POSIX Programmer's Manual.
- The Linux implementation of this interface may differ (consult
- the corresponding Linux manual page for details of Linux behavior),
- or the interface may not be implemented on Linux.
- .\"
- .SH NAME
- df
- \(em report free disk space
- .SH SYNOPSIS
- .LP
- .nf
- df \fB[\fR-k\fB] [\fR-P|-t\fB] [\fIfile\fR...\fB]\fR
- .fi
- .SH DESCRIPTION
- The
- .IR df
- utility shall write the amount of available space
- and file slots
- for file systems on which the invoking user has appropriate read
- access. File systems shall be specified by the
- .IR file
- operands; when none are specified, information shall be written for all
- file systems. The format of the default output from
- .IR df
- is unspecified, but all space figures are reported in 512-byte units,
- unless the
- .BR \-k
- option is specified. This output shall contain at least the file system
- names, amount of available space on each of these file systems,
- and, if no options other than
- .BR \-t
- are specified, the number of free file slots, or
- .IR inode s,
- available; when
- .BR \-t
- is specified, the output shall contain the total allocated space as well.
- .SH OPTIONS
- The
- .IR df
- utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 12.2" ", " "Utility Syntax Guidelines".
- .P
- The following options shall be supported:
- .IP "\fB\-k\fP" 10
- Use 1\|024-byte units, instead of the default 512-byte units, when
- writing space figures.
- .IP "\fB\-P\fP" 10
- Produce output in the format described in the STDOUT section.
- .IP "\fB\-t\fP" 10
- Include total allocated-space figures in the output.
- .SH OPERANDS
- The following operand shall be supported:
- .IP "\fIfile\fR" 10
- A pathname of a file within the hierarchy of the desired file system.
- If a file other than a FIFO, a regular file, a directory,
- or a special file representing the device containing the file system
- (for example,
- .BR /dev/dsk/0s1 )
- is specified, the results are unspecified. If the
- .IR file
- operand names a file other than a special file containing a file
- system,
- .IR df
- shall write the amount of free space in the file system containing the
- specified
- .IR file
- operand.
- Otherwise,
- .IR df
- shall write the amount of free space in that file system.
- .SH STDIN
- Not used.
- .SH "INPUT FILES"
- None.
- .SH "ENVIRONMENT VARIABLES"
- The following environment variables shall affect the execution of
- .IR df :
- .IP "\fILANG\fP" 10
- Provide a default value for the internationalization variables that are
- unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 8.2" ", " "Internationalization Variables"
- for the precedence of internationalization variables used to determine
- the values of locale categories.)
- .IP "\fILC_ALL\fP" 10
- If set to a non-empty string value, override the values of all the
- other internationalization variables.
- .IP "\fILC_CTYPE\fP" 10
- 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).
- .IP "\fILC_MESSAGES\fP" 10
- .br
- Determine the locale that should be used to affect the format and
- contents of diagnostic messages written to standard error and
- informative messages written to standard output.
- .IP "\fINLSPATH\fP" 10
- Determine the location of message catalogs for the processing of
- .IR LC_MESSAGES .
- .SH "ASYNCHRONOUS EVENTS"
- Default.
- .SH STDOUT
- When both the
- .BR \-k
- and
- .BR \-P
- options are specified, the following header line shall be written (in
- the POSIX locale):
- .sp
- .RS 4
- .nf
- "Filesystem 1024-blocks Used Available Capacity Mounted on\en"
- .fi
- .P
- .RE
- .P
- When the
- .BR \-P
- option is specified without the
- .BR \-k
- option, the following header line shall be written (in the POSIX
- locale):
- .sp
- .RS 4
- .nf
- "Filesystem 512-blocks Used Available Capacity Mounted on\en"
- .fi
- .P
- .RE
- .P
- The implementation may adjust the spacing of the header line and the
- individual data lines so that the information is presented in orderly
- columns.
- .P
- The remaining output with
- .BR \-P
- shall consist of one line of information for each specified
- file system. These lines shall be formatted as follows:
- .sp
- .RS 4
- .nf
- "%s %d %d %d %d%% %s\en", <\fIfile system name\fR>, <\fItotal space\fR>,
- <\fIspace used\fR>, <\fIspace free\fR>, <\fIpercentage used\fR>,
- <\fIfile system root\fR>
- .fi
- .P
- .RE
- .P
- In the following list, all quantities expressed in 512-byte units
- (1\|024-byte when
- .BR \-k
- is specified) shall be rounded up to the next higher unit. The fields
- are:
- .IP "<\fIfile\ system\ name\fP>" 10
- .br
- The name of the file system, in an implementation-defined format.
- .IP "<\fItotal\ space\fP>" 10
- The total size of the file system in 512-byte units. The exact meaning
- of this figure is implementation-defined, but should include
- <\fIspace\ used\fP>, <\fIspace\ free\fP>, plus any space reserved by
- the system not normally available to a user.
- .IP "<\fIspace\ used\fP>" 10
- The total amount of space allocated to existing files in the
- file system, in 512-byte units.
- .IP "<\fIspace\ free\fP>" 10
- The total amount of space available within the file system for the
- creation of new files by unprivileged users, in 512-byte units. When
- this figure is less than or equal to zero, it shall not be possible to
- create any new files on the file system without first deleting others,
- unless the process has appropriate privileges. The figure written may
- be less than zero.
- .IP "<\fIpercentage\ used\fP>" 10
- .br
- The percentage of the normally available space that is currently
- allocated to all files on the file system. This shall be calculated
- using the fraction:
- .RS 10
- .sp
- .RS 4
- .nf
- <\fIspace used\fR>/( <\fIspace used\fR>+ <\fIspace free\fR>)
- .fi
- .P
- .RE
- .P
- expressed as a percentage. This percentage may be greater than 100 if
- <\fIspace\ free\fP> is less than zero. The percentage value shall be
- expressed as a positive integer, with any fractional result causing it
- to be rounded to the next highest integer.
- .RE
- .IP "<\fIfile\ system\ root\fP>" 10
- .br
- The directory below which the file system hierarchy appears.
- .P
- The output format is unspecified when
- .BR \-t
- is used.
- .SH STDERR
- The standard error shall be used only for diagnostic messages.
- .SH "OUTPUT FILES"
- None.
- .SH "EXTENDED DESCRIPTION"
- None.
- .SH "EXIT STATUS"
- The following exit values shall be returned:
- .IP "\00" 6
- Successful completion.
- .IP >0 6
- An error occurred.
- .SH "CONSEQUENCES OF ERRORS"
- Default.
- .LP
- .IR "The following sections are informative."
- .SH "APPLICATION USAGE"
- On most systems, the ``name of the file system, in an
- implementation-defined format'' is the special file on which the
- file system is mounted.
- .P
- On large file systems, the calculation specified for percentage used
- can create huge rounding errors.
- .SH EXAMPLES
- .IP " 1." 4
- The following example writes portable information about the
- .BR /usr
- file system:
- .RS 4
- .sp
- .RS 4
- .nf
- df -P /usr
- .fi
- .P
- .RE
- .RE
- .IP " 2." 4
- Assuming that
- .BR /usr/src
- is part of the
- .BR /usr
- file system, the following produces the same output as the previous
- example:
- .RS 4
- .sp
- .RS 4
- .nf
- df -P /usr/src
- .fi
- .P
- .RE
- .RE
- .SH RATIONALE
- The behavior of
- .IR df
- with the
- .BR \-P
- option is the default action of the 4.2 BSD
- .IR df
- utility. The uppercase
- .BR \-P
- was selected to avoid collision with a known industry extension using
- .BR \-p .
- .P
- Historical
- .IR df
- implementations vary considerably in their default output. It was
- therefore necessary to describe the default output in a loose manner to
- accommodate all known historical implementations and to add a portable
- option (\c
- .BR \-P )
- to provide information in a portable format.
- .P
- The use of 512-byte units is historical practice and maintains
- compatibility with
- .IR ls
- and other utilities in this volume of POSIX.1\(hy2017. This does not mandate that the
- file system itself be based on 512-byte blocks. The
- .BR \-k
- 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/1\|024-byte usage on BSD systems), and that a
- .BR \-k
- option to switch to 1\|024-byte units was a good compromise. Users who
- prefer the more logical 1\|024-byte quantity can easily alias
- .IR df
- to
- .IR df
- .BR \-k
- without breaking many historical scripts relying on the 512-byte
- units.
- .P
- It was suggested that
- .IR df
- and the various related utilities be modified to access a
- .IR BLOCKSIZE
- environment variable to achieve consistency and user acceptance. Since
- this is not historical practice on any system, it is left as a possible
- area for system extensions and will be re-evaluated in a future version
- if it is widely implemented.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "\fIfind\fR\^"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "Chapter 8" ", " "Environment Variables",
- .IR "Section 12.2" ", " "Utility Syntax Guidelines"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 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 .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .