   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.

   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.

GNU file utilities
******************

   This manual minimally documents version 3.13 of the GNU file
utilities.

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.

   The GNU file utilities are mostly compatible with the POSIX.2
standard.

   Please report bugs to `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: 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. See Bugs (gcc).

   This manual is based on the Unix man pages in the distribution, which
were originally written by David MacKenzie and updated by Jim Meyering.
Franc,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.

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.

`--help'
     Print a usage message listing all available options, then exit
     successfully.

`--version'
     Print the version number, then exit successfully.

Backup options
==============

   Some GNU programs (at least `cp', `install', `ln', and `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.

`-b'
`--backup'
     Make backups of files that are about to be overwritten or removed.
     Without this option, the original versions are destroyed.

`-S SUFFIX'
`--suffix=SUFFIX'
     Append SUFFIX to each backup file made with `-b'.  If this option
     is not specified, the value of the `SIMPLE_BACKUP_SUFFIX'
     environment variable is used.  And if `SIMPLE_BACKUP_SUFFIX' is not
     set, the default is `~', just as in Emacs.

`-V METHOD'
`--version-control=METHOD'
     Use METHOD to determine the type of backups made with `-b'.  If
     this option is not specified, the value of the `VERSION_CONTROL'
     environment variable is used.  And if `VERSION_CONTROL' is not set,
     the default backup type is `existing'.

     This option corresponds to the Emacs variable `version-control';
     the same values for METHOD are accepted as in Emacs.  This options
     also more descriptive name.  The valid METHODs (unique
     abbreviations are accepted):

    `t'
    `numbered'
          Always make numbered backups.

    `nil'
    `existing'
          Make numbered backups of files that already have them, simple
          backups of the others.

    `never'
    `simple'
          Always make simple backups.

File permissions
****************

   Each file has a set of "permissions" that control the kinds of
access that users have to that file.  The permissions for a file are
also called its "access mode".  They can be represented either in
symbolic form or as an octal number.

Structure of File Permissions
=============================

   There are three kinds of permissions that a user can have for a file:

  1. permission to read the file.  For directories, this means
     permission to list the contents of the directory.

  2. permission to write to (change) the file.  For directories, this
     means permission to create and remove files in the directory.

  3. permission to execute the file (run it as a program).  For
     directories, this means permission to access files in the
     directory.

   There are three categories of users who may have different
permissions to perform any of the above operations on a file:

  1. the file's owner;

  2. other users who are in the file's group;

  3. everyone else.

   Files are given an owner and group when they are created.  Usually
the owner is the current user and the group is the group of the
directory the file is in, but this varies with the operating system, the
filesystem the file is created on, and the way the file is created.  You
can change the owner and group of a file by using the `chown' and
`chgrp' commands.

   In addition to the three sets of three permissions listed above, a
file's permissions have three special components, which affect only
executable files (programs) and, on some systems, directories:

  1. set the process's effective user ID to that of the file upon
     execution (called the "setuid bit").  No effect on directories.

  2. set the process's effective group ID to that of the file upon
     execution (called the "setgid bit").  For directories on some
     systems, put files created in the directory into the same group as
     the directory, no matter what group the user who creates them is
     in.

  3. save the program's text image on the swap device so it will load
     more quickly when run (called the "sticky bit").  For directories
     on some systems, prevent users from removing files that they do
     not own in the directory; this is called making the directory
     "append-only".

Symbolic Modes
==============

   "Symbolic modes" represent changes to files' permissions as
operations on single-character symbols.  They allow you to modify either
all or selected parts of files' permissions, optionally based on their
previous values, and perhaps on the current `umask' as well (see
Umask and Protection.).

   The format of symbolic modes is:

     [ugoa...][[+-=][rwxXstugo...]...][,...]

   The following sections describe the operators and other details of
symbolic modes.

Setting Permissions
-------------------

   The basic symbolic operations on a file's permissions are adding,
