\input texinfo
@c %**start of header
@setfilename fileutils.info
@settitle GNU file utilities
@c %**end of header

@include version.texi

@c Define new indices for file names and options.
@c @defcodeindex fl
@defcodeindex op

@c Put everything in one index (arbitrarily chosen to be the concept index).
@c @syncodeindex fl cp
@syncodeindex fn cp
@syncodeindex ky cp
@syncodeindex op cp
@syncodeindex pg cp
@syncodeindex vr cp

@ifinfo
@format
START-INFO-DIR-ENTRY
* File utilities: (fileutils).  GNU file utilities.
* chgrp: (fileutils)chgrp invocation.           Change file groups.
* chown: (fileutils)chown invocation.           Change file owners/groups.
* chmod: (fileutils)chmod invocation.           Change file permissions.
* cp: (fileutils)cp invocation.                 Copy files.
* dd: (fileutils)dd invocation.                 Copy and convert a file.
* df: (fileutils)df invocation.                 Report filesystem disk usage.
* dir: (fileutils)dir invocation.               List directories briefly.
* dircolors: (fileutils)dircolors invocation.   Color setup for ls.
* du: (fileutils)du invocation.                 Report on disk usage.
* install: (fileutils)install invocation.       Copy and change attributes.
* ln: (fileutils)ln invocation.                 Make links between files.
* ls: (fileutils)ls invocation.                 List directory contents.
* mkdir: (fileutils)mkdir invocation.           Create directories.
* mkfifo: (fileutils)mkfifo invocation.         Create FIFOs (named pipes).
* mknod: (fileutils)mknod invocation.           Create special files.
* mv: (fileutils)mv invocation.                 Rename files.
* rm: (fileutils)rm invocation.                 Remove files.
* rmdir: (fileutils)rmdir invocation.           Remove empty directories.
* sync: (fileutils)sync invocation.             Synchronize memory and disk.
* touch: (fileutils)touch invocation.           Change file timestamps.
* vdir: (fileutils)vdir invocation.             List directories verbosely.
END-INFO-DIR-ENTRY
@end format
@end ifinfo

@ifinfo
This file documents the GNU set of file utilities.

Copyright (C) 1994, 95, 96 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Foundation.
@end ifinfo

@titlepage
@title GNU @code{fileutils}
@subtitle A set of file utilities
@subtitle for version @value{VERSION}, @value{UPDATED}
@author David MacKenzie et al.

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1994, 95, 96 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Foundation.
@end titlepage


@ifnottex
@node Top
@top GNU file utilities

@cindex file utilities
@cindex utilities for file handling

This manual documents version @value{VERSION} of the GNU file utilities.

@end ifnottex

@menu
* Introduction::                Caveats, overview, and authors.
* Common options::              Common options.
* File permissions::            Access modes.
* Date input formats::          Specifying date strings.
* Directory listing::           ls dir vdir d v dircolors
* Basic operations::            cp dd install mv rm
* Special file types::          ln mkdir rmdir mkfifo mknod
* Changing file attributes::    chgrp chmod chown touch
* Disk usage::                  df du sync
* Index::                       General index.
@end menu


@node Introduction
@chapter Introduction

@cindex introduction

This manual is incomplete: No attempt is made to explain basic file
concepts in a way suitable for novices.  Thus, if you are interested,
please get involved in improving this manual.  The entire GNU community
will benefit.

@cindex POSIX.2
The GNU file utilities are mostly compatible with the @sc{POSIX.2} standard.

@c This paragraph appears in all of fileutils.texi, textutils.texi, and
@c sh-utils.texi too -- so be sure to keep them consistent.
@cindex bugs, reporting
Please report bugs to @email{bug-fileutils@@gnu.org}.  Remember
to include the version number, machine architecture, input files, and
any other information needed to reproduce the bug: your input, what you
expected, what you got, and why it is wrong.  Diffs are welcome, but
please include a description of the problem as well, since this is
sometimes difficult to infer. @xref{Bugs, , , gcc, GNU CC}.

@cindex history
This manual was originally derived from the Unix man pages in the
distribution, which were written by David MacKenzie and updated by Jim
Meyering.  What you are reading now is the authoritative documentation
for these utilities;  the man pages are no longer being maintained.
Fran@,{c}ois Pinard did the initial conversion to Texinfo format.
Karl Berry did the indexing, some reorganization, and editing of the results.
Richard Stallman contributed his usual invaluable insights to the
overall process.


@node Common options
@chapter Common options

@cindex common options

Certain options are available in all of these programs (in fact, every
GNU program should accept them).  Rather than writing identical
descriptions for each of the programs, they are described here.

@table @samp
@item --help
@opindex --help
@cindex help, online
Print a usage message listing all available options, then exit successfully.

@item --version
@opindex --version
@cindex version number, finding
Print the version number, then exit successfully.
@end table

@menu
* Backup options::              -b -S -V, in some programs.
* Block size::                  BLOCK_SIZE and --block-size, in some programs.
@end menu


@node Backup options
@section Backup options

@cindex backup options

Some GNU programs (at least @code{cp}, @code{install}, @code{ln}, and
@code{mv}) optionally make backups of files before writing new versions.
These options control the details of these backups.  The options are also
briefly mentioned in the descriptions of the particular programs.

@table @samp

@item -b
@itemx --backup
@opindex -b
@opindex --backup
@cindex backups, making
Make a backup of each file that would otherwise be overwritten or removed.
Without this option, the original versions are destroyed.

@item -S @var{suffix}
@itemx --suffix=@var{suffix}
@opindex -S
@opindex --suffix
@cindex backup suffix
@vindex SIMPLE_BACKUP_SUFFIX
Append @var{suffix} to each backup file made with @samp{-b}.  If this
option is not specified, the value of the @code{SIMPLE_BACKUP_SUFFIX}
environment variable is used.  And if @code{SIMPLE_BACKUP_SUFFIX} is not
set, the default is @samp{~}, just as in Emacs.

@item -V @var{method}
@itemx --version-control=@var{method}
@opindex -V
@opindex --version-control
@vindex VERSION_CONTROL
@cindex backup files, type made
Use @var{method} to determine the type of backups made with @samp{-b}.
If this option is not specified, the value of the @code{VERSION_CONTROL}
environment variable is used.  And if @code{VERSION_CONTROL} is not set,
the default backup type is @samp{existing}.

@vindex version-control @r{Emacs variable}
This option corresponds to the Emacs variable @samp{version-control};
the same values for @var{method} are accepted as in Emacs.  This options
also more descriptive name.  The valid @var{method}s (unique
abbreviations are accepted):

@table @samp
@item t
@itemx numbered
@opindex numbered @r{backup method}
Always make numbered backups.

@item nil
@itemx existing
@opindex existing @r{backup method}
Make numbered backups of files that already have them, simple backups
of the others.

@item never
@itemx simple
@opindex simple @r{backup method}
Always make simple backups.

@end table

@end table

@node Block size
@section Block size

@cindex block size

Some GNU programs (at least @code{df}, @code{du}, and @code{ls}) display
file sizes in ``blocks''.  You can adjust the block size to make file
sizes easier to read.  The block size used for display is independent of
any filesystem block size.  Displayed sizes are rounded to the nearest
block, with ties rounding to an even number.

@opindex --block-size=@var{size}
@vindex BLOCK_SIZE
@vindex DF_BLOCK_SIZE
@vindex DU_BLOCK_SIZE
@vindex LS_BLOCK_SIZE
@vindex POSIXLY_CORRECT@r{, and block size}

The default block size is chosen by examining the following environment
variables in turn; the first one that is set determines the block size.

@table @code

@item DF_BLOCK_SIZE
This specifies the default block size for the @code{df} command.
Similarly, @code{DU_BLOCK_SIZE} specifies the default for @code{du} and
@code{LS_BLOCK_SIZE} for @code{ls}.

@item BLOCK_SIZE
This specifies the default block size for all three commands, if the
above command-specific environment variables are not set.

@item POSIXLY_CORRECT
If neither the @code{@var{command}_BLOCK_SIZE} nor the @code{BLOCK_SIZE}
variables are set, but this variable is set, the block size defaults to 512.

@end table

If none of the above environment variables are set, the block size
currently defaults to 1024 bytes, but this number may change in the
future.

@cindex human-readable output
@cindex SI output

A block size specification can be a positive integer specifying the number
of bytes per block, or it can be @code{human-readable} or @code{si} to
select a human-readable format.

With human-readable formats, output sizes are followed by a size letter
such as @samp{M} for megabytes.  @code{BLOCK_SIZE=human-readable} uses
powers of 1024; @samp{M} stands for 1,048,576 bytes.
@code{BLOCK_SIZE=si} is similar, but uses powers of 1000; @samp{M} stands
for 1,000,000 bytes.  (SI, the International System of Units, defines
these power-of-1000 prefixes.)

An integer block size can be followed by a size letter to specify a
multiple of that size.  When this notation is used, the size letters
normally stand for powers of 1024, and can be followed by an optional
@samp{B} for ``byte''; but if followed by @samp{D} (for ``decimal
byte''), they stand for powers of 1000.  For example,
@code{BLOCK_SIZE=4MB} is equivalent to @code{BLOCK_SIZE=4194304}, and
@code{BLOCK_SIZE=4MD} is equivalent to @code{BLOCK_SIZE=4000000}.

The following size letters are defined.  Large sizes like @code{1Y}
may be rejected by your computer due to limitations of its arithmetic.

@table @samp
@item k
kilo: @math{2^10 = 1024} for @code{human-readable},
or @math{10^3 = 1000} for @code{si}.
@item M
Mega: @math{2^20 = 1,048,576}
or @math{10^6 = 1,000,000}.
@item G
Giga: @math{2^30 = 1,073,741,824}
or @math{10^9 = 1,000,000,000}.
@item T
Tera: @math{2^40 = 1,099,511,627,776}
or @math{10^12 = 1,000,000,000,000}.
@item P
Peta: @math{2^50 = 1,125,899,906,842,624}
or @math{10^15 = 1,000,000,000,000,000}.
@item E
Exa: @math{2^60 = 1,152,921,504,606,846,976}
or @math{10^18 = 1,000,000,000,000,000,000}.
@item Z
Zetta: @math{2^70 = 1,180,591,620,717,411,303,424}
or @math{10^21 = 1,000,000,000,000,000,000,000}.
@item Y
Yotta: @math{2^80 = 1,208,925,819,614,629,174,706,176}
or @math{10^24 = 1,000,000,000,000,000,000,000,000}.
@end table

