LSD: a non-halucenogenic directory listing program

OVERVIEW

LSD is a directory listing program, like the DOS DIR command. However,
LSD is modeled after the Unix ls command, and as such provides many
capabilities beyond those provided by the DIR command.

For example, LSD:

- allows the files listed to be sorted by name, extension, creation
time, or size in ascending or decending order.

- provides a variety of listing styles.

- allows subdirectories encountered to be recursed into, and their
contents listed.

- accepts several files specifications on a single command line.

- includes a 'more' facility to prevent long listings from scroll-
ing by before they can be read.

- includes an on-line help facility to eliminate constant reference
to the instruction manual.


LICENSE INFORMATION

LSD, version 1.6, is Copyright April 1990 by Semaphore Labs. This
copyright applies to both the executable program LSD.EXE, the documen-
tation file LSD.DOC, and the source files used to generate the LSD
program and its documentation.

This material may be freely distributed so long as no alterations are
made, and both the executable file and this documentation file are
included.

Comments, criticisms, requests for additional features, and general
correspondence is invited at the address below.

Semaphore Labs
152 Ibis Drive
Pasadena, Maryland, 21122

If the LSD program is found useful, a donation in any amount to
support continued development is welcomed. Anyone making a donation
of $25 or more will receive the complete source code for the LSD
program.










LSD V1.6, Copyright (c) April 1990, Semaphore Labs 1






LSD: a non-halucenogenic directory listing program


USAGE

The LSD program is invoked by entering LSD (or whatever you've named
the executable file), optionally followed by switches and file spec-
ifications. Any number of switches and file specifications can appear
in any order. If no switches are supplied, a brief alphabetically
sorted multi-column listing is produced. If no file specifications
are supplied, all regular (non-hidden, non-system) files in the
current directory are listed.

Example:

C> lsd
bar.c foo.c mar.c moo.c
bar.exe foo.exe mar.exe moo.exe
bar.obj foo.obj mar.obj moo.obj


File specifications follow normal DOS conventions. A full file
specification includes a drive letter, a colon, a series of directory
specifications separated by backward slant bars, a file name, a
period, and a file extension. The backward slant bars normally used
to separate directories under DOS can be replaced interchangably with
the forward slant bars used for this purpose under Unix. The char-
acters '?' and '*' can be used in file name and file extension fields
to represent any single character and any sequence of trailing char-
acters respectively. Any or all of these fields can be omitted.

If omitted, the drive and directory default to the current default
drive and directory, and the file name and extension default to '*.*',
which matches all files. Note that the file specifications '*', '.*',
and '*.*' are equivalent methods of specifying all files in a direc-
tory, and that '.exe' and '*.exe' are equivalent methods of specifying
all executable files in a directory. Files with a blank extension are
specified by including the period after the file name field in a file
specification.

Examples:

C> lsd .c
bar.c foo.c mar.c moo.c

C> lsd c:/foobar/.c
bar.c foo.c mar.c moo.c


Switches are used to specify options which alter the operation of the
LSD program. Switches begin with a hyphen or minus sign, followed by
one or more switch characters. For example, including the '-l' switch
toggles the long listing option on. This causes file size and at-
tribute information and file creation date and time information to be
displayed for each file.




LSD V1.6, Copyright (c) April 1990, Semaphore Labs 2






LSD: a non-halucenogenic directory listing program

Example:

C> lsd -l *.c
a----- 611 90-Feb-09 19:05:58 bar.c
a----- 6534 90-Feb-09 19:06:08 bar.exe
a----- 226 90-Feb-09 19:06:04 bar.obj
a----- 42 90-Feb-09 19:04:02 foo.c
a----- 6534 90-Feb-09 19:04:26 foo.exe
a----- 226 90-Feb-09 19:04:22 foo.obj
a----- 209 90-Feb-09 19:09:56 mar.c
a----- 6534 90-Feb-09 19:10:04 mar.exe
a----- 226 90-Feb-09 19:10:00 mar.obj
a----- 24 90-Feb-09 19:06:56 moo.c
a----- 6534 90-Feb-09 19:07:06 moo.exe
a----- 226 90-Feb-09 19:07:04 moo.obj


Several switch characters can be grouped together following a hyphen.
For example, the '-l' switch can be combined with the '-r' switch
which is used to reverse the normal sort order as shown below.

Example:

C> lsd -lr *.c
a----- 226 90-Feb-09 19:07:04 moo.obj
a----- 6534 90-Feb-09 19:07:06 moo.exe
a----- 24 90-Feb-09 19:06:56 moo.c
a----- 226 90-Feb-09 19:10:00 mar.obj
a----- 6534 90-Feb-09 19:10:04 mar.exe
a----- 209 90-Feb-09 19:09:56 mar.c
a----- 226 90-Feb-09 19:04:22 foo.obj
a----- 6534 90-Feb-09 19:04:26 foo.exe
a----- 42 90-Feb-09 19:04:02 foo.c
a----- 226 90-Feb-09 19:06:04 bar.obj
a----- 6534 90-Feb-09 19:06:08 bar.exe
a----- 611 90-Feb-09 19:05:58 bar.c