removing, and setting the permission that certain users have to read,
write, and execute the file.  These operations have the following
format:

     USERS OPERATION PERMISSIONS

The spaces between the three parts above are shown for readability only;
symbolic modes can not contain spaces.

   The USERS part tells which users' access to the file is changed.  It
consists of one or more of the following letters (or it can be empty;
see Umask and Protection., for a description of what happens then).
When more than one of these letters is given, the order that they are
in does not matter.

`u'
     the user who owns the file;

`g'
     other users who are in the file's group;

`o'
     all other users;

`a'
     all users; the same as `ugo'.

   The OPERATION part tells how to change the affected users' access to
the file, and is one of the following symbols:

`+'
     to add the PERMISSIONS to whatever permissions the USERS already
     have for the file;

`-'
     to remove the PERMISSIONS from whatever permissions the USERS
     already have for the file;

`='
     to make the PERMISSIONS the only permissions that the USERS have
     for the file.

   The PERMISSIONS part tells what kind of access to the file should be
changed; it is zero or more of the following letters.  As with the
USERS part, the order does not matter when more than one letter is
given.  Omitting the PERMISSIONS part is useful only with the `='
operation, where it gives the specified USERS no access at all to the
file.

`r'
     the permission the USERS have to read the file;

`w'
     the permission the USERS have to write to the file;

`x'
     the permission the USERS have to execute the file.

   For example, to give everyone permission to read and write a file,
but not to execute it, use:

     a=rw

   To remove write permission for from all users other than the file's
owner, use:

     go-w

The above command does not affect the access that the owner of the file
has to it, nor does it affect whether other users can read or execute
the file.

   To give everyone except a file's owner no permission to do anything
with that file, use the mode below.  Other users could still remove the
file, if they have write permission on the directory it is in.

     go=

Another way to specify the same thing is:

     og-rxw

Copying Existing Permissions
----------------------------

   You can base a file's permissions on its existing permissions.  To do
this, instead of using `r', `w', or `x' after the operator, you use the
letter `u', `g', or `o'.  For example, the mode
     o+g

