% $Id: ls.tex 1.9 1998/02/07 19:38:02 brian Exp $

\chapter{ls---List Directory}

The \textbf{ls} (list directory) command is a loose adaptation of the
GNU \textbf{ls} command, and is a better DIR command than DIR\@. It
supports multiple file specifications on the command line. It matches
filenames using the Bourne shell pattern matching rules and not
the DOS or OS/2 ``wildcard'' rules.

The \textbf{ls} command lists the names of ordinary files, hidden
files, system files, and directories as you wish. It also lists each
name with any drive and path information that was in the original file
specification. It can recursively descend subdirectories looking for
matching files and or directories if you wish.

In the ``long'' format, the \textbf{ls} command displays each file's
attributes as well as its size, date, and time.

By default, \textbf{ls} sorts the output by filename, and displays the
names in multi-column format if standard output is a character device.
When writing multi-column output, \textbf{ls} sorts the files by
column, newspaper-style, just as the Unix and GNU \textbf{ls} commands
do (and \textit{unlike} the simplistic sort by row performed by the
DOS, Win32, and OS/2 DIR commands).

\section{Usage}

\verb+ls [ -flags ] [ -- ] [ fspec ... ]+
\medskip

The flags are optional. If specified, they must consist of a dash
followed by one or more contiguous flag characters. The flags control
what names are listed and in what format they are listed.

If no flags are specified, then \texttt{-fdn} is assumed: list all
matching ordinary files and directories, and sort them by name.

Zero or more file specifications may be entered. Each file
specification consists of an optional drive, optional path, and
filename. Each filename may contain Bourne shell pattern-matching
characters (better than DOS's, Win32's, and OS/2's wildcard
characters, \textit{and} supported on all of these platforms). The
\textbf{ls} command lists all files in the specified directory whose
names match the filename, according to the flags.