Note that which file specifications may be entered in either upper or
lower case with no difference in effect, the case used for switch
characters is significant. For example, the '-s' switch character
causes disk space information to be displayed, while the '-S' switch
causes files listed to be sorted by file size.

Internally, the command line is scanned from left to right, and the
option setting associated with a switch character is toggled as that
option character is encountered. One consequence of this is that the
option specified by a switch character is only in effect for file
specifications which follow. Another consequence is that an option
will be returned to its default state when its switch character is
encountered a second time.






LSD V1.6, Copyright (c) April 1990, Semaphore Labs 3






LSD: a non-halucenogenic directory listing program

Example:

C> lsd *.c -l *.c -l *.c

c:/foobar/*.c
bar.c foo.c mar.c moo.c

c:/foobar/*.c
a----- 611 90-Feb-09 19:05:58 bar.c
a----- 42 90-Feb-09 19:04:02 foo.c
a----- 209 90-Feb-09 19:09:56 mar.c
a----- 24 90-Feb-09 19:06:56 moo.c

c:/foobar/*.c
bar.c foo.c mar.c moo.c

Initially all option flags are set to off, and are toggled on by the
first occurance of the appropriate switch character. The only excep-
tion to this rule is the 'more' option. The more option flag deter-
mines whether the display will pause for operator input after every
screen full of information is displayed. This option is initially on
if the display is directed to a terminal, and is initially off if the
output has been redirected to a file or other device.

For example, the command

C> lsd -Rpq /*.c

will generate a list of all .c files in all directories on the current
disk. After each screenful of lines, the '---- More? ----' prompt
will appear, and output will pause waiting for a response from the
console. If the same command is given with output redirected to a
file, the more option flag will initially be turned off so that the
directory listing will be written to the file with no further operator
intervention.






















LSD V1.6, Copyright (c) April 1990, Semaphore Labs 4






LSD: a non-halucenogenic directory listing program

SWITCHES

Numerous switches are available to modify the operation of the lsd
program. The complete list of these switches appears below. Note
that case is significant in the interpretation of the switches, and
that in some cases more than one switch is available to select an
option.

1: lists files in a single column.

D: lists only directories.
R: recurses through subdirectories.
S: sorts files by their size.
U: shows space used, free, total, and other disk info.

a: lists all files, including ., .., hidden files, etc.
d: list only a directory entry, not the files it contains.
s: sorts files by their file extension.
h: displays this help information. Same as -?
l: long listing: includes file attributes, date and size.
m: toggles more feature off.
o: lists files in directory order (i.e., unsorted).
p: includes full path specification for each file.
q: quiet mode drops headers in multiple directory listings.
r: reverses the usual sort order.
s: lists file size information instead of listing files.
t: sorts files by their creation time.
u: lists a file count and file size grand total.
x: lists files sorted in rows instead of columns.


LONG LISTING FORMATS

The default listing format for the lsd program is called brief format.
In brief format, only the file name and file extension are shown. If a
file is a directory file, the directory name will be followed by a
slash. Two alternates to this format are long format listings and path
format listings.

The long format listing includes each file's attributes, size, and
creation date and time in addition to the file's name and extension.
The attribute field is six characters long, with one character posi-
tion for each of the six file attributes. From left to right these
are the archive flag, the directory flag, the label flag, the system
flag, the hidden flag, and the read-only flag. Following the at-
tribute field is the file's size given in bytes. This is followed by
the file's creation date and time. Lastly comes the file's name and
extension.

Examples of two long format file listings:

a-L--- 0 90-Feb-09 19:49:42 examples

---sh- 12288 90-Feb-09 19:46:46 ibmbio.com



LSD V1.6, Copyright (c) April 1990, Semaphore Labs 5






LSD: a non-halucenogenic directory listing program

The path format listing prefaces the file name field with the full
path specification for the file. The path format option may be used by
itself or in combination with the long format option.

Example of a path format file listing:

c:/tc/ex/hello.c


Example of a long format, path format file listing:

a----- 104 88-Aug-29 2:00:00 c:/tc/ex/hello.c


MORE FACILITY

The more facility of the lsd program causes the display to pause when
the screen has filled. This allows the user time to scan through the
information presented so far. When ready to continue, the user hits
the space bar, and the next screen of information is displayed.

In addition to using the space bar to get another screen full of
information, several other characters can be entered in response to
the more prompt. The one to remember is that entering an 'h' or a
question mark will bring up the more help display.

Example:

C> lsd -l

{ one screen full of directory listing appears here }

---- More? ---- { user hits '?' }
Enter ...
return to display one more line.
y or space to show another screen full.
n or q or x or ^C to exit.
g or c to turn more off and display continuously.
0, 1, ..., 9 to show another 1, 2, ..., 512 lines.
any other key to recall this help display.
---- More? ----


The help screen explains the responses more is expecting. Hitting the
space bar or the y (for Yes) key displays one more screen full of
directory information. Hitting n (for No), q (for Quit), x (for eXit),
or control-C aborts execution of lsd. Hitting g (for Go) or c (for
Continuous) turns more mode off, so the rest of the listing is dis-
played without pauses. Hitting a digit key displays two to that power
more lines before pausing. Hitting any other key displays one more
line before returning to the more prompt.






LSD V1.6, Copyright (c) April 1990, Semaphore Labs 6






LSD: a non-halucenogenic directory listing program

EXAMPLES

Find all executable files in the current directory. Note that 'lsd
.exe' is the same as 'lsd *.exe'.

C> lsd .exe

bar.exe foo.exe mar.exe moo.exe


List all files in the home directory of the b: drive. This listing
includes hidden files, system files, and the disk label file.

C> lsd -a b:/

a-L--- 0 90-Feb-09 19:49:42 examples
-d---- 0 90-Feb-09 19:47:32 foobar/
---sh- 12288 90-Feb-09 19:46:46 ibmbio.com
---sh- 28160 90-Feb-09 19:46:48 ibmdos.com
-d---- 0 90-Feb-09 19:47:42 misc/


List all files in the current subdirectory. This listing includes
directory entries for the current subdirectory (.) and for the parent
subdirectory (..), as well as any hidden or system files which may be
present.

C> lsd -a

./ bar.exe foo.exe mar.exe
../ bar.obj foo.obj mar.obj
bar.c foo.c mar.c


List all .c files on the default disk.

C> lsd -R /.c

c:/foobar/*.c
bar.c foo.c mar.c moo.c

c:/misc/*.c
args.c depends.c dx.c simsol.c


List the space used in each directory on the b: drive.

C> lsd -Rs b:

0 2 b:/*.*
27926 12 b:/foobar/*.*
73172 15 b:/misc/*.*
-------- --- ----
101098 29 3



LSD V1.6, Copyright (c) April 1990, Semaphore Labs 7






LSD: a non-halucenogenic directory listing program

Find all directories on the default disk. List them with their path
information and directory header information. Adding the '-q' quiet
option would eliminate the directory headings (c:/*.*, etc) and the
blank lines between directories sharing a common parent.

C> lsd -RDp /

c:/*.*
c:/emacs/
c:/tc/

c:/emacs/*.*
c:/emacs/obj/

c:/tc/*.*
c:/tc/bgi/
c:/tc/ex/
c:/tc/include/
c:/tc/lib/

c:/tc/include/*.*
c:/tc/include/sys/


Show disk label, organization, and space used information for disk
drives a: through d:

C> lsd -U a: b: c: d:

Drive a: is labeled "examples".
Org: 512 bytes per cluster in 1 sector of 512 bytes each.
Use: 1,103,360 (90.8%) free, 110,592 (9.2%) used, 1,213,952 total.

Drive b: is unlabeled.
Org: 1024 bytes per cluster in 2 sectors of 512 bytes each.
Use: 71,680 (19.7%) free, 290,816 (80.3%) used, 362,496 total.

Drive c: is labeled "hardsoftwar".
Org: 2048 bytes per cluster in 4 sectors of 512 bytes each.
Use: 1,533,952 (4.8%) free, 30,234,624 (95.2%) used, 31,768,576 total

Drive d: is labeled "vdisk v3.2".
Org: 512 bytes per cluster in 1 sector of 512 bytes each.
Use: 1,108,992 (77.3%) free, 325,632 (22.7%) used, 1,434,624 total.













LSD V1.6, Copyright (c) April 1990, Semaphore Labs 8






LSD: a non-halucenogenic directory listing program

COMING ATTRACTIONS

Additions planned (note that that says 'planned', not 'promised') for
the next release of the lsd program include:

- Add the '-X' exclude option to list all file except those match-
ing a given file specification(s).

- Add an option to merge several directories' files into a single
sort unit. This would allow the -S switch to list the largest
files on an entire disk, instead of in each directory.

- Find a way to determine how many lines are on the screen, and
pass this information to the more feature, rather than assuming
that all screens always display 25 lines.

- Add -i option to list license and ordering info.

- Read initial switch settings from the LSD environment variable.
This will provide some easy customization of the program's
operation.

- Find a way to sense when stdout has been redirected to the
printer. Set the more flag off under this condition.

































LSD V1.6, Copyright (c) April 1990, Semaphore Labs 9