adds the permissions for users who are in a file's group to the
permissions that other users have for the file.  Thus, if the file
started out as mode 664 (`rw-rw-r--'), the above mode would change it
to mode 666 (`rw-rw-rw-').  If the file had started out as mode 741
(`rwxr----x'), the above mode would change it to mode 745
(`rwxr--r-x').  The `-' and `=' operations work analogously.

Changing Special Permissions
----------------------------

   In addition to changing a file's read, write, and execute
permissions, you can change its special permissions.  See Mode Structure,
for a summary of these permissions.

   To change a file's permission to set the user ID on execution, use
`u' in the USERS part of the symbolic mode and `s' in the PERMISSIONS
part.

   To change a file's permission to set the group ID on execution, use
`g' in the USERS part of the symbolic mode and `s' in the PERMISSIONS
part.

   To change a file's permission to stay permanently on the swap device,
use `o' in the USERS part of the symbolic mode and `t' in the
PERMISSIONS part.

   For example, to add set user ID permission to a program, you can use
the mode:

     u+s

   To remove both set user ID and set group ID permission from it, you
can use the mode:

     ug-s

   To cause a program to be saved on the swap device, you can use the
mode:

     o+t

   Remember that the special permissions only affect files that are
executable, plus, on some systems, directories (on which they have
different meanings; see Mode Structure.).  Using `a' in the USERS
part of a symbolic mode does not cause the special permissions to be
affected; thus,

     a+s

has *no effect*.  You must use `u', `g', and `o' explicitly to affect
the special permissions.  Also, the combinations `u+t', `g+t', and
`o+s' have no effect.

   The `=' operator is not very useful with special permissions; for
example, the mode:

     o=t

does cause the file to be saved on the swap device, but it also removes
all read, write, and execute permissions that users not in the file's
group might have had for it.

Conditional Executability
-------------------------

   There is one more special type of symbolic permission: if you use
`X' instead of `x', execute permission is affected only if the file
already had execute permission or is a directory.  It affects
directories' execute permission even if they did not initially have any
execute permissions set.

   For example, this mode:

     a+X

gives all users permission to execute files (or search directories) if
anyone could before.

Making Multiple Changes
-----------------------

   The format of symbolic modes is actually more complex than described
above (see Setting Permissions.).  It provides two ways to make
multiple changes to files' permissions.

   The first way is to specify multiple OPERATION and PERMISSIONS parts
after a USERS part in the symbolic mode.

   For example, the mode:

     og+rX-w

gives users other than the owner of the file read permission and, if it
is a directory or if someone already had execute permission to it,
gives them execute permission; and it also denies them write permission
to it file.  It does not affect the permission that the owner of the
file has for it.  The above mode is equivalent to the two modes:

     og+rX
     og-w

   The second way to make multiple changes is to specify more than one
simple symbolic mode, separated by commas.  For example, the mode:

     a+r,go-w

gives everyone permission to read the file and removes write permission
on it for all users except its owner.  Another example:

     u=rwx,g=rx,o=

sets all of the non-special permissions for the file explicitly.  (It
gives users who are not in the file's group no permission at all for
it.)

   The two methods can be combined.  The mode:

     a+r,g+x-w

gives all users permission to read the file, and gives users who are in
the file's group permission to execute it, as well, but not permission
to write to it.  The above mode could be written in several different
ways; another is:

     u+r,g+rx,o+r,g-w

The Umask and Protection
------------------------

   If the USERS part of a symbolic mode is omitted, it defaults to `a'
(affect all users), except that any permissions that are *set* in the
system variable `umask' are *not affected*.  The value of `umask' can
be set using the `umask' command.  Its default value varies from system
to system.

   Omitting the USERS part of a symbolic mode is generally not useful
with operations other than `+'.  It is useful with `+' because it
allows you to use `umask' as an easily customizable protection against
giving away more permission to files than you intended to.

   As an example, if `umask' has the value 2, which removes write
permission for users who are not in the file's group, then the mode:

     +w

adds permission to write to the file to its owner and to other users who
are in the file's group, but *not* to other users.  In contrast, the
mode:

     a+w

ignores `umask', and *does* give write permission for the file to all
users.

Numeric Modes
=============

   File permissions are stored internally as 16 bit integers.  As an
alternative to giving a symbolic mode, you can give an octal (base 8)
number that corresponds to the internal representation of the new mode.
This number is always interpreted in octal; you do not have to add a
leading 0, as you do in C.  Mode 0055 is the same as mode 55.

   A numeric mode is usually shorter than the corresponding symbolic
mode, but it is limited in that it can not take into account a file's
previous permissions; it can only set them absolutely.

   The permissions granted to the user, to other users in the file's
group, and to other users not in the file's group are each stored as
three bits, which are represented as one octal digit.  The three special
permissions are also each stored as one bit, and they are as a group
represented as another octal digit.  Here is how the bits are arranged
in the 16 bit integer, starting with the lowest valued bit:

     Value in  Corresponding
     Mode      Permission

               Other users not in the file's group:
        1      Execute
        2      Write
        4      Read

               Other users in the file's group:
       10      Execute
       20      Write
       40      Read

               The file's owner:
      100      Execute
      200      Write
      400      Read

               Special permissions:
     1000      Save text image on swap device
     2000      Set group ID on execution
     4000      Set user ID on execution

   For example, numeric mode 4755 corresponds to symbolic mode
`u=rwxs,go=rx', and numeric mode 664 corresponds to symbolic mode
`ug=rw,o=r'.  Numeric mode 0 corresponds to symbolic mode `ugo='.

Date input formats
******************

   This section describes the textual date representations that GNU
programs accept.  These are the strings you, as a user, can supply as
arguments to the various programs.  The C interface (via the `getdate'
function) is not described here.

   Although the date syntax here can represent any possible time since
zero A.D., computer integers are not big enough for such a
(comparatively) long time.  The earliest date semantically allowed on
Unix systems is midnight, 1 January 1970 UCT.

General date syntax
===================

   A "date" is a string, possibly empty, containing many items
separated by whitespace.  The whitespace may be omitted when no
ambiguity arises.  The empty string means the beginning of today (i.e.,
midnight).  Order of the items is immaterial.  A date string may contain
many flavors of items:

   * calendar date items

   * time of the day items

   * time zone items

   * day of the week items

   * relative items

   * pure numbers.

We describe each of these item types in turn, below.

   A few numbers may be written out in words in most contexts.  This is
most useful for specifying day of the week items or relative items (see
below).  Here is the list: `first' for 1, `next' for 2, `third' for 3,
`fourth' for 4, `fifth' for 5, `sixth' for 6, `seventh' for 7, `eighth'
for 8, `ninth' for 9, `tenth' for 10, `eleventh' for 11 and `twelfth'
for 12.  Also, `last' means exactly -1.

   When a month is written this way, it is still considered to be
written numerically, instead of being "spelled in full"; this changes
the allowed strings.

   Alphabetic case is completely ignored in dates.  Comments may be
introduced between round parentheses, as long as included parentheses
are properly nested.  Hyphens not followed by a digit are currently
ignored.  Leading zeros on numbers are ignored.

Calendar date item
==================

   A "calendar date item" specifies a day of the year.  It is specified
differently, depending on whether the month is specified numerically or
literally.  All these strings specify the same calendar date:

     1970-09-17           # ISO 8601.
     70-9-17              # This century assumed by default.
     70-09-17             # Leading zeros are ignored.
     9/17/72              # Common U.S. writing.
     24 September 1972
     24 Sept 72           # September has a special abbreviation.
     24 Sep 72            # Three-letter abbreviations always allowed.
     Sep 24, 1972
     24-sep-72
     24sep72

   The year can also be omitted.  In this case, the last specified year
is used, or the current year if none.  For example:

     9/17
     sep 17

   Here are the rules.

   For numeric months, the ISO 8601 format `YEAR-MONTH-DAY' is allowed,
where YEAR is any positive number, MONTH is a number between 01 and 12,
and DAY is a number between 01 and 31.  A leading zero must be present
if a number is less than ten.  If YEAR is less than 100, then 1900 is
added to it to force a date in this century.  The construct
`MONTH/DAY/YEAR', popular in the United States, is accepted.  Also
`MONTH/DAY', omitting the year.

   Literal months may be spelled out in full: `January', `February',
`March', `April', `May', `June', `July', `August', `September',
`October', `November' or `December'.  Literal months may be abbreviated
to their first three letters, possibly followed by an abbreviating dot.
It is also permitted to write `Sept' instead of `September'.

   When months are written literally, the calendar date may be given as
any of the following:

     DAY MONTH YEAR
     DAY MONTH
     MONTH DAY YEAR
     DAY-MONTH-YEAR

   Or, omitting the year:

     MONTH DAY

Time of day item
================

   A "time of day item" in date strings specifies the time on a given
day.  Here are some examples, all of which represent the same time:

     20:02:0
     20:02
     8:02pm
     20:02-0500      # In EST (Eastern U.S. Standard Time).

   More generally, the time of the day may be given as
`HOUR:MINUTE:SECOND', where HOUR is a number between 0 and 23, MINUTE
is a number between 0 and 59, and SECOND is a number between 0 and 59.
Alternatively, `:SECOND' can be omitted, in which case it is taken to
be zero.

   If the time is followed by `am' or `pm' (or `a.m.' or `p.m.'), HOUR
is restricted to run from 1 to 12, and `:MINUTE' may be omitted (taken
to be zero).  `am' indicates the first half of the day, `pm' indicates
the second half of the day.  In this notation, 12 is the predecessor of
1: midnight is `12am' while noon is `12pm'.

   The time may alternatively be followed by a timezone correction,
expressed as `SHHMM', where S is `+' or `-', HH is a number of zone
hours and MM is a number of zone minutes.  When a timezone correction
is given this way, it forces interpretation of the time in UTC,
overriding any previous specification for the timezone or the local
timezone.  The MINUTE part of the time of the day may not be elided
when a timezone correction is used.  This is the only way to specify a
timezone correction by fractional parts of an hour.

   Either `am'/`pm' or a timezone correction may be specified, but not
both.

Timezone item
=============

   A "timezone item" specifies an international timezone, indicated by
a small set of letters.  Any included period is ignored.  Military
timezone designations use a single letter.  Currently, only integral
zone hours may be represented in a timezone item.  See the previous
section for a finer control over the timezone correction.

   Here are many non-daylight-savings-time timezones, indexed by the
zone hour value.

+000
     `GMT' for Greenwich Mean, `UT' or `UTC' for Universal
     (Coordinated), `WET' for Western European and `Z' for militaries.

+100
     `WAT' for West Africa and `A' for militaries.

+200
     `AT' for Azores and `B' for militaries.

+300
     `C' for militaries.

+400
     `AST' for Atlantic Standard and `D' for militaries.

+500
     `E' for militaries and `EST' for Eastern Standard.

+600
     `CST' for Central Standard and `F' for militaries.

+700
     `G' for militaries and `MST' for Mountain Standard.

+800
     `H' for militaries and `PST' for Pacific Standard.

+900
     `I' for militaries and `YST' for Yukon Standard.

+1000
     `AHST' for Alaska-Hawaii Standard, `CAT' for Central Alaska, `HST'
     for Hawaii Standard and `K' for militaries.

+1100
     `L' for militaries and `NT' for Nome.

+1200
     `IDLW' for International Date Line West and `M' for militaries.

-100
     `CET' for Central European, `FWT' for French Winter, `MET' for
     Middle European, `MEWT' for Middle European Winter, `N' for
     militaries and `SWT' for Swedish Winter.

-200
     `EET' for Eastern European, USSR Zone 1 and `O' for militaries.

-300
     `BT' for Baghdad, USSR Zone 2 and `P' for militaries.

-400
     `Q' for militaries and `ZP4' for USSR Zone 3.

-500
     `R' for militaries and `ZP5' for USSR Zone 4.

-600
     `S' for militaries and `ZP6' for USSR Zone 5.

-700
     `T' for militaries and `WAST' for West Australian Standard.

-800
     `CCT' for China Coast, USSR Zone 7 and `U' for militaries.

-900
     `JST' for Japan Standard, USSR Zone 8 and `V' for militaries.

-1000
     `EAST' for East Australian Standard, `GST' for Guam Standard, USSR
     Zone 9 and `W' for militaries.

-1100
     `X' for militaries.

-1200
     `IDLE' for International Date Line East, `NZST' for New Zealand
     Standard, `NZT' for New Zealand and `Y' for militaries.

   Here are many DST timezones, indexed by the zone hour value.  Also,
by following a non-DST timezone by the string `DST' in a separate word
(that is, separated by some whitespace), the corresponding DST timezone
may be specified.

0
     `BST' for British Summer.

+400
     `ADT' for Atlantic Daylight.

+500
     `EDT' for Eastern Daylight.

+600
     `CDT' for Central Daylight.

+700
     `MDT' for Mountain Daylight.

+800
     `PDT' for Pacific Daylight.

+900
     `YDT' for Yukon Daylight.

+1000
     `HDT' for Hawaii Daylight.

-100
     `MEST' for Middle European Summer, `MESZ' for Middle European
     Summer, `SST' for Swedish Summer and `FST' for French Summer.

-700
     `WADT' for West Australian Daylight.

-1000
     `EADT' for Eastern Australian Daylight.

-1200
     `NZDT' for New Zealand Daylight.

Day of week item
================

   The explicit mention of a day of the week will forward the date
(only if necessary) to reach that day of the week in the future.

   Days of the week may be spelled out in full: `Sunday', `Monday',
`Tuesday', `Wednesday', `Thursday', `Friday' or `Saturday'.  Days may
be abbreviated to their first three letters, optionally followed by a
period.  The special abbreviations `Tues' for `Tuesday', `Wednes' for
`Wednesday' and `Thur' or `Thurs' for `Thursday' are also allowed.

   A number may precede a day of the week item to move forward
supplementary weeks.  It is best used in expression like `third
monday'.  In this context, `last DAY' or `next DAY' is also acceptable;
they move one week before or after the day that DAY by itself would
represent.

   A comma following a day of the week item is ignored.

Relative item in date strings
=============================

   "Relative items" adjust a date (or the current date if none) forward
or backward.  The effects of relative items accumulate.  Here are some
examples:

     1 year
     1 year ago
     3 years
     2 days

   The unit of time displacement may be selected by the string `year'
or `month' for moving by whole years or months.  These are fuzzy units,
as years and months are not all of equal duration.  More precise units
are `fortnight' which is worth 14 days, `week' worth 7 days, `day'
worth 24 hours, `hour' worth 60 minutes, `minute' or `min' worth 60
seconds, and `second' or `sec' worth one second.  An `s' suffix on
these units is accepted and ignored.

   The unit of time may be preceded by a multiplier, given as an
optionally signed number.  Unsigned numbers are taken as positively
signed.  No number at all implies 1 for a multiplier.  Following a
relative item by the string `ago' is equivalent to preceding the unit
by a multiplicator with value -1.

   The string `tomorrow' is worth one day in the future (equivalent to
`day'), the string `yesterday' is worth one day in the past (equivalent
to `day ago').

   The strings `now' or `today' are relative items corresponding to
zero-valued time displacement, these strings come from the fact a
zero-valued time displacement represents the current time when not
otherwise change by previous items.  They may be used to stress other
items, like in `12:00 today'.  The string `this' also has the meaning
of a zero-valued time displacement, but is preferred in date strings
like `this thursday'.

   When a relative item makes the resulting date to cross the boundary
between DST and non-DST (or vice-versa), the hour is adjusted according
to the local time.

Pure numbers in date strings
============================

   The precise intepretation of a pure decimal number is dependent of
the context in the date string.

   If the decimal number is of the form YYYYMMDD and no other calendar
date item (see Calendar date item.) appears before it in the date
string, then YYYY is read as the year, MM as the month number and DD as
the day of the month, for the specified calendar date.

   If the decimal number is of the form HHMM and no other time of day
item appears before it in the date string, then HH is read as the hour
of the day and MM as the minute of the hour, for the specified time of
the day.  MM can also be omitted.

   If both a calendar date and a time of day appear to the left of a
number in the date string, but no relative item, then the number
overrides the year.

Authors of `getdate'
====================

   `getdate' was originally implemented by Steven M. Bellovin
(`smb@research.att.com') while at the University of North Carolina at
Chapel Hill.  The code was later tweaked by a couple of people on
Usenet, then completely overhauled by Rich $alz (`rsalz@bbn.com') and
Jim Berets (`jberets@bbn.com') in August, 1990.  Various revisions for
the GNU system were made by David MacKenzie, Jim Meyering, and others.

   This chapter was originally produced by Franc,ois Pinard
(`pinard@iro.umontreal.ca') from the `getdate.y' source code, and then
edited by K. Berry (`kb@cs.umb.edu').

Directory listing
*****************

   This chapter describes the `ls' command and its variants `dir' and
`vdir', which list information about files.

`ls': List directory contents
=============================

   The `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 `ls' lists the contents of directories, not recursively, and
omitting files with names beginning with `.'.  For other non-option
arguments, by default `ls' lists just the file name.  If no non-option
arguments are specified, `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 `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 `ls''s operation.

   The `-g' option is accepted but ignored, for compatibility with
Unix.  Also see Common options.

Which files are listed
----------------------

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

`-a'
`--all'
     List all files in directories, including files that start with `.'.

`-A'
`--almost-all'
     List all files in directories except for `.' and `..'.

`-B'
`--ignore-backups'
     Do not list files that end with `~', unless they are given on the
     command line.

`-d'
`--directory'
     List just the names of directories, as with other types of files,
     rather than listing their contents.

`-I'
`--ignore'
     Do not list files whose names match the shell pattern (not regular
     expression) PATTERN unless they are given on the command line.  As
     in the shell, an initial `.' in a file name does not match a
     wildcard at the start of PATTERN.

`-L'
`--dereference'
     List the files linked to by symbolic links instead of listing the
     contents of the links.

`-R'
`--recursive'
     List the contents of all directories recursively.

What information is listed
--------------------------

   These options affect the information that `ls' displays.  By
default, only file names are shown.

`-D'
`--dired'
     With the long listing (`-l') format, print an additional line after
     the main output:

          //DIRED// BEG1 END1 BEG2 END2 ...

     The BEGN and ENDN are unsigned integers which 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 (`-R'), output a
     similar line after each subdirectory:
          //SUBDIRED// BEG1 END1 ...

`-G'
`--no-group'
     Inhibit display of group information in a long format directory
     listing.  (This is the default in some non-GNU versions of `ls',
     so we provide this option for compatibility.)

`-i'
`--inode'
     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.)

`-l'
`--format=long'
`--format=verbose'
     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
     `total BLOCKS', where BLOCKS is the total disk space used by all
     files in that directory.  By default, 1024-byte blocks are used;
     if the environment variable `POSIXLY_CORRECT' is set, 512-byte
     blocks are used (unless the `-k' option is given).  The BLOCKS
     computed counts each hard link separately; this is arguably a
     deficiency.

     The permissions listed are similar to symbolic mode specifications
     (see Symbolic Modes.).  But `ls' combines multiple bits into
     the third character of each set of permissions as follows:
    `s'
          If the setuid or setgid bit and the corresponding executable
          bit are both set.

    `S'
          If the setuid or setgid bit is set but the corresponding
          executable bit is not set.

    `t'
          If the sticky bit and the other-executable bit are both set.

    `T'
          If the sticky bit is set but the other-executable bit is not
          set.

    `x'
          If the executable bit is set and none of the above apply.

    `-'
          Otherwise.

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

`-s'
`--size'
     Print the size of each file in 1024-byte blocks to the left of the
     file name.  If the environment variable `POSIXLY_CORRECT' is set,
     512-byte blocks are used instead, unless the `-k' option is given
     (see General output formatting.).

     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 `ls'
     program.

Sorting the output
------------------

   These options change the order in which `ls' sorts the information
it outputs.  By default, sorting is done by character code (e.g., ASCII
order).

`-c'
`--time=ctime'
`--time=status'
     Sort according to the status change time (the `ctime' in the
     inode).  If the long listing format (`-l') is being used, print the
     status change time instead of the modification time.

`-f'
     Primarily, like `-U'--do not sort; list the files in whatever
     order they are stored in the directory.  But also enable `-a' (list
     all files) and disable `-l', `--color', and `-s' (if they were
     specified before the `-f').

`-r'
`--reverse'
     Reverse whatever the sorting method is--e.g., list files in reverse
     alphabetical order, youngest first, smallest first, or whatever.

`-S'
`--sort=size'
     Sort by file size, largest first.

`-t'
`--sort=time'
     Sort by modification time (the `mtime' in the inode), newest first.

`-u'
`--time=atime'
`--time=access'
`--time=use'
     Sort by access time (the `atime' in the inode).  If the long
     listing format is being used, print the last access time.

`-U'
`--sort=none'
     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
     `-f' does.)  This is especially useful when listing very large
     directories, since not doing any sorting can be noticeably faster.

`-X'
`--sort=extension'
     Sort directory contents alphabetically by file extension
     (characters after the last `.'); files with no extension are
     sorted first.

General output formatting
-------------------------

   These options affect the appearance of the overall output.

`-1'
`--format=single-column'
     List one file per line.  This is the default for `ls' when standard
     output is not a terminal.

`-C'
`--format=vertical'
     List files in columns, sorted vertically.  This is the default for
     `ls' if standard output is a terminal.  It is always the default
     for the `dir' and `d' programs.

`--color [=WHEN]'
     Specify whether to use color for distinguishing file types.  WHEN
     may be omitted, or one of:
        * none Do not use color at all.  This is the default.

        * auto Only use color if standard output is a terminal.

        * always Always use color.  Specifying `--color' and no WHEN is
     equivalent to `--color=always'.

`-F'
`--classify'
     Append a character to each file name indicating the file type.
     Also, for regular files that are executable, append `*'.  The file
     type indicators are `/' for directories, `@' for symbolic links,
     `|' for FIFOs, `=' for sockets, and nothing for regular files.

`--full-time'
     List times in full, rather than using the standard abbreviation
     heuristics.  The format is the same as `date''s default; it's not
     possible to change this, but you can extract out the date string
     with `cut' and then pass the result to `date -d'.  See `date' invocation (sh-utils).

     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.

`-k'
`--kilobytes'
     If file sizes are being listed, print them in kilobytes.  This
     overrides the environment variable `POSIXLY_CORRECT'.

`-m'
`--format=commas'
     List files horizontally, with as many as will fit on each line,
     separated by `, ' (a comma and a space).

`-n'
`--numeric-uid-gid'
     List the numeric UID and GID instead of the names.

`-p'
     Append a character to each file name indicating the file type.
     This is like `-F', except that executables are not marked.

`-x FORMAT'
`--format=across'
`--format=horizontal'
     List the files in columns, sorted horizontally.

`-T COLS'
`--tabsize=COLS'
     Assume that each tabstop is COLS columns wide.  The default is 8.
     `ls' uses tabs where possible in the output, for efficiency.  If
     COLS is zero, do not use tabs at all.

`-w'
`--width=COLS'
     Assume the screen is COLS columns wide.  The default is taken from
     the terminal settings if possible; otherwise the environment
     variable `COLUMNS' is used if it is set; otherwise the default is
     80.

Formatting the file names
-------------------------

   These options change how file names themselves are printed.

`-b'
`--escape'
     Quote nongraphic characters in file names using alphabetic and
     octal backslash sequences like those used in C.

`-N'
`--literal'
     Do not quote file names.

`-q'
`--hide-control-chars'
     Print question marks instead of nongraphic characters in file
     names.  This is the default.

`-Q'
`--quote-name'
     Enclose file names in double quotes and quote nongraphic
     characters as in C.

`dir': Briefly list directory contents
======================================

   `dir' (also installed as `d') is equivalent to `ls -C'; that is,
files are by default listed in columns, sorted vertically.

   See `ls'.

`vdir': Verbosely list directory contents
=========================================

   `vdir' (also installed as `v')is equivalent to `ls -l'; that is,
files are by default listed in long format.

`dircolors': Color setup for `ls'
=================================

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

     eval `dircolors [OPTION]... [FILE]`

   If FILE is specified, `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
`dircolors --print-data-base'.

   The output is a shell command to set the `LS_COLOR' environment
variable.  You can specify the shell syntax to use on the command line,
or `dircolors' will guess it from the value of the `SHELL' environment
variable.

   The program accepts the following options.  Also see Common options.

`-b'
`--sh'
`--bourne-shell'
     Output Bourne shell commands.  This is the default if the `SHELL'
     environment variable is set and does not end with `csh' or `tcsh'.

`-c'
`--csh'
`--c-shell'
     Output C shell commands.  This is the default if `SHELL' ends with
     `csh' or `tcsh'.

`-p'
`--print-data-base'
     Print the (compiled-in) default color configuration database.  This
     output is itself a valid configuration file, and is fairly
     descriptive of the possibilities.

Basic operations
****************

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