@opindex -k
@opindex --kilobytes
@opindex -h
@opindex --human-readable
@opindex -H
@opindex --si

Block size defaults can be overridden by an explicit
@samp{--block-size=@var{size}} option.  The @samp{-k} or
@samp{--kilobytes} option is equivalent to @samp{--block-size=1k}, which
is the default unless the @code{POSIXLY_CORRECT} environment variable is
set.  The @samp{-h} or @samp{--human-readable} option is equivalent to
@samp{--block-size=human-readable}.  The @samp{-H} or @samp{--si} option
is equivalent to @samp{--block-size=si}.

@node File permissions
@chapter File permissions

@cindex file permissions
@cindex permissions of files

@include perm.texi


@include getdate.texi


@node Directory listing
@chapter Directory listing

This chapter describes the @code{ls} command and its variants @code{dir}
and @code{vdir}, which list information about files.

@menu
* ls invocation::               List directory contents.
* dir invocation::              Briefly ls.
* vdir invocation::             Verbosely ls.
* dircolors invocation::        Color setup for ls, etc.
@end menu


@node ls invocation
@section @code{ls}: List directory contents

@pindex ls
@cindex directory listing

The @code{ls} program lists information about files (of any type,
including directories).  Options and file arguments can be intermixed
arbitrarily, as usual.

For non-option command-line arguments that are directories, by default
@code{ls} lists the contents of directories, not recursively, and
omitting files with names beginning with @code{.}.  For other non-option
arguments, by default @code{ls} lists just the file name.  If no
non-option arguments are specified, @code{ls} lists the contents of the
current directory.

By default, the output is sorted alphabetically.  If standard output is
a terminal, the output is in columns (sorted vertically) and control
characters are output as question marks; otherwise, the output is listed
one per line and control characters are output as-is.

Because @code{ls} is such a fundamental program, it has accumulated many
options over the years.  They are described in the subsections below;
within each section, options are listed alphabetically (ignoring case).
The division of options into the subsections is not absolute, since some
options affect more than one aspect of @code{ls}'s operation.

@opindex -g @r{(ignored)}
The @samp{-g} option is accepted but ignored, for compatibility
with Unix.  Also see @ref{Common options}.

@menu
* Which files are listed::
* What information is listed::
* Sorting the output::
* More details about version sort::
* General output formatting::
* Formatting the file names::
@end menu


@node Which files are listed
@subsection Which files are listed

These options determine which files @code{ls} lists information for.
By default, any files and the contents of any directories on the command
line are shown.

@table @samp

@item -a
@itemx --all
@opindex -a
@opindex --all
List all files in directories, including files that start with @samp{.}.

@item -A
@itemx --almost-all
@opindex -A
@opindex --almost-all
List all files in directories except for @file{.} and @file{..}.

@item -B
@itemx --ignore-backups
@opindex -B
@opindex --ignore-backups
@cindex backup files, ignoring
Do not list files that end with @samp{~}, unless they are given on the
command line.

@item -d
@itemx --directory
@opindex -d
@opindex --directory
List just the names of directories, as with other types of files, rather
than listing their contents.

@item -I PATTERN
@itemx --ignore=PATTERN
@opindex -I
@opindex --ignore=@var{pattern}
Do not list files whose names match the shell pattern (not regular
expression) @var{pattern} unless they are given on the command line.  As
in the shell, an initial @samp{.} in a file name does not match a
wildcard at the start of @var{pattern}.  Sometimes it is useful
to give this option several times.  For example,

@example
$ ls --ignore='.??*' --ignore='.[^.]' --ignore='#*'
@end example

