\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 filenames 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
@set Francois Franc,ois
@end ifinfo
@tex
@set Francois Fran\noexpand\ptexc cois
@end tex

@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.
* 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 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 fileutils, version @value{VERSION}
@subtitle A set of file utilities
@subtitle for version @value{VERSION}, @value{RELEASEDATE}
@author David MacKenzie et al.

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1994 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


@ifinfo
@node Top
@top GNU file utilities

@cindex file utilities
@cindex utilities for file handling

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

@menu
* Introduction::		Caveats, overview, and authors.
* Common options::              Common options.
* File permissions::		Access modes.
* Directory listing::           ls dir vdir d v
* 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
@end ifinfo


@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 POSIX.2 standard.

@cindex bugs, reporting
Please report bugs to @samp{bug-gnu-utils@@prep.ai.mit.edu}.  Remember
to include the version number, machine architecture, input files, and
any other information needed to reproduce the bug.  @xref{Bugs, , , gcc,
GNU CC}.

@cindex history
This manual is based on the Unix man pages in the distribution, which
were originally written by David MacKenzie and updated by Jim Meyering.
@c If the following space before `@value' is removed, makeinfo
@c fails to substitute the value for Francois.  Instead, it reports
@c `F{No Value For "rancois"}...'. This is a bug in makeinfo.
@c So please don't remove that leading space for now.
 @value{Francois} 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 these programs.  Rather than
writing identical descriptions for each of the programs, they are
described here.  (In fact, every GNU program accepts (or should accept)
these options.)

@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.
@end menu


@node Backup options
@section Backup options

@cindex backup options

Some GNU programs (at least @code{cp}, @code{mv}, and @code{ln})
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 backups of files that are about to 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 File permissions
@chapter File permissions

@cindex file permissions
@cindex permissions of files

@include perm.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.
@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 filename.  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); otherwise,
they are listed one per line.

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
Also, 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::          
* General output formatting::   
* Formatting the filenames::
@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
@itemx --ignore
@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 filename does not match a
wildcard at the start of @var{pattern}.

@item -L
@itemx --dereference
@opindex -L
@opindex --dereference
@cindex symbolic links, dereferencing
List the files linked to by symbolic links instead of listing the
contents of the links.

@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 filenames 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 which record the
byte position of the beginning and end of each filename 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{beg1 end1 @dots{}}
@end example

@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 -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 filename.  (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 6 months old or more than 1 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
@code{total @var{blocks}}, where @var{blocks} is the total disk space
used by all files in that directory.  By default, 1024-byte blocks are
used; if the environment variable @code{POSIXLY_CORRECT} is set,
512-byte blocks are used (unless the @samp{-k} option is given).
The @var{blocks} computed counts each hard link separately;
this is arguably a bug.

This output format is the default for the GNU @code{v} and @code{vdir}
programs.

@item -s
@itemx --size
@opindex -s
@opindex --size
@cindex size of files, reporting
@vindex POSIXLY_CORRECT@r{, overrides @code{ls -s}}
Print the size of each file in 1024-byte blocks to the left of the
filename.  If the environment variable @code{POSIXLY_CORRECT} is set,
512-byte blocks are used instead, unless the @samp{-k} option is given
(@pxref{General output formatting}).

@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
@itemx --time=ctime
@itemx --time=status
@opindex -c
@opindex --time
@opindex ctime@r{, sorting by}
@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
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} 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
@itemx --time=atime
@itemx --time=access
@itemx --time=use
@opindex -u
@opindex --time
@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 -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 -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 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.

@item -F
@itemx --classify
@opindex -F
@opindex --classify
@cindex file type and executables, marking
@cindex executables and file type, marking
Append a character to each filename 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 -k
@itemx --kilobytes
@opindex -k
@opindex --kilobytes
@vindex POSIXLY_CORRECT@r{, overridden by @code{ls -k}}
If file sizes are being listed, print them in kilobytes.  This
overrides the environment variable @code{POSIXLY_CORRECT}.

@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
@cindex file type, marking
Append a character to each filename indicating the file type. This is
like @samp{-F}, except that executables are not marked.

@item -x
@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
@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.

@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 filenames
@subsection Formatting the filenames

These options change how filenames themselves are printed.

@table @samp

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

@item -N
@itemx --literal
@opindex -N
@opindex --literal
Do not quote filenames.

@item -q
@itemx --hide-control-chars
@opindex -q
@opindex --hide-control-chars
Print question marks instead of nongraphic characters in filenames.
This is the default.

@item -Q
@itemx --quote-name
@opindex -Q
@opindex --quote-name
Enclose filenames in double quotes and quote nongraphic characters as
in C.

@end table


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

@pindex dir
@cindex directory listing, brief

