1DF(1P)                     POSIX Programmer's Manual                    DF(1P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       df — report free disk space
13

SYNOPSIS

15       df [-k] [-P|-t] [file...]
16

DESCRIPTION

18       The df utility shall write the amount of available space and file slots
19       for  file  systems  on  which  the  invoking  user has appropriate read
20       access. File systems shall be specified by the file operands; when none
21       are  specified,  information shall be written for all file systems. The
22       format of the default output from df is unspecified, but all space fig‐
23       ures are reported in 512-byte units, unless the -k option is specified.
24       This output shall contain at least the file  system  names,  amount  of
25       available space on each of these file systems, and, if no options other
26       than -t are specified, the number of free file slots, or inodes, avail‐
27       able;  when  -t  is specified, the output shall contain the total allo‐
28       cated space as well.
29

OPTIONS

31       The df  utility  shall  conform  to  the  Base  Definitions  volume  of
32       POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.
33
34       The following options shall be supported:
35
36       -k        Use  1024-byte  units, instead of the default 512-byte units,
37                 when writing space figures.
38
39       -P        Produce output in the format described in the STDOUT section.
40
41       -t        Include total allocated-space figures in the output.
42

OPERANDS

44       The following operand shall be supported:
45
46       file      A pathname of a file within the hierarchy of the desired file
47                 system.   If  a  file  other  than  a FIFO, a regular file, a
48                 directory, or a special file representing the device contain‐
49                 ing the file system (for example, /dev/dsk/0s1) is specified,
50                 the results are unspecified. If the file operand names a file
51                 other  than a special file containing a file system, df shall
52                 write the amount of free space in the file system  containing
53                 the  specified  file  operand.  Otherwise, df shall write the
54                 amount of free space in that file system.
55

STDIN

57       Not used.
58

INPUT FILES

60       None.
61

ENVIRONMENT VARIABLES

63       The following environment variables shall affect the execution of df:
64
65       LANG      Provide a default value for  the  internationalization  vari‐
66                 ables  that are unset or null. (See the Base Definitions vol‐
67                 ume of POSIX.1‐2017, Section 8.2, Internationalization  Vari‐
68                 ables  for  the  precedence of internationalization variables
69                 used to determine the values of locale categories.)
70
71       LC_ALL    If set to a non-empty string value, override  the  values  of
72                 all the other internationalization variables.
73
74       LC_CTYPE  Determine  the  locale for the interpretation of sequences of
75                 bytes of text data as characters (for example, single-byte as
76                 opposed to multi-byte characters in arguments).
77
78       LC_MESSAGES
79                 Determine the locale that should be used to affect the format
80                 and contents of diagnostic messages written to standard error
81                 and informative messages written to standard output.
82
83       NLSPATH   Determine the location of message catalogs for the processing
84                 of LC_MESSAGES.
85

ASYNCHRONOUS EVENTS

87       Default.
88

STDOUT

90       When both the -k and -P options are  specified,  the  following  header
91       line shall be written (in the POSIX locale):
92
93
94           "Filesystem 1024-blocks Used Available Capacity Mounted on\n"
95
96       When  the  -P  option is specified without the -k option, the following
97       header line shall be written (in the POSIX locale):
98
99
100           "Filesystem 512-blocks Used Available Capacity Mounted on\n"
101
102       The implementation may adjust the spacing of the header  line  and  the
103       individual  data  lines so that the information is presented in orderly
104       columns.
105
106       The remaining output with -P shall consist of one line  of  information
107       for  each specified file system. These lines shall be formatted as fol‐
108       lows:
109
110
111           "%s %d %d %d %d%% %s\n", <file system name>, <total space>,
112               <space used>, <space free>, <percentage used>,
113               <file system root>
114
115       In the following list,  all  quantities  expressed  in  512-byte  units
116       (1024-byte when -k is specified) shall be rounded up to the next higher
117       unit. The fields are:
118
119       <file system name>
120                 The name of the file  system,  in  an  implementation-defined
121                 format.
122
123       <total space>
124                 The  total  size  of  the  file system in 512-byte units. The
125                 exact meaning of this figure is  implementation-defined,  but
126                 should  include  <space used>,  <space free>,  plus any space
127                 reserved by the system not normally available to a user.
128
129       <space used>
130                 The total amount of space allocated to existing files in  the
131                 file system, in 512-byte units.
132
133       <space free>
134                 The  total  amount  of space available within the file system
135                 for the creation of  new  files  by  unprivileged  users,  in
136                 512-byte  units.  When  this  figure is less than or equal to
137                 zero, it shall not be possible to create any new files on the
138                 file system without first deleting others, unless the process
139                 has appropriate privileges. The figure written  may  be  less
140                 than zero.
141
142       <percentage used>
143                 The  percentage  of the normally available space that is cur‐
144                 rently allocated to all files on the file system. This  shall
145                 be calculated using the fraction:
146
147
148                     <space used>/( <space used>+ <space free>)
149
150                 expressed  as  a  percentage.  This percentage may be greater
151                 than 100 if <space free> is less than  zero.  The  percentage
152                 value  shall  be  expressed  as  a positive integer, with any
153                 fractional result causing it to be rounded to the next  high‐
154                 est integer.
155
156       <file system root>
157                 The directory below which the file system hierarchy appears.
158
159       The output format is unspecified when -t is used.
160