The first option ignores names of length 3 or more that start with @samp{.},
the second ignores all two-character names that start with @samp{.}
except @samp{..}, and the third ignores names that start with @samp{#}.

@item -L
@itemx --dereference
@opindex -L
@opindex --dereference
@cindex symbolic links, dereferencing
In a long listing, show file information (e.g., times and permissions)
for the referents of symbolic links rather than for the symbolic links
themselves.

@item -R
@itemx --recursive
@opindex -R
@opindex --recursive
@cindex recursive directory listing
@cindex directory listing, recursive
List the contents of all directories recursively.

@end table


@node What information is listed
@subsection What information is listed

These options affect the information that @code{ls} displays.  By
default, only file names are shown.

@table @samp

@item -D
@itemx --dired
@opindex -D
@opindex --dired
@cindex dired Emacs mode support
With the long listing (@samp{-l}) format, print an additional line after
the main output:

@example
//DIRED// @var{beg1 end1 beg2 end2 @dots{}}
@end example

@noindent
The @var{begN} and @var{endN} are unsigned integers that record the
byte position of the beginning and end of each file name in the output.
This makes it easy for Emacs to find the names, even when they contain
unusual characters such as space or newline, without fancy searching.

If directories are being listed recursively (@code{-R}), output a similar
line after each subdirectory:
@example
//SUBDIRED// @var{format} @var{beg1 end1 @dots{}}
@end example

Finally, output a line of the form:
@example
//DIRED-OPTIONS// --quoting-style=@var{word}
@end example
where @var{word} is the quoting style (@pxref{Formatting the file names}).

@item -G
@itemx --no-group
@opindex -G
@opindex --no-group
Inhibit display of group information in a long format directory listing.
(This is the default in some non-GNU versions of @code{ls}, so we
provide this option for compatibility.)

@item -h
@itemx --human-readable
@opindex -h
@opindex --human-readable
@cindex human-readable output
Append a size letter such as @samp{M} for megabytes to each size.
Powers of 1024 are used, not 1000; @samp{M} stands for 1,048,576 bytes.
Use the @samp{-H} or @samp{--si} option if you prefer powers of 1000.

@item -H
@itemx --si
@opindex -H
@opindex --si
@cindex SI output
Append a size letter such as @samp{M} for megabytes to each size.  (SI
is the International System of Units, which defines these letters as
prefixes.)  Powers of 1000 are used, not 1024; @samp{M} stands for
1,000,000 bytes.  Use the @samp{-h} or @samp{--human-readable} option if
you prefer powers of 1024.

@item -i
@itemx --inode
@opindex -i
@opindex --inode
@cindex inode number, printing
Print the inode number (also called the file serial number and index
number) of each file to the left of the file name.  (This number
uniquely identifies each file within a particular filesystem.)

@item -l
@itemx --format=long
@itemx --format=verbose
@opindex -l
@opindex --format
@opindex long ls @r{format}
@opindex verbose ls @r{format}
In addition to the name of each file, print the file type, permissions,
number of hard links, owner name, group name, size in bytes, and
timestamp (by default, the modification time).  For files with a time
more than six months old or more than one hour into the future, the
timestamp contains the year instead of the time of day.

For each directory that is listed, preface the files with a line
@samp{total @var{blocks}}, where @var{blocks} is the total disk allocation
for all files in that directory.  The block size currently defaults to 1024
bytes, but this can be overridden (@pxref{Block size}).
The @var{blocks} computed counts each hard link separately;
this is arguably a deficiency.

@cindex permissions, output by @code{ls}
The permissions listed are similar to symbolic mode specifications
(@pxref{Symbolic Modes}).  But @code{ls} combines multiple bits into the
third character of each set of permissions as follows:
@table @samp
@item s
If the setuid or setgid bit and the corresponding executable bit
are both set.

@item S
If the setuid or setgid bit is set but the corresponding executable bit
is not set.

@item t
If the sticky bit and the other-executable bit are both set.

@item T
If the sticky bit is set but the other-executable bit is not set.

@item x
If the executable bit is set and none of the above apply.

@item -
Otherwise.
@end table

@item -o
@opindex -o
Produce long format directory listings, but don't display group information.
It is equivalent to using @samp{--format=long} with @samp{--no-group} .
This option is provided for compatibility with other versions of @code{ls}.

@item -s
@itemx --size
@opindex -s
@opindex --size
@cindex disk allocation
@cindex size of files, reporting
Print the disk allocation of each file to the left of the file name.
This is the amount of disk space used by the file, which is usually a
bit more than the file's size, but it can be less if the file has holes.

Normally the disk allocation is printed in units of
1024 bytes, but this can be overridden (@pxref{Block size}).

@cindex NFS mounts from BSD to HP-UX
For files that are NFS-mounted from an HP-UX system to a BSD system,
this option reports sizes that are half the correct values.  On HP-UX
systems, it reports sizes that are twice the correct values for files
that are NFS-mounted from BSD systems.  This is due to a flaw in HP-UX;
it also affects the HP-UX @code{ls} program.

@end table


@node Sorting the output
@subsection Sorting the output

@cindex sorting @code{ls} output
These options change the order in which @code{ls} sorts the information
it outputs.  By default, sorting is done by character code (e.g., ASCII
order).

@table @samp

@item -c
@opindex -c
@opindex status time@r{, sorting by}
Sort according to the status change time (the @samp{ctime} in the
inode).  If the long listing format (@samp{-l}) is being used, print the
status change time instead of the modification time.

@item -f
@opindex -f
@cindex unsorted directory listing
@cindex directory order, listing by
Primarily, like @samp{-U}---do not sort; list the files in whatever
order they are stored in the directory.  But also enable @samp{-a} (list
all files) and disable @samp{-l}, @samp{--color}, and @samp{-s} (if they
were specified before the @samp{-f}).

@item -r
@itemx --reverse
@opindex -r
@opindex --reverse
@cindex reverse sorting
Reverse whatever the sorting method is---e.g., list files in reverse
alphabetical order, youngest first, smallest first, or whatever.

@item -S
@itemx --sort=size
@opindex -S
@opindex --sort
@opindex size of files@r{, sorting files by}
Sort by file size, largest first.

@item -t
@itemx --sort=time
@opindex -t
@opindex --sort
@opindex modification time@r{, sorting files by}
Sort by modification time (the @samp{mtime} in the inode), newest first.

@item -u
@opindex -u
@opindex atime@r{, sorting files by}
@opindex access time@r{, sorting files by}
@opindex use time@r{, sorting files by}
Sort by access time (the @samp{atime} in the inode).  If the long
listing format is being used, print the last access time.

@item --time=atime
@itemx --time=access
@opindex --time
@opindex atime@r{, printing or sorting files by}
@opindex access time@r{, printing or sorting files by}
When used with @samp{--sort=time} (@samp{-t}), this is equivalent to @samp{-u}.
With options that print times (e.g., @samp{--format=long}), print each file's
time of last access, rather than its time of last modification.

@item --time=ctime
@itemx --time=status
@itemx --time=use
@opindex --time
@opindex ctime@r{, printing or sorting by}
@opindex status time@r{, printing or sorting by}
@opindex use time@r{, printing or sorting files by}
When used with @samp{--sort=time} (@samp{-t}), this is equivalent to @samp{-c}.
With options that print times (e.g., @samp{--format=long}), print each file's
time of last inode change, rather than its time of last modification.

@item -U
@itemx --sort=none
@opindex -U
@opindex --sort
@opindex none@r{, sorting option for @code{ls}}
Do not sort; list the files in whatever order they are
stored in the directory.  (Do not do any of the other unrelated things
that @samp{-f} does.)  This is especially useful when listing very large
directories, since not doing any sorting can be noticeably faster.

@item -v
@itemx --sort=version
@opindex -v
@opindex --sort
@opindex version@r{, sorting option for @code{ls}}
Sort by version name and number, lowest first.  It behaves like a default
sort, excepted that each sequence of decimal digits is treated numericaly
as an index/version number.  (@xref{More details about version sort}.)

@item -X
@itemx --sort=extension
@opindex -X
@opindex --sort
@opindex extension@r{, sorting files by}
Sort directory contents alphabetically by file extension (characters
after the last @samp{.}); files with no extension are sorted first.

@end table


@node More details about version sort
@subsection More details about version sort

The version sort takes into account the fact that file names frequently include
indices or version numbers.  Standard sorting functions usually do not produce
the ordering that people expect because comparisons are made on a
character-by-character basis.  The version
sort adresses this problem, and is especially useful when browsing
directories that contain many files with indices/version numbers in their
names:

@example
      > ls -1            > ls -1v
      foo.zml-1.gz       foo.zml-1.gz
      foo.zml-100.gz     foo.zml-2.gz
      foo.zml-12.gz      foo.zml-6.gz
      foo.zml-13.gz      foo.zml-12.gz
      foo.zml-2.gz       foo.zml-13.gz
      foo.zml-25.gz      foo.zml-25.gz
      foo.zml-6.gz       foo.zml-100.gz
@end example

Note also that numeric parts with leading zeroes are considered as
fractional one:

@example
      > ls -1            > ls -1v
      abc-1.007.tgz      abc-1.007.tgz
      abc-1.012b.tgz     abc-1.01a.tgz
      abc-1.01a.tgz      abc-1.012b.tgz
@end example

@node General output formatting
@subsection General output formatting

These options affect the appearance of the overall output.

@table @samp

@item -1
@itemx --format=single-column
@opindex -1
@opindex --format
@opindex single-column @r{output of files}
List one file per line.  This is the default for @code{ls} when standard
output is not a terminal.

@item -C
@itemx --format=vertical
@opindex -C
@opindex --format
@opindex vertical @r{sorted files in columns}
List files in columns, sorted vertically.  This is the default for
@code{ls} if standard output is a terminal.  It is always the default
for the @code{dir} and @code{d} programs.
GNU @code{ls} uses variable width columns to display as many files as
possible in the fewest lines.

@item --color [=@var{when}]
@opindex --color
@cindex color, distinguishing file types with
Specify whether to use color for distinguishing file types.  @var{when}
may be omitted, or one of:
@itemize @bullet
@item none
@vindex none @r{color option}
Do not use color at all.  This is the default.
@item auto
@vindex auto @r{color option}
@cindex terminal, using color iff
Only use color if standard output is a terminal.
@item always
@vindex always @r{color option}
Always use color.
@end itemize
Specifying @samp{--color} and no @var{when} is equivalent to
@samp{--color=always}.

@item -F
@itemx --classify
@itemx --indicator-style=classify
@opindex -F
@opindex --classify
@opindex --indicator-style
@cindex file type and executables, marking
@cindex executables and file type, marking
Append a character to each file name indicating the file type.  Also,
for regular files that are executable, append @samp{*}.  The file type
indicators are @samp{/} for directories, @samp{@@} for symbolic links,
@samp{|} for FIFOs, @samp{=} for sockets, and nothing for regular files.

@item --full-time
@opindex --full-time
List times in full, rather than using the standard abbreviation
heuristics.  The format is the same as @code{date}'s default; it's not
possible to change this, but you can extract out the date string with
@code{cut} and then pass the result to @code{date -d}.  @xref{date
invocation, @code{date} invocation, , sh-utils, Shell utilities}.

This is most useful because the time output includes the seconds.  (Unix
filesystems store file timestamps only to the nearest second, so this
option shows all the information there is.)  For example, this can help
when you have a Makefile that is not regenerating files properly.

@item --indicator-style=@var{word}
@opindex --indicator-style
Append a character indicator with style @var{word} to entry names,
as follows:
@table @samp
@item none
Do not append any character indicator; this is the default.
@item file-type
Append @samp{/} for directories, @samp{@@} for symbolic links, @samp{|}
for FIFOs, @samp{=} for sockets, and nothing for regular files.  This is
the same as the @samp{-p} or @samp{--file-type} option.
@item classify
Append @samp{*} for executable regular files, otherwise behave as for
@samp{file-type}.  This is the same as the @samp{-F} or
@samp{--classify} option.
@end table

@item -k
@itemx --kilobytes
@opindex -k
@opindex --kilobytes
Print file sizes in 1024-byte blocks, overriding the default block
size (@pxref{Block size}).

@item -m
@itemx --format=commas
@opindex -m
@opindex --format
@opindex commas@r{, outputting between files}
List files horizontally, with as many as will fit on each line,
separated by @samp{, } (a comma and a space).

@item -n
@itemx --numeric-uid-gid
@opindex -n
@opindex --numeric-uid-gid
@cindex numeric uid and gid
List the numeric UID and GID instead of the names.

@item -p
@itemx --file-type
@itemx --indicator-style=file-type
@opindex --file-type
@opindex --indicator-style
@cindex file type, marking
Append a character to each file name indicating the file type. This is
like @samp{-F}, except that executables are not marked.

@item -x @var{format}
@itemx --format=across
@itemx --format=horizontal
@opindex -x
@opindex --format
@opindex across@r{, listing files}
@opindex horizontal@r{, listing files}
List the files in columns, sorted horizontally.

@item -T @var{cols}
@itemx --tabsize=@var{cols}
@opindex -T
@opindex --tabsize
Assume that each tabstop is @var{cols} columns wide.  The default is 8.
@code{ls} uses tabs where possible in the output, for efficiency.  If
@var{cols} is zero, do not use tabs at all.

@item -w
@itemx --width=@var{cols}
@opindex -w
@opindex --width
@vindex COLUMNS
Assume the screen is @var{cols} columns wide.  The default is taken
from the terminal settings if possible; otherwise the environment
variable @code{COLUMNS} is used if it is set; otherwise the default
is 80.

@end table


@node Formatting the file names
@subsection Formatting the file names

These options change how file names themselves are printed.

@table @samp

@item -b
@itemx --escape
@itemx --quoting-style=escape
@opindex -b
@opindex --escape
@opindex --quoting-style
@cindex backslash sequences for file names
Quote nongraphic characters in file names using alphabetic and octal
backslash sequences like those used in C.

@item -N
@itemx --literal
@opindex -N
@opindex --literal
Do not quote file names.

@item -q
@itemx --hide-control-chars
@opindex -q
@opindex --hide-control-chars
Print question marks instead of nongraphic characters in file names.
This is the default if the output is a terminal and the program is
@code{ls}.

@item -Q
@itemx --quote-name
@itemx --quoting-style=c
@opindex -Q
@opindex --quote-name
@opindex --quoting-style
Enclose file names in double quotes and quote nongraphic characters as
in C.

@item --quoting-style=@var{word}
@opindex --quoting-style
@cindex quoting style
Use style @var{word} to quote output names.  The @var{word} should
be one of the following:
@table @samp
@item literal
Output names as-is.
@item shell
Quote names for the shell if they contain shell metacharacters or would
cause ambiguous output.
@item shell-always
Quote names for the shell, even if they would normally not require quoting.
@item c
Quote names as for a C language string; this is the same as the
@samp{-Q} or @samp{--quote-name} option.
@item escape
Quote as with @samp{c} except omit the surrounding double-quote
characters; this is the same as the @samp{-b} or @samp{--escape} option.
@end table

You can specify the default value of the @samp{--quoting-style} option
with the environment variable @code{QUOTING_STYLE}.  If that environment
variable is not set, the default value is @samp{literal}, but this
default may change to @samp{shell} in a future version of this package.

@item --show-control-chars
@opindex --show-control-chars
Print nongraphic characters as-is in file names.
This is the default unless the output is a terminal and the program is
@code{ls}.

@end table


@node dir invocation
@section @code{dir}: Briefly list directory contents

@pindex dir
@cindex directory listing, brief

@code{dir} (also installed as @code{d}) is equivalent to @code{ls -C
-b}; that is, by default files are listed in columns, sorted vertically,
and special characters are represented by backslash escape sequences.

@xref{ls invocation, @code{ls}}.


@node vdir invocation
@section @code{vdir}: Verbosely list directory contents

@pindex vdir
@cindex directory listing, verbose

@code{vdir} (also installed as @code{v}) is equivalent to @code{ls -l
-b}; that is, by default files are listed in long format and special
characters are represented by backslash escape sequences.

@node dircolors invocation
@section @code{dircolors}: Color setup for @code{ls}

@pindex dircolors
@cindex color setup
@cindex setup for color

@code{dircolors} outputs a sequence of shell commands to set up the
terminal for color output from @code{ls} (and @code{dir}, etc.).
Typical usage:

@example
eval `dircolors [@var{option}]@dots{} [@var{file}]`
@end example

If @var{file} is specified, @code{dircolors} reads it to determine which
colors to use for which file types and extensions.  Otherwise, a
precompiled database is used.  For details on the format of these files,
run @samp{dircolors --print-database}.

@vindex LS_COLORS
@vindex SHELL @r{environment variable, and color}
The output is a shell command to set the @code{LS_COLORS} environment
variable.  You can specify the shell syntax to use on the command line,
or @code{dircolors} will guess it from the value of the @code{SHELL}
environment variable.

The program accepts the following options.  Also see @ref{Common options}.

@table @samp
@item -b
@itemx --sh
@itemx --bourne-shell
@opindex -b
@opindex --sh
@opindex --bourne-shell
@cindex Bourne shell syntax for color setup
@cindex @code{sh} syntax for color setup
Output Bourne shell commands.  This is the default if the @code{SHELL}
environment variable is set and does not end with @samp{csh} or
@samp{tcsh}.

@item -c
@itemx --csh
@itemx --c-shell
@opindex -c
@opindex --csh
@opindex --c-shell
@cindex C shell syntax for color setup
@cindex @code{csh} syntax for color setup
Output C shell commands.  This is the default if @code{SHELL} ends with
@code{csh} or @code{tcsh}.

@item -p
@itemx --print-database
@opindex -p
@opindex --print-database
@cindex color database, printing
@cindex database for color setup, printing
@cindex printing color database
Print the (compiled-in) default color configuration database.  This
output is itself a valid configuration file, and is fairly descriptive
of the possibilities.

@end table


@node Basic operations
@chapter Basic operations

@cindex manipulating files

This chapter describes the commands for basic file manipulation:
copying, moving (renaming), and deleting (removing).

@menu
* cp invocation::               Copy files.
* dd invocation::               Convert and copy a file.
* install invocation::          Copy files and set attributes.
* mv invocation::               Move (rename) files.
* rm invocation::               Remove files or directories.
@end menu


@node cp invocation
@section @code{cp}: Copy files and directories

@pindex cp
@cindex copying files and directories
@cindex files, copying
@cindex directories, copying

@code{cp} copies files (or, optionally, directories).  The copy is
completely independent of the original.  You can either copy one file to
another, or copy arbitrarily many files to a destination directory.
Synopsis:

@example
cp [@var{option}]@dots{} @var{source} @var{dest}
cp [@var{option}]@dots{} @var{source}@dots{} @var{directory}
@end example

If the last argument names an existing directory, @code{cp} copies each
@var{source} file into that directory (retaining the same name).
Otherwise, if only two files are given, it copies the first onto the
second.  It is an error if the last argument is not a directory and more
than two non-option arguments are given.

Generally, files are written just as they are read.  For exceptions,
see the @samp{--sparse} option below.

By default, @code{cp} does not copy directories (see @samp{-r} below).

@cindex self-backups
@cindex backups, making only
@code{cp} generally refuses to copy a file onto itself, with the
following exception: if @samp{--force --backup} is specified with
@var{source} and @var{dest} identical, and referring to a regular file,
@code{cp} will make a backup file, either regular or numbered, as
specified in the usual ways (@pxref{Backup options}).  This is useful when
you simply want to make a backup of an existing file before changing it.

The program accepts the following options.  Also see @ref{Common options}.

@table @samp
@item -a
@itemx --archive
@opindex -a
@opindex --archive
Preserve as much as possible of the structure and attributes of the
original files in the copy (but do not preserve directory structure).
Equivalent to @samp{-dpR}.

@item -b
@itemx --backup
@opindex -b
@opindex --backup
@cindex backups, making
Make a backup of each file that would otherwise be overwritten or removed.
@xref{Backup options}.

@item -d
@itemx --no-dereference
@opindex -d
@opindex --no-dereference
@cindex symbolic links, copying
@cindex hard links, preserving
Copy symbolic links as symbolic links rather than copying the files that
they point to, and preserve hard links between source files in the
copies.

@item -f
@itemx --force
@opindex -f
@opindex --force
Remove existing destination files.

@item -i
@itemx --interactive
@opindex -i
@opindex --interactive
Prompt whether to overwrite existing regular destination files.

@item -l
@itemx --link
@opindex -l
@opindex --link
Make hard links instead of copies of non-directories.

@item -p
@itemx --preserve
@opindex -p
@opindex --preserve
@cindex file information, preserving
Preserve the original files' owner, group, permissions, and timestamps.

@item -P
@itemx --parents
@opindex -P
@opindex --parents
@cindex parent directories and @code{cp}
Form the name of each destination file by appending to the target
directory a slash and the specified name of the source file.  The last
argument given to @code{cp} must be the name of an existing directory.
For example, the command:

@example
cp --parents a/b/c existing_dir
@end example

@noindent
copies the file @file{a/b/c} to @file{existing_dir/a/b/c}, creating
any missing intermediate directories.

@item -r
@cindex directories, copying recursively
@cindex copying directories recursively
@cindex recursively copying directories
@cindex non-directories, copying as special files
Copy directories recursively, copying any non-directories and
non-symbolic links (that is, FIFOs and special files) as if they were
regular files.  This means trying to read the data in each source
file and writing it to the destination.  It is usually a mistake to
apply @code{cp -r} to special files like FIFOs and the ones typically
found in the @file{/dev} directory.  In most cases, @code{cp -r}
will hang indefinitely trying to read from FIFOs and special files
like @file{/dev/console}, and it will fill up your destination disk
if you use it to copy @file{/dev/zero}.
Use the @samp{--recursive} (@samp{-R}) option instead if you want
to copy special files, preserving their special nature
rather than reading from them to copy their contents.

@item -R
@itemx --recursive
@opindex -R
@opindex --recursive
Copy directories recursively, preserving non-directories (contrast with
@samp{-r} just above).

@item --sparse=@var{when}
@opindex --sparse=@var{when}
@cindex sparse files, copying
@cindex holes, copying files with
@findex read @r{system call, and holes}
A @dfn{sparse file} contains @dfn{holes}---a sequence of zero bytes that
does not occupy any physical disk blocks; the @samp{read} system call
reads these as zeroes.  This can both save considerable disk space and
increase speed, since many binary files contain lots of consecutive zero
bytes.  By default, @code{cp} detects holes in input source files via a crude
heuristic and makes the corresponding output file sparse as well.

The @var{when} value can be one of the following:
@table @samp
@item auto
The default behavior: the output file is sparse if the input file is sparse.

@item always
Always make the output file sparse.  This is useful when the input
file resides on a filesystem that does not support sparse files (the
most notable example is @samp{efs} filesystems in SGI IRIX 5.3 and
earlier), but the output file is on another type of filesystem.

@item never
Never make the output file sparse.  If you find an application for this
option, let us know.
@end table

@item -s
@itemx --symbolic-link
@opindex -s
@opindex --symbolic-link
@cindex symbolic links, copying with
Make symbolic links instead of copies of non-directories.  All source
file names must be absolute (starting with @samp{/}) unless the
destination files are in the current directory.  This option merely
results in an error message on systems that do not support symbolic links.

@item -S @var{suffix}
@itemx --suffix=@var{suffix}
@opindex -S
@opindex --suffix
Append @var{suffix} to each backup file made with @samp{-b}.
@xref{Backup options}.

@item -u
@itemx --update
@opindex -u
@opindex --update
@cindex newer files, copying only
Do not copy a nondirectory that has an existing destination with the
same or newer modification time.

@item -v
@itemx --verbose
@opindex -v
@opindex --verbose
Print the name of each file before copying it.

@item -V @var{method}
@itemx --version-control=@var{method}
@opindex -V
@opindex --version-control
Change the type of backups made with @samp{-b}.  The @var{method}
argument can be @samp{numbered} (or @samp{t}), @samp{existing} (or
@samp{nil}), or @samp{never} (or @samp{simple}).  @xref{Backup options}.

@item -x
@itemx --one-file-system
@opindex -x
@opindex --one-file-system
@cindex filesystems, omitting copying to different
Skip subdirectories that are on different filesystems from the one that
the copy started on.
However, mount point directories @emph{are} copied.

@end table


@node dd invocation
@section @code{dd}: Convert and copy a file

@pindex dd
@cindex converting while copying a file

@code{dd} copies a file (from standard input to standard output, by
default) with a changeable I/O block size, while optionally performing
conversions on it.  Synopsis:

@example
dd [@var{option}]@dots{}
@end example

The program accepts the following options.  Also see @ref{Common options}.

@cindex multipliers after numbers
The numeric-valued options below (@var{bytes} and @var{blocks}) can be
followed by a multiplier: @samp{b}=512, @samp{c}=1,
@samp{w}=2, @samp{x@var{m}}=@var{m}, or any of the
standard block size suffixes like @samp{k}=1024 (@pxref{Block size}).

@table @samp

@item if=@var{file}
@opindex if
Read from @var{file} instead of standard input.

@item of=@var{file}
@opindex of
Write to @var{file} instead of standard output.  Unless
@samp{conv=notrunc} is given, @code{dd} truncates @var{file} to zero
bytes (or the size specified with @samp{seek=}).

@item ibs=@var{bytes}
@opindex ibs
@cindex block size of input
@cindex input block size
Read @var{bytes} bytes at a time.

@item obs=@var{bytes}
@opindex obs
@cindex block size of output
@cindex output block size
Write @var{bytes} bytes at a time.

@item bs=@var{bytes}
@opindex bs
@cindex block size
Both read and write @var{bytes} bytes at a time.  This overrides
@samp{ibs} and @samp{obs}.

@item cbs=@var{bytes}
@opindex cbs
@cindex block size of conversion
@cindex converstion block size
Convert @var{bytes} bytes at a time.

@item skip=@var{blocks}
@opindex skip
Skip @var{blocks} @samp{ibs}-byte blocks in the input file before copying.

@item seek=@var{blocks}
@opindex seek
Skip @var{blocks} @samp{obs}-byte blocks in the output file before copying.

@item count=@var{blocks}
@opindex count
Copy @var{blocks} @samp{ibs}-byte blocks from the input file, instead
of everything until the end of the file.

@item conv=@var{conversion}[,@var{conversion}]@dots{}
@opindex conv
Convert the file as specified by the @var{conversion} argument(s).
(No spaces around any comma(s).)

Conversions:

@table @samp

@item ascii
@opindex ascii@r{, converting to}
Convert EBCDIC to ASCII.

@item ebcdic
@opindex ebcdic@r{, converting to}
Convert ASCII to EBCDIC.

@item ibm
@opindex alternate ebcdic@r{, converting to}
Convert ASCII to alternate EBCDIC.

@item block
@opindex block @r{(space-padding)}
For each line in the input, output @samp{cbs} bytes, replacing the
input newline with a space and padding with spaces as necessary.

@item unblock
@opindex unblock
Replace trailing spaces in each @samp{cbs}-sized input block with a
newline.

@item lcase
@opindex lcase@r{, converting to}
Change uppercase letters to lowercase.

@item ucase
@opindex ucase@r{, converting to}
Change lowercase letters to uppercase.

@item swab
@opindex swab @r{(byte-swapping)}
@cindex byte-swapping
Swap every pair of input bytes.  GNU @code{dd}, unlike others, works
when an odd number of bytes are read---the last byte is simply copied
(since there is nothing to swap it with).

@item noerror
@opindex noerror
@cindex read errors, ignoring
Continue after read errors.

@item notrunc
@opindex notrunc
@cindex truncating output file, avoiding
Do not truncate the output file.

@item sync
@opindex sync @r{(padding with nulls)}
Pad every input block to size of @samp{ibs} with trailing zero bytes.
@end table

@end table


@node install invocation
@section @code{install}: Copy files and set attributes

@pindex install
@cindex copying files and setting attributes

@code{install} copies files while setting their permission modes and, if
possible, their owner and group.  Synopses:

@example
install [@var{option}]@dots{} @var{source} @var{dest}
install [@var{option}]@dots{} @var{source}@dots{} @var{directory}
install -d [@var{option}]@dots{} @var{directory}@dots{}
@end example

In the first of these, the @var{source} file is copied to the @var{dest}
target file.  In the second, each of the @var{source} files are copied
to the destination @var{directory}.  In the last, each @var{directory}
(and any missing parent directories) is created.

@cindex Makefiles, installing programs in
@code{install} is similar to @code{cp}, but allows you to control the
attributes of destination files.  It is typically used in Makefiles to
copy programs into their destination directories.  It refuses to copy
files onto themselves.

The program accepts the following options.  Also see @ref{Common options}.

@table @samp

@item -b
@itemx --backup
@opindex -b
@opindex --backup
@cindex backups, making
Make a backup of each file that would otherwise be overwritten or removed.
@xref{Backup options}.

@item -c
@opindex -c
Ignored; for compatibility with old Unix versions of @code{install}.

@item -d
@itemx --directory
@opindex -d
@opindex --directory
@cindex directories, creating with given attributes
@cindex parent directories, creating missing
@cindex leading directories, creating missing
Create each given directory and any missing parent directories, setting
the owner, group and mode as given on the command line or to the
defaults.  It also gives any parent directories it creates those
attributes.  (This is different from the SunOS 4.x @code{install}, which
gives directories that it creates the default attributes.)

@item -g @var{group}
@itemx --group=@var{group}
@opindex -g
@opindex --group
@cindex group ownership of installed files, setting
Set the group ownership of installed files or directories to
@var{group}. The default is the process's current group.  @var{group}
may be either a group name or a numeric group id.

@item -m @var{mode}
@itemx --mode=@var{mode}
@opindex -m
@opindex --mode
@cindex permissions of installed files, setting
Set the permissions for the installed file or directory to @var{mode},
which can be either an octal number, or a symbolic mode as in
@code{chmod}, with 0 as the point of departure (@pxref{File
permissions}).  The default mode is 0755---read, write, and execute
for the owner, and read and execute for group and other.

@item -o @var{owner}
@itemx --owner=@var{owner}
@opindex -o
@opindex --owner
@cindex ownership of installed files, setting
@cindex appropriate privileges
@vindex root @r{as default owner}
If @code{install} has appropriate privileges (is run as root), set the
ownership of installed files or directories to @var{owner}. The default
is @code{root}.  @var{owner} may be either a user name or a numeric user
ID.

@item -p
@itemx --preserve-timestamps
@opindex -p
@opindex --preserve-timestamps
@cindex timestamps of installed files, preserving
Set the time of last access and the time of last modification of each
installed file to match those of each corresponding original file.
When a file is installed without this option, its last access and
last modification times are both set to the time of installation.
This option is useful if you want to use the last modification times
of installed files to keep track of when they were last built as opposed
to when they were last installed.

@item -s
@itemx --strip
@opindex -s
@opindex --strip
@cindex symbol table information, stripping
@cindex stripping symbol table information
Strip the symbol tables from installed binary executables.

@item -S @var{suffix}
@itemx --suffix=@var{suffix}
@opindex -S
@opindex --suffix
Append @var{suffix} to each backup file made with @samp{-b}.
@xref{Backup options}.

@item -v
@itemx --verbose
@opindex -v
@opindex --verbose
Print the name of each file before copying it.

@item -V @var{method}
@itemx --version-control=@var{method}
@opindex -V
@opindex --version-control
Change the type of backups made with @samp{-b}.  The @var{method}
argument can be @samp{numbered} (or @samp{t}), @samp{existing} (or
@samp{nil}), or @samp{never} (or @samp{simple}).  @xref{Backup options}.

@end table


@node mv invocation
@section @code{mv}: Move (rename) files

@pindex mv

@code{mv} moves or renames files (or directories).  Synopsis:

@example
mv [@var{option}]@dots{} @var{source} @var{dest}
mv [@var{option}]@dots{} @var{source}@dots{} @var{directory}
@end example

If the last argument names an existing directory, @code{mv} moves each
other given file into a file with the same name in that directory.
Otherwise, if only two files are given, it renames the first as
the second.  It is an error if the last argument is not a directory
and more than two files are given.

@code{mv} can move only regular files across filesystems.

@cindex prompting, and @code{mv}
If a destination file exists but is normally unwritable, standard input
is a terminal, and the @samp{-f} or @samp{--force} option is not given,
@code{mv} prompts the user for whether to replace the file.  (You might
own the file, or have write permission on its directory.)  If the
response does not begin with @samp{y} or @samp{Y}, the file is skipped.

The program accepts the following options.  Also see @ref{Common options}.

@table @samp

@item -b
@itemx --backup
@opindex -b
@opindex --backup
@cindex backups, making
Make a backup of each file that would otherwise be overwritten or removed.
@xref{Backup options}.

@item -f
@itemx --force
@opindex -f
@opindex --force
@cindex prompts, omitting
Remove existing destination files and never prompt the user.

@item -i
@itemx --interactive
@opindex -i
@opindex --interactive
@cindex prompts, forcing
Prompt whether to overwrite each existing destination file, regardless
of its permissions.  If the response does not begin with @samp{y} or
@samp{Y}, the file is skipped.

@item -u
@itemx --update
@opindex -u
@opindex --update
@cindex newer files, moving only
Do not move a nondirectory that has an existing destination with the
same or newer modification time.

@item -v
@itemx --verbose
@opindex -v
@opindex --verbose
Print the name of each file before moving it.

@item -S @var{suffix}
@itemx --suffix=@var{suffix}
@opindex -S
@opindex --suffix
Append @var{suffix} to each backup file made with @samp{-b}.
@xref{Backup options}.

@item -V @var{method}
@itemx --version-control=@var{method}
@opindex -V
@opindex --version-control
Change the type of backups made with @samp{-b}.  The @var{method}
argument can be @samp{numbered} (or @samp{t}), @samp{existing} (or
@samp{nil}), or @samp{never} (or @samp{simple}).  @xref{Backup options}.

@end table


@node rm invocation
@section @code{rm}: Remove files or directories

@pindex rm
@cindex removing files or directories

@code{rm} removes each given @var{file}.  By default, it does not remove
directories.  Synopsis:

@example
rm [@var{option}]@dots{} [@var{file}]@dots{}
@end example

@cindex prompting, and @code{rm}
If a file is unwritable, standard input is a terminal, and the @samp{-f}
or @samp{--force} option is not given, or the @samp{-i} or
@samp{--interactive} option @emph{is} given, @code{rm} prompts the user
for whether to remove the file.  If the response does not begin with
@samp{y} or @samp{Y}, the file is skipped.

The program accepts the following options.  Also see @ref{Common options}.

@table @samp

@item -d
@itemx --directory
@opindex -d
@opindex --directory
@cindex directories, removing with @code{unlink}
@findex unlink
@pindex fsck
Remove directories with @code{unlink} instead of @code{rmdir}, and don't
require a directory to be empty before trying to unlink it.  Only works
if you have appropriate privileges.  Because unlinking a directory
causes any files in the deleted directory to become unreferenced, it is
wise to @code{fsck} the filesystem after doing this.

@item -f
@itemx --force
@opindex -f
@opindex --force
Ignore nonexistent files and never prompt the user.
Ignore any previous @samp{--interactive} (@samp{-i}) option.

@item -i
@itemx --interactive
@opindex -i
@opindex --interactive
Prompt whether to remove each file.  If the response does not begin
with @samp{y} or @samp{Y}, the file is skipped.
Ignore any previous @samp{--force} (@samp{-f}) option.

@item -r
@itemx -R
@itemx --recursive
@opindex -r
@opindex -R
@opindex --recursive
@cindex directories, removing (recursively)
Remove the contents of directories recursively.

@item -v
@itemx --verbose
@opindex -v
@opindex --verbose
Print the name of each file before removing it.

@end table

@cindex files beginning with @samp{-}, removing
@cindex @samp{-}, removing files beginning with
One common question is how to remove files whose names begin with a
@samp{-}.  GNU @code{rm}, like every program that uses the @code{getopt}
function to parse its arguments, lets you use the @samp{--} option to
indicate that all following arguments are non-options.  To remove a file
called @file{-f} in the current directory, you could type either:

@example
rm -- -f
@end example

@noindent
or:

@example
rm ./-f
@end example

@opindex - @r{and Unix @code{rm}}
The Unix @code{rm} program's use of a single @samp{-} for this purpose
predates the development of the getopt standard syntax.


@node Special file types
@chapter Special file types

@cindex special file types
@cindex file types, special

This chapter describes commands which create special types of files (and
@code{rmdir}, which removes directories, one special file type).

@cindex special file types
@cindex file types
Although Unix-like operating systems have markedly fewer special file
types than others, not @emph{everything} can be treated only as the
undifferentiated byte stream of @dfn{normal files}.  For example, when a
file is created or removed, the system must record this information,
which it does in a @dfn{directory}---a special type of file.  Although
you can read directories as normal files, if you're curious, in order
for the system to do its job it must impose a structure, a certain
order, on the bytes of the file.  Thus it is a ``special'' type of file.

Besides directories, other special file types include named pipes
(FIFOs), symbolic links, sockets, and so-called @dfn{special files}.

@menu
* ln invocation::               Make links between files.
* mkdir invocation::            Make directories.
* mkfifo invocation::           Make FIFOs (named pipes).
* mknod invocation::            Make block or character special files.
* rmdir invocation::            Remove empty directories.
@end menu


@node ln invocation
@section @code{ln}: Make links between files

@pindex ln
@cindex links, creating
@cindex hard links, creating
@cindex symbolic (soft) links, creating
@cindex creating links (hard or soft)

@cindex filesystems and hard links
@code{ln} makes links between files.  By default, it makes hard links;
with the @samp{-s} option, it makes symbolic (or @dfn{soft}) links.
Synopses:

@example
ln [@var{option}]@dots{} @var{target} [@var{linkname}]
ln [@var{option}]@dots{} @var{target}@dots{} @var{directory}
@end example

@itemize @bullet

@item If the last argument names an existing directory, @code{ln} creates a
link to each @var{target} file in that directory, using the
@var{target}s' names.  (But see the description of the
@samp{--no-dereference} option below.)