The @code{dir} program (also installed as @code{d}) is equivalent to
@code{ls -C}; that is, files are by default always listed in columns,
sorted vertically.

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


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

@pindex vdir
@cindex directory listing, verbose

The @code{vdir} program (also installed @code{v})is equivalent to
@code{ls -l}; that is, files are by default listed in long format.


@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.

@cindex holes, copying
@findex read @r{system call, and holes}
If the source file contains holes, @code{cp} copies them and other
blocks of zero bytes as holes.  Otherwise, files are written just as
they are read.  (A @dfn{hole} is a sequence of zero bytes that does not
occupy any physical disk blocks; the @samp{read} system call reads these
as zeroes.)

By default, @code{cp} does not copy directories.  It also refuses to
copy a file onto itself.

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.  Equivalent to @samp{-dpR}.

@item -b
@itemx --backup
@opindex -b
@opindex --backup
@cindex backups, making
Make backups of files that are about to 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.  Thus, with this option, @code{cp}
may well hang indefinitely reading a FIFO, unless something else happens
to be writing it.

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

@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
filenames 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.

@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 blocksize, 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{k}=1024,
@samp{w}=2, @samp{x@var{m}}=@var{m}.

@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{obs}-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 -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 -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.

@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 backups of files that are about to 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.

@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.

@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 being 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{source} [@var{dest}]
ln [@var{option}]@dots{} @var{source}@dots{} @var{directory}
@end example

If the last argument names an existing directory, @code{ln} links each
@var{source} file into a file with the same name in that directory.
(But see the description of the @samp{--no-dereference} option below.)
If only one file is given, it links that file into the current directory.
Otherwise, if only two files are given, it links the first onto the
second.  It is an error if the last argument is not a directory and more
than two files are given.  By default, it does not remove existing
files.

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 links to
directories, and hard links cannot cross filesystem boundaries.  (These
restrictions are not mandated by POSIX, however.)

@cindex dereferencing symbolic links
@dfn{Symbolic links} (@dfn{symlinks} for short), on the other hand, are
a special file type (which not all kernels support; in particular,
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 backups of files that are about to 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 used with @samp{--force} and an explicit destination that is a
symlink to a directory, remove (or move it with @samp{--backup}) that
symlink before making any link.

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 -v
@itemx --verbose
@opindex -v
@opindex --verbose
Print the name of each file before linking 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 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.

@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 (buffered) special file

@item c
@opindex c @r{for character special file}
@cindex buffered character file
for a character (buffered) special file

@item u
@opindex u @r{for unbuffered character special file}
@cindex unbuffered character special file
for a character (unbuffered) 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

@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.

@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

Files are not merely contents, a name, and a file type (@pxref{Special
file types}).  They also have 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 all this 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
file.  Synopsis:

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

The first non-option argument, @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.

@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 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.
Synopsis:

@example
chgrp [@var{option}]@dots{} @var{group} @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 -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} @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.

The first non-option argument, @var{mode}, specifies the new
permissions.  See the section below for details.

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 -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 filename.

@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 invocation,
@code{date} invocation, , sh-utils, Shell utilities}.

@item -f
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{reference-file}
@itemx --file=@var{reference-file}
@opindex -r
@opindex --file
Use the times of @var{reference-file} instead of the current time.

@item -t MMDDhhmm[[CC]YY][.ss]
Use the argument (months, days, hours, minutes, optional century and
years, optional seconds) instead of the current time.

@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}.

@vindex POSIXLY_CORRECT
Disk space is shown in 1024-byte blocks by default, unless the
environment variable @code{POSIXLY_CORRECT} is set, in which case
512-byte blocks are used (unless the @samp{-k} option is given).

@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 0 blocks, which are omitted
by default.  Such filesystems are typically special-purpose
pseudo-filesystems, such as automounter entries.  Filesystems of type
``ignore'' or ``auto'', supported by some operating systems, are only
included in the listing if this option is specified.

@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
@vindex POSIXLY_CORRECT@r{, overridden by @code{df -k}}
Print sizes in 1024-byte blocks.  This overrides the environment
variable @code{POSIXLY_CORRECT}.

@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 the results may be slightly out of date.

@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 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, 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.  The output is in 1024-byte units by default, unless the
environment variable @code{POSIXLY_CORRECT} is set, in which case
512-byte blocks are used (unless @samp{-k} is specified).

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, instead of kilobytes.

@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 -k
@itemx --kilobytes
@opindex -k
@opindex --kilobytes
@vindex POSIXLY_CORRECT@r{, overridden by @code{du -k}}
Print sizes in kilobytes.  This overrides the environment variable
@code{POSIXLY_CORRECT}.

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

@item -L
@itemx --dereference
@opindex -L
@opindex --dereference
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).

@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.

@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:
