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