@item If two filenames are given, @code{ln} creates a link from the
second to the first.

@item If one @var{target} is given, @code{ln} creates a link to that
file in the current directory.

@item It is an error if the last argument is not a directory and more
than two files are given.  Without @samp{-f} or @samp{-i} (see below),
@code{ln} will not remove an existing file.  Use the @samp{--backup}
option to make @code{ln} rename existing files.

@end itemize

@cindex hard link, defined
@cindex inode, and hard links
A @dfn{hard link} is another name for an existing file; the link and the
original are indistinguishable.  Technically speaking, they share the
same inode, and the inode contains all the information about a
file---indeed, it is not incorrect to say that the inode @emph{is} the
file.  On all existing implementations, you cannot make a hard link to
a directory, and hard links cannot cross filesystem boundaries.  (These
restrictions are not mandated by @sc{POSIX}, however.)

@cindex dereferencing symbolic links
@cindex symbolic link, defined
@dfn{Symbolic links} (@dfn{symlinks} for short), on the other hand, are
a special file type (which not all kernels support: System V release 3
(and older) systems lack symlinks) in which the link file actually
refers to a different file, by name.  When most operations (opening,
reading, writing, and so on) are passed the symbolic link file, the
kernel automatically @dfn{dereferences} the link and operates on the
target of the link.  But some operations (e.g., removing) work on the
link file itself, rather than on its target.  @xref{Symbolic Links,,,
library, GNU C library}.