STDERR

162       The standard error shall be used only for diagnostic messages.
163

OUTPUT FILES

165       None.
166

EXTENDED DESCRIPTION

168       None.
169

EXIT STATUS

171       The following exit values shall be returned:
172
173        0    Successful completion.
174
175       >0    An error occurred.
176

CONSEQUENCES OF ERRORS

178       Default.
179
180       The following sections are informative.
181

APPLICATION USAGE

183       On  most  systems, the ``name of the file system, in an implementation-
184       defined format'' is the special  file  on  which  the  file  system  is
185       mounted.
186
187       On  large  file  systems, the calculation specified for percentage used
188       can create huge rounding errors.
189

EXAMPLES

191        1. The following example writes portable information  about  the  /usr
192           file system:
193
194
195               df -P /usr
196
197        2. Assuming that /usr/src is part of the /usr file system, the follow‐
198           ing produces the same output as the previous example:
199
200
201               df -P /usr/src
202

RATIONALE

204       The behavior of df with the -P option is the default action of the  4.2
205       BSD df utility. The uppercase -P was selected to avoid collision with a
206       known industry extension using -p.
207
208       Historical df implementations vary considerably in their  default  out‐
209       put.  It  was  therefore  necessary to describe the default output in a
210       loose manner to accommodate all known historical implementations and to
211       add a portable option (-P) to provide information in a portable format.
212
213       The use of 512-byte units is historical practice and maintains compati‐
214       bility with ls and other utilities in this volume of POSIX.1‐2017. This
215       does  not  mandate  that  the  file  system itself be based on 512-byte
216       blocks. The -k option was added as a compromise measure. It was  agreed
217       by  the  standard  developers  that 512 bytes was the best default unit
218       because of its complete historical consistency on System V (versus  the
219       mixed  512/1024-byte  usage  on  BSD  systems), and that a -k option to
220       switch to 1024-byte units was a good compromise. Users who  prefer  the
221       more  logical  1024-byte  quantity can easily alias df to df -k without
222       breaking many historical scripts relying on the 512-byte units.
223
224       It was suggested that df and the various related utilities be  modified
225       to  access  a BLOCKSIZE environment variable to achieve consistency and
226       user acceptance. Since this is not historical practice on  any  system,
227       it  is  left  as  a possible area for system extensions and will be re-
228       evaluated in a future version if it is widely implemented.
229

FUTURE DIRECTIONS

231       None.
232

SEE ALSO

234       find
235
236       The Base Definitions volume of  POSIX.1‐2017,  Chapter  8,  Environment
237       Variables, Section 12.2, Utility Syntax Guidelines
238
240       Portions  of  this text are reprinted and reproduced in electronic form
241       from IEEE Std 1003.1-2017, Standard for Information Technology --  Por‐
242       table  Operating System Interface (POSIX), The Open Group Base Specifi‐
243       cations Issue 7, 2018 Edition, Copyright (C) 2018 by the  Institute  of
244       Electrical  and  Electronics Engineers, Inc and The Open Group.  In the
245       event of any discrepancy between this version and the original IEEE and
246       The  Open Group Standard, the original IEEE and The Open Group Standard
247       is the referee document. The original Standard can be  obtained  online
248       at http://www.opengroup.org/unix/online.html .
249
250       Any  typographical  or  formatting  errors that appear in this page are
251       most likely to have been introduced during the conversion of the source
252       files  to  man page format. To report such errors, see https://www.ker
253       nel.org/doc/man-pages/reporting_bugs.html .
254
255
256
257IEEE/The Open Group                  2017                               DF(1P)
Impressum