If a file specification is that of a directory, then \textbf{ls}
appends \texttt{/*} to it and matches everything in that directory. If
there are no file specifications, then \textbf{ls} assumes \texttt{*}:
match everything in the current directory.

\section{Flags}

The following (case-sensitive) flag characters are supported:

\begin{itemize}

    \item[\texttt{-f}] Lists all ordinary (including read-only) files
        that match the file specification(s). If the \texttt{-f} flag
        is specified, then directories are not listed unless the
        \texttt{-d} flag is also specified.

    \item[\texttt{-s}]  Lists all system files.

    \item[\texttt{-h}]  Lists all hidden files.

    \item[\texttt{-d}] Lists all subdirectories that match the file
        specification(s). If the \texttt{-d} flag is specified, then
        ordinary files are not listed unless the \texttt{-f} flag is
        also specified.

    \item[\texttt{-a}] Lists all ordinary files, system files, hidden
        files, directories, the \texttt{.}\ and \texttt{..}\
        directories, and, for DOS only, volume IDs.

    \item[\texttt{-l}] Lists each matching file or directory name in
        ``long'' format. For each name, it also displays the
        attributes, size, time stamp, and date stamp. If \texttt{-l}
        is not specified, the \textbf{ls} command lists only the
        names.

    \item[\texttt{-c}] Uses time of creation instead of time of last
        modification. If used with \texttt{-l}, it shows this time. If
        used with \texttt{-t}, it sorts using this time. (Win32 and
        OS/2 versions only.)

    \item[\texttt{-u}] Uses time of last access instead of time of last
        modification. If used with \texttt{-l}, it shows this time. If
        used with \texttt{-t}, it sorts using this time (NTFS and HPFS
        only).

    \item[\texttt{-x}] The same as \texttt{-u}, for compatibility with
        previous versions of \textbf{ls}.

    \item[\texttt{-R}]  Recursively descends subdirectories.

    \item[\texttt{-p}]  Puts a path separator after each name that is a directory.

    \item[\texttt{-C}] Forces multicolumn output. The \textbf{ls}
        command tries to list more than one filename per line,
        depending upon the length of the longest name and the width of
        the display screen. Filenames are sorted vertically.

    \item[\texttt{-m}] The same as \texttt{-C}, for compatibility with
    previous versions of \textbf{ls}.

    \item[\texttt{-1}]  Forces single (one) column output.

    \item[\texttt{-n}]  Sorts the output by name (default), in alphabetic order.

    \item[\texttt{-t}]  Sorts the output by date and time, from newest to oldest.

    \item[\texttt{-z}] Sorts the output by filesize, from smallest to
        largest.

    \item[\texttt{-r}]  Reverses the order of the sort.

    \item[\texttt{-o}]  Don't sort: display filenames in the order in which they occur
        in each directory.

    \item[\texttt{-g}]  Lists each set of matching files as a group in the order that
        their fspecs are specified. For example, if \texttt{*.h *.c} are
        entered, then the \texttt{-g} flag causes all \textbf{.h} files to be displayed
        first and all \textbf{.c} files to be displayed next.

        The \texttt{-g} flag causes the program to make a separate pass through a
        directory for each fspec, making '\textbf{ls}' run slower. The default
        behavior is to display all matching files as they are found,
        making only one pass through each directory.

    \item[\texttt{-L}]  Shows filenames in lowercase.

    \item[\texttt{-U}]  Shows filenames in uppercase.

\end{itemize}

You can mix and match the \texttt{f}, \texttt{s}, \texttt{h}, and
\texttt{d} flags to include as many different file types as you wish.
If you specify at least one of the \texttt{s}, \texttt{h}, or
\texttt{d} flags, then you must explicitly specify \texttt{-f} to
include ordinary files in the listing. If you don't specify one of the
\texttt{f}, \texttt{s}, \texttt{h}, \texttt{d}, or \texttt{a} flags,
then the default is
\texttt{-fd}: list only ordinary files and directories.

You can specify the \texttt{-l} (letter el) flag to list file and/or
directory names in ``long'' format. In this format, each name appears
along with its mode, size, date, and time. The mode (attribute)
consists of a set of characters that are interpreted as follows:

\begin{itemize}

        \item The first character is:
        \begin{itemize}
           \item[{}]
           \begin{tabular}{l l}
           \texttt{d} &  The name is a directory. \\
         % \texttt{v} &  The file represents a volume id (DOS only). \\
           \texttt{-} &  The name is a file.
           \end{tabular}
        \end{itemize}

        \item The second character is:
        \begin{itemize}
           \item[{}]
           \begin{tabular}{l l}
           \texttt{r} &  The file is readable (always!). \\
           \texttt{-} &  The file is not readable (never!).
           \end{tabular}
        \end{itemize}

        \item The third character is:
        \begin{itemize}
           \item[{}]
           \begin{tabular}{l l}
           \texttt{w} &  The file is writable. \\
           \texttt{-} &  The file is read-only.
           \end{tabular}
        \end{itemize}

        \item The fourth character is:
        \begin{itemize}
           \item[{}]
           \begin{tabular}{l l}
           \texttt{s} &  The file is a system file. \\
           \texttt{-} &  The file is not a system file.
           \end{tabular}
        \end{itemize}

        \item The fifth character is:
        \begin{itemize}
           \item[{}]
           \begin{tabular}{l l}
           \texttt{h} &  The file is a hidden file. \\
           \texttt{-} &  The file is not a hidden file.
           \end{tabular}
        \end{itemize}

        \item The sixth character is:
        \begin{itemize}
           \item[{}]
           \begin{tabular}{l l}
           \texttt{a} &  The file has been changed (its archive bit is set). \\
           \texttt{-} &  The file's archive bit is not set.
           \end{tabular}
        \end{itemize}

\end{itemize}

\section{Notes}

An ordinary file is a directory entry whose directory, system
hidden, and volid attribute (mode) bits are all zero.

Filenames are listed on standard output. Filespecs that don't match
any files are listed on standard error.

A file specification consists of an optional drive, optional path
information, and a filename. The filename may consist of Bourne shell
pattern-matching characters. DOS's filename pattern matching is
simplistic, Win32's and OS/2's is a lot better, but Bourne shell
pattern matching is better still. Also, all versions (DOS, Win32, and
OS2) of the commands in this package support the same enhanced level
of pattern-matching.

A dot within a filename is treated as just another character and not
assumed to be the beginning of a file extension. Indeed, the \textbf{ls} command
has no concept of a file extension. This is compatible with the use of
dots within Win32, NTFS, HPFS, and AIX filenames.

Flag characters are case sensitive. Name comparisons are
case-insensitive, as specified by DOS, Win32, and OS/2.

If the \texttt{-l} (long format) flag is listed, each file's
modification time and date are displayed. Specify the \texttt{-c} flag
along with \texttt{-l} to display each file's time of creation. Or,
specify the \texttt{-u} flag along with \texttt{-l} to display each
file's time of last access. Note that the \texttt{c} and \texttt{u}
flags don't yield valid times for a file system (such as DOS or OS/2
FAT) that don't maintain them. Also note that the DOS version simply
shows the time of last modification for the \texttt{-lu} and
\texttt{-lc} flags.

You may specify more than one set of flags. For example, you may enter
the commands \texttt{ls -n -l *.c *.h} and \texttt{ls -nl *.c *.h}
both list all \textbf{.c} and \textbf{.h} files in long format, sorted
by name.

The order in which you specify certain flags is important. For
example, if you specify \texttt{-l}, \texttt{-C}, and/or \texttt{-1},
the last one entered takes precedence. Likewise, if you specify
\texttt{-o}, \texttt{-n}, \texttt{-z}, and/or \texttt{-t}, the last
one entered overrides the others.

If the \textbf{ls} command is displaying filenames in multicolumn
format and/or sorting the names, then \textbf{ls} first stores all of
the filenames in memory, sorts them (\texttt{n}, \texttt{t}, or
\texttt{z} flag), and determines how many columns to display. The DOS
version of the \textbf{ls} command may run out of memory for large
file listings. If it does, you should re-run \textbf{ls} with the
\texttt{-1o} (number 1 and letter o) flags: force single-column output
and don't sort.

The DOS version of \textbf{ls} defaults to showing all filenames in
lowercase since this is more readable (especially on smaller
displays). The OS/2 version shows HPFS, NFS, and TVFS filenames as-is
and shows all other filenames (including those on FAT filesystems) in
lowercase. The Win32 version shows all filenames as-is. If you want
uppercase filenames, then specify the
\texttt{-U flag}. On OS/2 and Win32 platforms, the \texttt{-L} flag
will force all names to be shown in lowercase.

The Watcom-built versions (Win32, OS/2, and DOS) do not list the volume
label.

Enter \texttt{ls -?}  to get help.

\section{Examples}

\begin{enumerate}

\item
\texttt{ls *}      \\
\texttt{ls}        \\
\texttt{ls -fd *}

                 These commands all mean the same thing: List all
                 ordinary files and subdirectories within the current
                 directory. They match the same files that the DOS
                 command \texttt{DIR *.*} matches.

\item
\texttt{ls *.*}

                 This command lists all ordinary files in the current
                 directory that have an extension (that is, that have a
                 dot in their file name). This is not the same as the
                 \texttt{ls *} command nor is it the same as the \texttt{DIR *.*}
                 command, since it won't list any files or directories
                 whose name contains no dot.

\item
\texttt{ls -Cn}

                 List all files in the current directory in multi-column
                 format, sorted by name. This is the default behaviour
                 for the \textbf{ls} command when stdout is the display (and when
                 \textbf{ls} is entered with no flags or arguments).

\item
\texttt{ls *.c}

                 List all files in the current directory that end in the \textbf{.c}
                 suffix (or have the \textbf{.c} extension, in DOS's words).

\item
\texttt{ls *.c *.h} \\
\texttt{ls *.[ch]}

                 List all files in the current directory that end in
                 either \textbf{.c} or \textbf{.h}. These commands
                 show the same results. In the first command, notice
                 that you can enter more than one file specification.
                 In the second command, notice that the one Bourne
                 shell pattern can replace the two simplistic
                 DOS-sytle patterns.

\item
\verb+ls -Rd c:/+  \\
\verb+ls -Rd c:\+

                 List all directories and subdirectories on drive \texttt{C},
                 starting at the root directory. This produces a tree
                 listing of drive \texttt{C}.

                 Both \verb+\+ (backslash) and \texttt{/} (forward
                 slash) characters are interpreted as path separators.
                 When showing the matching directory entries,
                 \textbf{ls} will use the last path separator (if any)
                 that you entered on the command line.

                 If you didn't enter a path separator on the command
                 line, then \textbf{ls} uses a default path separator
                 of \verb+\+ if the \texttt{USEP} environment variable
                 is set to \verb+\+ and a default path separator of
                 \verb+/+ otherwise.

\item
\texttt{ls -a a:}

                 List all files and subdirectories in the current
                 directory of the \texttt{A} drive.

\item
\texttt{ls -lsh *}

                 This command lists only hidden and system files in the
                 current directory, along with their mode (attributes),
                 sizes, and time and date stamps.

\item
\texttt{ls -d *}

                 This command lists all subdirectories within the
                 current directory. The DOS \texttt{DIR *.} command sort of
                 does the same thing, provided that directory names have
                 no extension and file names always have an extension.

\item
\texttt{ls -l}

                 List each file in the current directory, along with its
                 mode, size, and time and date of last modification.

\item
\texttt{ls -lc}

                 Like \texttt{-l}, except display each file's time and date of
                 creation (Win32 and OS/2 versions only).

\item
\texttt{ls -lu}

                 Like -l, except display each file's time and date of
                 last access (NTFS and HPFS only).

\item
\texttt{ls -R c:/[a-m]*.exe}

                 List all \textbf{.exe} files on drive \texttt{C} that begin with the
                 letters A through M, inclusive.

\item
\texttt{ls -R c:/my.bat}

                 List all occurances of the \textbf{my.bat} file on drive \texttt{C}.
                 This command performs a ``whereis'' type of function.

\item
\texttt{ls -R *.c}

                 List all \textbf{.c} files in the current directory and,
                 recursively, in any subdirectories within the current
                 directory.

\item
\texttt{ls -lRdn /}

                 List all directories on the current drive in ``long''
                 format, sorted by directory name.

\item
\texttt{ls -lt}

                 List all files in the current directory in ``long''
                 format, sorted by date and time of modification.

\item
\texttt{ls -lut}

                 List all files in the current directory in ``long'' format,
                 sorted by date and time of last access (NTFS and
                 HPFS only).

\item
\texttt{ls -luo}

                 List all files in the current directory in ``long''
                 format, in the order in which they occur in the
                 directory (unsorted). Display the time of last access
                 for each one.

\item
\texttt{ls -lRn}     \\
\texttt{ls -l -Rn}   \\
\texttt{ls -l -R -n}

                 You may specify flags in one or more groups. For
                 example, these commands all produce identical results.

\item
\texttt{ls -lC1}

                 The same command as \texttt{ls -1}. The \texttt{C} flag
                 disables the \texttt{l} flag, and the \texttt{1} flag in turn
                 disables the \texttt{C} flag.

\end{enumerate}