The program accepts the following options.  Also see @ref{Common options}.

@table @samp

@item -b
@itemx --backup
@opindex -b
@opindex --backup
@cindex backups, making
Make a backup of each file that would otherwise be overwritten or removed.
@xref{Backup options}.

@item -d
@itemx -F
@itemx --directory
@opindex -d
@opindex -F
@opindex --directory
@cindex hard links to directories
Allow the super-user to make hard links to directories.

@item -f
@itemx --force
@opindex -f
@opindex --force
Remove existing destination files.

@item -i
@itemx --interactive
@opindex -i
@opindex --interactive
@cindex prompting, and @code{ln}
Prompt whether to remove existing destination files.

@item -n
@itemx --no-dereference
@opindex -n
@opindex --no-dereference
When given an explicit destination that is a symlink to a directory,
treat that destination as if it were a normal file.

When the destination is an actual directory (not a symlink to one),
there is no ambiguity.  The link is created in that directory.
But when the specified destination is a symlink to a directory,
there are two ways to treat the user's request.  @code{ln} can
treat the destination just as it would a normal directory and create
the link in it.  On the other hand, the destination can be viewed as a
non-directory---as the symlink itself.  In that case, @code{ln}
must delete or backup that symlink before creating the new link.
The default is to treat a destination that is a symlink to a directory
just like a directory.

