ls User's Manual
[1mls - Directory Listing Utility for the CLI Environment[0m
V1.1 12-Sep-87
Copyright (c) 1987 J. Brack
All Rights Reserved
This software and/or documentation is released for public
distribution for personal, non-commercial use only. Limited rights
to use, modify and redistribute are hereby granted for non-commercial
purposes, provided that all copyright notices remain intact and all
changes are clearly documented. The author makes no warranty of any
kind with respect to this product and explicitly disclaims any
implied warranties of merchantability or fitness for any particular
purpose. In no event will the author be liable for consequential
damages even if the author has been advised of the possibility of
such damages.
You may freely copy and redistribute this product. It may be uploaded
to any information service except those that attempt to claim
copyright on individual uploads.
[1m Purpose
[0m The AmigaDOS "Dir" utility provides a neat, sorted listing of
filenames within a directory. When the "opt a" qualifier is used,
"Dir" will descend through any sub-directories it finds. The
AmigaDOS "List" utility provides an unsorted yet more informative
listing of files, their sizes, their protection and their creation
dates. "List" also provides pattern matching on file names but will
not descend into sub-directories. I wanted a utility that combined
the best features of both "Dir" and "List", so I wrote "ls".
[1m Usage
[0m Place "ls" in your "c:" directory, and use it as follows:
ls [switches] [name]
Where [switches] may be:
-a Descend through "all" sub-directories
-d Show sub-directories along with files
-n List only the "new" files created today
-p Provide output in "pipe" format
-s List only the files that match a pattern
-v Display "ls" version number information
? Display small "usage" help message
[NULL] Default to list all files in default directory
Where [name] may be:
1. [NULL] - default to current directory
2. Any valid directory path
Page 1
ls User's Manual
3. Any valid device name
4. Any valid filename
Examples:
ls
List all files in the default directory. Sub-directories
will not be included in the list of files.
ls -d
List all files in the default directory and list
sub-directories. Files within sub-directories are not
listed.
ls -n -p
List all files in the default directory that were created
today in "pipe" format (pipe format is explained later).
ls -a df1:
List all files in all directories on device "df1:".
ls -a -n Textfiles
List all files created today in directory "Textfiles" and in
sub-directories nested within "Textfiles".
ls foo
List all files in directory "foo", or if "foo" is not a
directory, list information about the file "foo".
[1m Pattern Matching
[0m The "-s" switch lets you search for files using the famous "*" (match
any number of characters) and "?" (match any single character)
wildcards. Alphabetic matching is case-insensitive. For example:
ls -s*.doc
List all files in current directory whose names end with
".doc"
ls -se* Basic
List all files in the "Basic" directory whose names start
with "e".
ls -s??? -a df0:
List all files on device "df0:" that are 3 characters long.
ls -sncd.? -n programs/c
List all files created today in directory "programs/c" that
are 5 characters long beginning with "ncd." (e.g.: ncd.c and
ncd.o might match this string).
[1m Output Format
[0m "ls" lists files within directories in alphanumeric sorted order. If
Page 2
ls User's Manual
sub-directories are found within the specified directory and the "-d"
switch has been used, the directory names are indented in
alphanumeric order using a contrasting text color following the
files. If the "-a" switch has been used, the contents of the current
directory is printed followed by the contents of each sub-directory
with the directories appearing in alphanumeric sorted order. Typical
listings may appear as follows:
1> ls :Textfiles
[32mDirectory: :Textfiles[31m
frog.txt 6908/15 Today
serpent.doc 13498/28 Thursday
toad.txt 6330/13 27-Jun-1987
26736 bytes, 56 blocks in 3 files
1> ls -d :Textfiles
[32mDirectory: :Textfiles[31m
frog.txt 6908/15 Today
serpent.doc 13498/28 Thursday
toad.txt 6330/13 27-Jun-1987
26736 bytes, 56 blocks in 3 files
[32mSub-directory: gfile
Sub-directory: iff[31m
1> ls -a :Textfiles
[32mDirectory: :Textfiles[31m
frog.txt 6908/15 Today
serpent.doc 13498/28 Thursday
toad.txt 6330/13 27-Jun-1987
26736 bytes, 56 blocks in 3 files
[32mDirectory: :Textfiles/gfile[31m
gfile.doc 15293/32 22-Jun-1987
gfile.txt 196/1 Thursday
15489 bytes, 33 blocks in 2 files
[32mDirectory: :Textfiles/iff[31m
iff.doc 3201/7 10-Jul-1987
iff.help 6801/14 11-Feb-1987
10002 bytes, 21 blocks in 2 files
In the first example the "-d" switch was not specified, so the
presence of sub-directories "gfile" and "iff" was not listed. In the
second example the "-d" switch was specified causing sub-directories
"gfile" and "iff" to be listed in contrasting text color. In the
third example the "-a" switch causes "ls" to descend to the
sub-directories and list their contents.
[1m Pipe Output
[0m The output of "ls" can be redirected to a file which can be read by
another application program. This other program may take advantage
Page 3
ls User's Manual
of the pattern matching, directory descent and date selection
features of "ls". In a well known operating system whose name starts
with "U", this is known as "pipe" communications. In support of
piping, "ls" provides the "-p" switch. As an example, consider the
pipe output format of the directory and file structure used above:
1> ls -a -p :Textfiles
:Textfiles/frog.txt
:Textfiles/serpent.doc
:Textfiles/toad.txt
:Textfiles/gfile/gfile.doc
:Textfiles/gfile/gfile.txt
:Textfiles/iff/iff.doc
:textfiles/iff/iff.help
Note that all the "frills" are stripped from the pipe output format.
This format is not pretty for human beings, but it is nice for
program input. When "-p" is specified, the "-d" switch is turned off
so that you never need to worry about directory names appearing in
pipe output. If you can't think of a program that could take
advantage of this feature, stay tuned to your download area, I have
many things "in the pipe".
[1m Output Redirection and Aborts
[0m Like all good C programs, the output of "ls" may be redirected to a
file or the printer:
1> ls >a.tmp -p (sends pipe listing to disk file named "a.tmp")
1> ls >prt: -a (sends listing of all directories to printer)
To abort a lengthy listing, type "control-C".
Page 4
[1m
ls User's Manual
In Closing
[0m The "-a" and "-d" switches are, in fact, contradictory but not
illegal in combination. If both switches are specified, "-a" is
assumed.
The "-n" switch does not list new directories. The search applies
only to new files within some directory.
The choice of switch names for options "a" and "s" may seem
unimaginative, but I chose them to be compatible with the AmigaDOS
"Dir opt a" and "List -s" standard. It may also be argued that the
name "ls" is trite since there are several hundred previously
existing programs of the same name. Well "ls" is fewer keystrokes
than "pumpkinseed" and a standard name for this function in the
operating system whose name ends in "X". So there!
"ls" buffers file names and directories in allocated memory. If your
RAM is close to full, "ls" may abort with a "not enough memory" error
when large directories are listed.
If the brightness control on your monitor is set too low, "ls" may
not appear to work, in fact it may appear that your machine is
broken. Be sure you can easily read your screen for best results.
Why doesn't "ls" show file protection status? Call it developer's
fiat. I never play with file protection, so I don't show it. If
"ls" proves to be popular and the community sees a need for the
inclusion of file protection status, I will add it.
I have been using "ls" for several weeks without incident, and I
believe that it is bug-free. If you have any bug reports,
suggestions, comments or money to send, I can be contacted on GEnie
(mail address: J.Brack) or by snail at:
Ohio Imaging Inc.
23060 Miles Road
Bedford Heights, Ohio 44128-5443
"ls" is a product crafted by J. Brack, purveyor of fine software
tools for over 1.0e-1 of a century.
"AmigaDOS" is a trademark of Commodore-Amiga Inc.
"ls" is written in MANX Aztec C V3.4a. Thanx to Manx for a wonderful
product.
Page 5