@item -s
@itemx --symbolic
@opindex -s
@opindex --symbolic
Make symbolic links instead of hard links.  This option merely produces
an error message on systems that do not support symbolic links.

@item -S @var{suffix}
@itemx --suffix=@var{suffix}
@opindex -S
@opindex --suffix
Append @var{suffix} to each backup file made with @samp{-b}.
@xref{Backup options}.

@item -v
@itemx --verbose
@opindex -v
@opindex --verbose
Print the name of each file before linking it.

@item -V @var{method}
@itemx --version-control=@var{method}
@opindex -V
@opindex --version-control
Change the type of backups made with @samp{-b}.  The @var{method}
argument can be @samp{numbered} (or @samp{t}), @samp{existing} (or
@samp{nil}), or @samp{never} (or @samp{simple}).  @xref{Backup options}.

@end table

Examples:

@example
ln -s /some/name  # creates link ./name pointing to /some/name
ln -s /some/name myname  # creates link ./myname pointing to /some/name
ln -s a b ..      # creates links ../a and ../b pointing to ./a and ./b
@end example


@node mkdir invocation
@section @code{mkdir}: Make directories

@pindex mkdir
@cindex directories, creating
@cindex creating directories

@code{mkdir} creates directories with the specified names.  Synopsis:

@example
mkdir [@var{option}]@dots{} @var{name}@dots{}
@end example

It is not an error if a @var{name} is already a directory; @code{mkdir}
simply proceeds.  But if a @var{name} is an existing file and is
anything but a directory, @code{mkdir} complains.

The program accepts the following options.  Also see @ref{Common options}.

@table @samp

@item -m @var{mode}
@itemx --mode=@var{mode}
@opindex -m
@opindex --mode
@cindex modes of created directories, setting
Set the mode of created directories to @var{mode}, which is symbolic as
in @code{chmod} and uses 0777 (read, write and execute allowed for
everyone) minus the bits set in the umask for the point of the
departure.  @xref{File permissions}.

@item -p
@itemx --parents
@opindex -p
@opindex --parents
@cindex parent directories, creating
Make any missing parent directories for each argument.  The mode for parent
directories is set to the umask modified by @samp{u+wx}.
Ignore arguments corresponding to existing directories.

@itemx --verbose
@opindex --verbose
Print a message for each created directory.  This is most useful with
@samp{--parents}.
@end table


@node mkfifo invocation
@section @code{mkfifo}: Make FIFOs (named pipes)

@pindex mkfifo
@cindex FIFOs, creating
@cindex named pipes, creating
@cindex creating FIFOs (named pipes)

@code{mkfifo} creates FIFOs (also called @dfn{named pipes}) with the
specified names.  Synopsis:

@example
mkfifo [@var{option}] @var{name}@dots{}
@end example

A @dfn{FIFO} is a special file type that permits independent processes
to communicate.  One process opens the FIFO file for writing, and
another for reading, after which data can flow as with the usual
anonymous pipe in shells or elsewhere.

The program accepts the following option.  Also see @ref{Common options}.

@table @samp

@item -m @var{mode}
@itemx --mode=@var{mode}
@opindex -m
@opindex --mode
@cindex modes of created FIFOs, setting
Set the mode of created FIFOs to @var{mode}, which is symbolic as in
@code{chmod} and uses 0666 (read and write allowed for everyone) minus
the bits set in the umask for the point of departure.  @xref{File permissions}.

@end table


@node mknod invocation
@section @code{mknod}: Make block or character special files

@pindex mknod
@cindex block special files, creating
@cindex character special files, creating

@code{mknod} creates a FIFO, character special file, or block special
file with the specified name.  Synopsis:

@example
mknod [@var{option}]@dots{} @var{name} @var{type} [@var{major} @var{minor}]
@end example

@cindex special files
@cindex block special files
@cindex character special files
Unlike the phrase ``special file type'' above, the term @dfn{special
file} has a technical meaning on Unix: something that can generate or
receive data.  Usually this corresponds to a physical piece of hardware,
e.g., a printer or a disk.  (These files are typically created at
system-configuration time.)  The @code{mknod} command is what creates
files of this type.  Such devices can be read either a character at a
time or a ``block'' (many characters) at a time, hence we say there are
@dfn{block special} files and @dfn{character special} files.

The arguments after @var{name} specify the type of file to make:

@table @samp

@item p
@opindex p @r{for FIFO file}
for a FIFO

@item b
@opindex b @r{for block special file}
for a block special file

@item c
@c Don't document the `u' option -- it's just a synonym for `c'.
@c Do *any* versions of mknod still use it?
@c @itemx u
@opindex c @r{for character special file}
@c @opindex u @r{for character special file}
for a character special file

@end table

When making a block or character special file, the major and minor
device numbers must be given after the file type.

The program accepts the following option.  Also see @ref{Common options}.

@table @samp

@item -m @var{mode}
@itemx --mode=@var{mode}
@opindex -m
@opindex --mode
Set the mode of created files to @var{mode}, which is symbolic as in
@code{chmod} and uses 0666 minus the bits set in the umask as the point
of departure.  @xref{File permissions}.

@end table


@node rmdir invocation
@section @code{rmdir}: Remove empty directories

@pindex rmdir
@cindex removing empty directories
@cindex directories, removing empty

@code{rmdir} removes empty directories.  Synopsis:

@example
rmdir [@var{option}]@dots{} @var{directory}@dots{}
@end example

If any @var{directory} argument does not refer to an existing empty
directory, it is an error.

The program accepts the following option.  Also see @ref{Common options}.

@table @samp

@itemx --ignore-fail-on-non-empty
@opindex --ignore-fail-on-non-empty
@cindex directory deletion, ignoring failures
Ignore each failure that is solely because a directory is non-empty.

@item -p
@itemx --parents
@opindex -p
@opindex --parents
@cindex parent directories, removing
Remove any parent directories that become empty after an argument
@var{directory} is removed.

@itemx --verbose
@opindex --verbose
@cindex directory deletion, reporting
Give a diagnostic for each successful removal.
@var{directory} is removed.

@end table

@xref{rm invocation}, for how to remove non-empty directories (recursively).


@node Changing file attributes
@chapter Changing file attributes

@cindex changing file attributes
@cindex file attributes, changing
@cindex attributes, file

A file is not merely its contents, a name, and a file type
(@pxref{Special file types}).  A file also has an owner (a userid), a
group (a group id), permissions (what the owner can do with the file,
what people in the group can do, and what everyone else can do), various
timestamps, and other information.  Collectively, we call these a file's
@dfn{attributes}.

These commands change file attributes.

@menu
* chown invocation::            Change file owners and groups.
* chgrp invocation::            Change file groups.
* chmod invocation::            Change access permissions.
* touch invocation::            Change file timestamps.
@end menu


@node chown invocation
@section @code{chown}: Change file owner and group

@pindex chown
@cindex file ownership, changing
@cindex group ownerships, changing
@cindex changing file ownership
@cindex changing group ownership

@code{chown} changes the user and/or group ownership of each given @var{file}
to @var{new-owner} or to the user and group of an existing reference file.
Synopsis:

@example
chown [@var{option}]@dots{} @{@var{new-owner} | --reference=@var{file}@} @var{file}@dots{}
@end example

If used, @var{new-owner} specifies the new owner and/or group as follows
(with no embedded white space):

@example
[@var{owner}] [ [:.] [@var{group}] ]
@end example

Specifically:

@table @var
@item owner
If only an @var{owner} (a user name or numeric user id) is given, that
user is made the owner of each given file, and the files' group is not
changed.

@item owner@samp{.}group
@itemx owner@samp{:}group
If the @var{owner} is followed by a colon or dot and a @var{group} (a
group name or numeric group id), with no spaces between them, the group
ownership of the files is changed as well (to @var{group}).

@item owner@samp{.}
@itemx owner@samp{:}
If a colon or dot but no group name follows @var{owner}, that user is
made the owner of the files and the group of the files is changed to
@var{owner}'s login group.

@item @samp{.}group
@itemx @samp{:}group
If the colon or dot and following @var{group} are given, but the owner
is omitted, only the group of the files is changed; in this case,
@code{chown} performs the same function as @code{chgrp}.

@end table

The program accepts the following options.  Also see @ref{Common options}.

@table @samp

@item -c
@itemx --changes
@opindex -c
@opindex --changes
@cindex changed owners, verbosely describing
Verbosely describe the action for each @var{file} whose ownership
actually changes.

@item -f
@itemx --silent
@itemx --quiet
@opindex -f
@opindex --silent
@opindex --quiet
@cindex error messages, omitting
Do not print error messages about files whose ownership cannot be
changed.

@itemx --dereference
@opindex --dereference
@cindex symbolic links, changing owner
@findex lchown
Do not act on symbolic links themselves but rather on what they point to.

@item -h
@itemx --no-dereference
@opindex -h
@opindex --no-dereference
@cindex symbolic links, changing owner
@findex lchown
Act on symbolic links themselves instead of what they point to.
This is the default.
This mode relies on the @code{lchown} system call.
On systems that do not provide the @code{lchown} system call,
@code{chown} fails when a file specified on the command line
is a symbolic link.
By default, no diagnostic is issued for symbolic links encountered
during a recursive traversal, but see @samp{--verbose}.

@item --reference=@var{file}
@opindex --reference
Use the user and group of the reference @var{file} instead of an explicit
@var{new-owner} value.

@item -v
@itemx --verbose
@opindex -v
@opindex --verbose
Verbosely describe the action (or non-action) taken for every @var{file}.
If a symbolic link is encountered during a recursive traversal
on a system without the @code{lchown} system call, and @samp{--no-dereference}
is in effect, then issue a diagnostic saying neither the symbolic link nor
its referent is being changed.

@item -R
@itemx --recursive
@opindex -R
@opindex --recursive
@cindex recursively changing file ownership
Recursively change ownership of directories and their contents.

@end table


@node chgrp invocation
@section @code{chgrp}: Change group ownership

@pindex chgrp
@cindex group ownership, changing
@cindex changing group ownership

@code{chgrp} changes the group ownership of each given @var{file}
to @var{group} (which can be either a group name or a numeric group id)
or to the group of an existing reference file.  Synopsis:

@example
chgrp [@var{option}]@dots{} @{@var{group} | --reference=@var{file}@} @var{file}@dots{}
@end example

The program accepts the following options.  Also see @ref{Common options}.

@table @samp

@item -c
@itemx --changes
@opindex -c
@opindex --changes
@cindex changed files, verbosely describing
Verbosely describe the action for each @var{file} whose group actually
changes.

@item -f
@itemx --silent
@itemx --quiet
@opindex -f
@opindex --silent
@opindex --quiet
@cindex error messages, omitting
Do not print error messages about files whose group cannot be
changed.

@item -f
@itemx --no-dereference
@opindex -f
@opindex --no-dereference
@cindex symbolic links, changing group
@findex lchown
Act on symbolic links themselves instead of what they point to.  Only
available if the @code{lchown} system call is provided.

@item --reference=@var{file}
@opindex --reference
Use the group of the reference @var{file} instead of an explicit
@var{GROUP}.

@item -v
@itemx --verbose
@opindex -v
@opindex --verbose
Verbosely describe the action or non-action taken for every @var{file}.

@item -R
@itemx --recursive
@opindex -R
@opindex --recursive
@cindex recursively changing group ownership
Recursively change the group ownership of directories and their contents.

@end table


@node chmod invocation
@section @code{chmod}: Change access permissions

@pindex chmod
@cindex changing access permissions
@cindex access permissions, changing
@cindex permissions, changing access

@code{chmod} changes the access permissions of the named files.  Synopsis:

@example
chmod [@var{option}]@dots{} @{@var{mode} | --reference=@var{file}@} @var{file}@dots{}
@end example

@cindex symbolic links, permissions of
@code{chmod} never changes the permissions of symbolic links, since
the @code{chmod} system call cannot change their permissions.
This is not a problem since the permissions of symbolic links are
never used.  However, for each symbolic link listed on the command
line, @code{chmod} changes the permissions of the pointed-to file.
In contrast, @code{chmod} ignores symbolic links encountered during
recursive directory traversals.

If used, @var{mode} specifies the new permissions.
For details, see the section on @ref{File permissions}.

The program accepts the following options.  Also see @ref{Common options}.

@table @samp

@item -c
@itemx --changes
@opindex -c
@opindex --changes
Verbosely describe the action for each @var{file} whose permissions
actually changes.

@item -f
@itemx --silent
@itemx --quiet
@opindex -f
@opindex --silent
@opindex --quiet
@cindex error messages, omitting
Do not print error messages about files whose permissions cannot be
changed.

@item -v
@itemx --verbose
@opindex -v
@opindex --verbose
Verbosely describe the action or non-action taken for every @var{file}.

@item --reference=@var{file}
@opindex --reference
Use the mode of the reference @var{file} instead of an explicit @var{MODE}.
@xref{File permissions}.

@item -R
@itemx --recursive
@opindex -R
@opindex --recursive
@cindex recursively changing access permissions
Recursively change permissions of directories and their contents.

@end table


@node touch invocation
@section @code{touch}: Change file timestamps

@pindex touch
@cindex changing file timestamps
@cindex file timestamps, changing
@cindex timestamps, changing file

@code{touch} changes the access and/or modification times of the
specified files.  Synopsis:

@example
touch [@var{option}]@dots{} @var{file}@dots{}
@end example

If the first @var{file} would be a valid argument to the @samp{-t}
option and no timestamp is given with any of the @samp{-d}, @samp{-r},
or @samp{-t} options and the @samp{--} argument is not given, that
argument is interpreted as the time for the other files instead of
as a file name.

@cindex empty files, creating
Any @var{file} that does not exist is created empty.

@cindex permissions, for changing file timestamps
If changing both the access and modification times to the current
time, @code{touch} can change the timestamps for files that the user
running it does not own but has write permission for.  Otherwise, the
user must own the files.

The program accepts the following options.  Also see @ref{Common options}.

@table @samp

@item -a
@itemx --time=atime
@itemx --time=access
@itemx --time=use
@opindex -a
@opindex --time
@opindex atime@r{, changing}
@opindex access @r{time, changing}
@opindex use @r{time, changing}
Change the access time only.

@item -c
@itemx --no-create
@opindex -c
@opindex --no-create
Do not create files that do not exist.

@item -d
@itemx --date=time
@opindex -d
@opindex --date
@opindex time
Use @var{time} instead of the current time.  It can contain month names,
timezones, @samp{am} and @samp{pm}, etc.  @xref{Date input formats}.

@item -f
@opindex -f
@cindex BSD @code{touch} compatibility
Ignored; for compatibility with BSD versions of @code{touch}.

@item -m
@itemx --time=mtime
@itemx --time=modify
@opindex -m
@opindex --time
@opindex mtime@r{, changing}
@opindex modify @r{time, changing}
Change the modification time only.

@item -r @var{file}
@itemx --reference=@var{file}
@opindex -r
@opindex --reference
Use the times of the reference @var{file} instead of the current time.

@item -t [[CC]YY]MMDDhhmm[.ss]
Use the argument (optional four-digit or two-digit years, months,
days, hours, minutes, optional seconds) instead of the current time.
If the year is specified with with only two digits, then @var{CC}
is 20 for years in the range 0 @dots{} 68, and 19 for year in
69 @dots{} 99.  If no digits of the year are specified,
the argument is interpreted as a date in the current year.

@end table


@node Disk usage
@chapter Disk usage

@cindex disk usage

No disk can hold an infinite amount of data.  These commands report on
how much disk storage is in use or available.  (This has nothing much to
do with how much @emph{main memory}, i.e., RAM, a program is using when
it runs; for that, you want @code{ps} or @code{pstat} or @code{swap}
or some such command.)

@menu
* df invocation::               Report filesystem disk space usage.
* du invocation::               Estimate file space usage.
* sync invocation::             Synchronize memory and disk.
@end menu


@node df invocation
@section @code{df}: Report filesystem disk space usage

@pindex df
@cindex filesystem disk usage
@cindex disk usage by filesystem

@code{df} reports the amount of disk space used and available on
filesystems.  Synopsis:

@example
df [@var{option}]@dots{} [@var{file}]@dots{}
@end example

With no arguments, @code{df} reports the space used and available on all
currently mounted filesystems (of all types).  Otherwise, @code{df}
reports on the filesystem containing each argument @var{file}.

Normally the disk space is printed in units of
1024 bytes, but this can be overridden (@pxref{Block size}).

@cindex disk device file
@cindex device file, disk
If an argument @var{file} is a disk device file containing a mounted
filesystem, @code{df} shows the space available on that filesystem
rather than on the filesystem containing the device node (i.e., the root
filesystem).  GNU @code{df} does not attempt to determine the disk usage
on unmounted filesystems, because on most kinds of systems doing so
requires extremely nonportable intimate knowledge of filesystem
structures.

The program accepts the following options.  Also see @ref{Common options}.

@table @samp

@item -a
@itemx --all
@opindex -a
@opindex --all
@cindex automounter filesystems
@cindex ignore filesystems
Include in the listing filesystems that have a size of 0 blocks, which
are omitted by default.  Such filesystems are typically special-purpose
pseudo-filesystems, such as automounter entries.  Also, filesystems of
type ``ignore'' or ``auto'', supported by some operating systems, are
only included if this option is specified.

@item -h
@itemx --human-readable
@opindex -h
@opindex --human-readable
@cindex human-readable output
Append a size letter such as @samp{M} for megabytes to each size.
Powers of 1024 are used, not 1000; @samp{M} stands for 1,048,576 bytes.
Use the @samp{-H} or @samp{--si} option if you prefer powers of 1000.

@item -H
@itemx --si
@opindex -H
@opindex --si
@cindex SI output
Append a size letter such as @samp{M} for megabytes to each size.  (SI
is the International System of Units, which defines these letters as
prefixes.)  Powers of 1000 are used, not 1024; @samp{M} stands for
1,000,000 bytes.  Use the @samp{-h} or @samp{--human-readable} option if
you prefer powers of 1024.

@item -i
@itemx --inodes
@opindex -i
@opindex --inodes
@cindex inode usage
List inode usage information instead of block usage.  An inode (short
for index node) is contains information about a file such as its owner,
permissions, timestamps, and location on the disk.

@item -k
@itemx --kilobytes
@opindex -k
@opindex --kilobytes
@cindex kilobytes for filesystem sizes
Print sizes in 1024-byte blocks, overriding the default block size
(@pxref{Block size}).

@item -l
@itemx --local
@opindex -l
@opindex --local
@cindex filesystem types, limiting output to certain
Limit the listing to local filesystems.  By default, remote filesystems
are also listed.

@item -m
@itemx --megabytes
@opindex -m
@opindex --megabytes
@cindex megabytes for filesystem sizes
Print sizes in megabyte (that is, 1,048,576-byte) blocks.

@itemx --no-sync
@opindex --no-sync
@cindex filesystem space, retrieving old data more quickly
Do not invoke the @code{sync} system call before getting any usage data.
This may make @code{df} run significantly faster on systems with many
disks, but on some systems (notably SunOS) the results may be slightly
out of date.  This is the default.

@item -P
@itemx --portability
@opindex -P
@opindex --portability
@cindex one-line output format
@cindex POSIX output format
@cindex portable output format
@cindex output format, portable
Use the @sc{POSIX} output format.  This is like the default format except
that the information about each filesystem is always printed on exactly
one line; a mount device is never put on a line by itself.  This means
that if the mount device name is more than 20 characters long (e.g., for
some network mounts), the columns are misaligned.

@itemx --sync
@opindex --sync
@cindex filesystem space, retrieving current data more slowly
Invoke the @code{sync} system call before getting any usage data.  On
some systems (notably SunOS), doing this yields more up to date results,
but in general this option makes @code{df} much slower, especially when
there are many or very busy filesystems.

@item -t @var{fstype}
@itemx --type=@var{fstype}
@opindex -t
@opindex --type
@cindex filesystem types, limiting output to certain
Limit the listing to filesystems of type @var{fstype}.  Multiple
filesystem types can be specified by giving multiple @samp{-t} options.
By default, nothing is omitted.

@item -T
@itemx --print-type
@opindex -T
@opindex --print-type
@cindex filesystem types, printing
Print each filesystem's type.  The types printed here are the same ones
you can include or exclude with @samp{-t} and @samp{-x}.  The particular
types printed are whatever is supported by the system.  Here are some of
the common names (this list is certainly not exhaustive):

@table @samp

@item nfs
@cindex NFS filesystem type
An NFS filesystem, i.e., one mounted over a network from another
machine.  This is the one type name which seems to be used uniformly by
all systems.

@item 4.2@r{, }ufs@r{, }efs@dots{}
@cindex Linux filesystem types
@cindex local filesystem types
@opindex 4.2 @r{filesystem type}
@opindex ufs @r{filesystem type}
@opindex efs @r{filesystem type}
A filesystem on a locally-mounted hard disk.  (The system might even
support more than one type here; Linux does.)

@item hsfs@r{, }cdfs
@cindex CD-ROM filesystem type
@cindex High Sierra filesystem
@opindex hsfs @r{filesystem type}
@opindex cdfs @r{filesystem type}
A filesystem on a CD-ROM drive.  HP-UX uses @samp{cdfs}, most other
systems use @samp{hsfs} (@samp{hs} for `High Sierra').

@item pcfs
@cindex PC filesystem
@cindex DOS filesystem
@cindex MS-DOS filesystem
@cindex diskette filesystem
@opindex pcfs
An MS-DOS filesystem, usually on a diskette.

@end table

@item -x @var{fstype}
@itemx --exclude-type=@var{fstype}
@opindex -x
@opindex --exclude-type
Limit the listing to filesystems not of type @var{fstype}.
Multiple filesystem types can be eliminated by giving multiple
@samp{-x} options.  By default, no filesystem types are omitted.

@item -v
Ignored; for compatibility with System V versions of @code{df}.

@end table


@node du invocation
@section @code{du}: Estimate file space usage

@pindex du
@cindex file space usage
@cindex disk usage for files

@code{du} reports the amount of disk space used by the specified files
and for each subdirectory (of directory arguments).  Synopsis:

@example
du [@var{option}]@dots{} [@var{file}]@dots{}
@end example

With no arguments, @code{du} reports the disk space for the current
directory.  Normally the disk space is printed in units of
1024 bytes, but this can be overridden (@pxref{Block size}).

The program accepts the following options.  Also see @ref{Common options}.

@table @samp

@item -a
@itemx --all
@opindex -a
@opindex --all
Show counts for all files, not just directories.

@item -b
@itemx --bytes
@opindex -b
@opindex --bytes
Print sizes in bytes, overriding the default block size (@pxref{Block size}).

@item -c
@itemx --total
@opindex -c
@opindex --total
@cindex grand total of disk space
Print a grand total of all arguments after all arguments have
been processed.  This can be used to find out the total disk usage of
a given set of files or directories.

@item -D
@itemx --dereference-args
@opindex -D
@opindex --dereference-args
Dereference symbolic links that are command line arguments.
Does not affect other symbolic links.  This is helpful for finding
out the disk usage of directories, such as @file{/usr/tmp}, which
are often symbolic links.

@item -h
@itemx --human-readable
@opindex -h
@opindex --human-readable
@cindex human-readable output
Append a size letter such as @samp{M} for megabytes to each size.
Powers of 1024 are used, not 1000; @samp{M} stands for 1,048,576 bytes.
Use the @samp{-H} or @samp{--si} option if you prefer powers of 1000.

@item -H
@itemx --si
@opindex -H
@opindex --si
@cindex SI output
Append a size letter such as @samp{M} for megabytes to each size.  (SI
is the International System of Units, which defines these letters as
prefixes.)  Powers of 1000 are used, not 1024; @samp{M} stands for
1,000,000 bytes.  Use the @samp{-h} or @samp{--human-readable} option if
you prefer powers of 1024.

@item -k
@itemx --kilobytes
@opindex -k
@opindex --kilobytes
Print sizes in 1024-byte blocks, overriding the default block size
(@pxref{Block size}).

@item -l
@itemx --count-links
@opindex -l
@opindex --count-links
@cindex hard links, counting in @code{du}
Count the size of all files, even if they have appeared already (as a
hard link).

@item -L
@itemx --dereference
@opindex -L
@opindex --dereference
@cindex symbolic links, dereferencing in @code{du}
Dereference symbolic links (show the disk space used by the file
or directory that the link points to instead of the space used by
the link).

@itemx --max-depth=@var{DEPTH}
@opindex --max-depth=@var{DEPTH}
@cindex limiting output of @code{du}
Show the total for each directory (and file if --all) that is at
most MAX_DEPTH levels down from the root of the hierarchy.  The root
is at level 0, so @code{du --max-depth=0} is equivalent to @code{du -s}.

@item -m
@itemx --megabytes
@opindex -m
@opindex --megabytes
@cindex megabytes for filesystem sizes
Print sizes in megabyte (that is, 1,048,576-byte) blocks.

@item -s
@itemx --summarize
@opindex -s
@opindex --summarize
Display only a total for each argument.

@item -S
@itemx --separate-dirs
@opindex -S
@opindex --separate-dirs
Report the size of each directory separately, not including the sizes
of subdirectories.

@item -x
@itemx --one-file-system
@opindex -x
@opindex --one-file-system
@cindex one filesystem, restricting @code{du} to
Skip directories that are on different filesystems from the one that
the argument being processed is on.

@itemx --exclude=@var{PAT}
@opindex --exclude=@var{PAT}
@cindex excluding files from @code{du}
When recursing, skip subdirectories or files matching @var{PAT}.
For example, @code{du --exclude='*.o'} excludes files whose names
end in @samp{.o}.

@item -X @var{FILE}
@itemx --exclude-from=@var{FILE}
@opindex -X @var{FILE}
@opindex --exclude-from=@var{FILE}
@cindex excluding files from @code{du}
Like @samp{--exclude}, except take the patterns to exclude from @var{FILE},
one per line.  If @var{FILE} is @samp{-}, take the patterns from standard
input.

@end table

@cindex NFS mounts from BSD to HP-UX
On BSD systems, @code{du} reports sizes that are half the correct
values for files that are NFS-mounted from HP-UX systems.  On HP-UX
systems, it reports sizes that are twice the correct values for
files that are NFS-mounted from BSD systems.  This is due to a flaw
in HP-UX; it also affects the HP-UX @code{du} program.


@node sync invocation
@section @code{sync}: Synchronize data on disk with memory

@pindex sync
@cindex synchronize disk and memory

@cindex superblock, writing
@cindex inodes, written buffered
@code{sync} writes any data buffered in memory out to disk.  This can
include (but is not limited to) modified superblocks, modified inodes,
and delayed reads and writes.  This must be implemented by the kernel;
The @code{sync} program does nothing but exercise the @code{sync} system
call.

@cindex crashes and corruption
The kernel keeps data in memory to avoid doing (relatively slow) disk
reads and writes.  This improves performance, but if the computer
crashes, data may be lost or the filesystem corrupted as a
result. @code{sync} ensures everything in memory is written to disk.

Any arguments are ignored, except for a lone @samp{--help} or
@samp{--version} (@pxref{Common options}).


@node Index
@unnumbered Index

@printindex cp

@contents
@bye

@c Local variables:
@c texinfo-column-for-description: 32
@c End:
