Black Box 4/BlackBox.cdr/fileutil/rh_ls.arj/LS.DOC

Text File | 1990-09-19 | 9.0 KB | 211 lines

ls - a Unix-like directory listing program for MS-DOS


Syntax: ls [-aclmrstuR] [(path)name ... ]

    Options may appear in any order, grouped or separated; if separate,
    each must be preceded by a dash.  The name(s) may refer to files or
    directories.  If no name is given the current directory is listed.

Options:

    (none)  Show filenames according to the default settings
      -a    Reverse the "list all files" option default
      -c    Reverse the "one-column listing" option default
      -h    Print the help message and the default settings
      -l    Reverse the "long listing" option default
      -m    Reverse the 'pause for more" option default
      -r    Reverse the default sort direction
      -R    Recursively list sub-directories
      -s    Print sizes
      -s1   Print sizes for single-sided diskette
      -s2   Print sizes for double-sided diskette
      -t    Reverse the "time sort" option default
      -u    Reverse the "include disk usage" option default

Description:

The basic action is to list the filenames in the current directory, sorted
alphabetically into 5 columns.  If the (path)name of a directory/filename
pattern is specified, all files which match the pattern in the specified
directory are listed.  Wildcard characters ("*", "?") are acceptable in
the filename part of a directory/filename pattern.   Subdirectories are
identified by a trailing directory separator character in the basic list
format.

The basic action may be modified or replaced by alternative actions by
specifying options on the command line or by changing the default settings
options using MS-DOS environment variables.  These options are described
below:


    Option: -a    Variable for default setting: LSALL

System files, "hidden" files and the directory synonyms "." and ".." are
normally not included in the listing, but this option will bring them out
of the woodwork.  "Volume Labels" are always ignored.  If they have any
logic or value it has been carefully hidden by Microsoft.


    Option: -c    Variable for default setting: LSCOLM

This option forces output into a single column, so "ls -c" will give a
sorted list of filenames (only) in a single column, and "ls -lc" will
provide a "long" listing in one column instead of two.  These formats can
be useful if you want to use the file names or information for further
operations (e.g. as arguments in ".bat" files).  This format is the 4.2bsd
Unix default when sending the listing to any device other than the display;
here you must explicitly ask for single column output to get it.


    Option: -h    Default setting is always: OFF

The -h option causes ls to output a summary of its options and a list of
the current default settings.  After this, it terminates with no further
action.`


    Option: -l    Variable for default setting: LSLONG

This option yields a two-column "long" listing, sorted vertically by column,
showing nearly everything known about the files (i.e. all the news that fits).
The file attributes are shown symbolically by single characters: "d" for
directories or "s" for system files, "h" for hidden files, and "w" for writable
(not read-only) files.  The lack of one of these attributes is shown by a dash.
The actual length of the file, in bytes, is given unless the -u option is
included (see below).  The month and time of the last modification are shown if
the file is less than 12 months old, otherwise month and year are printed.

Note that the file sizes displayed in the "long" listing will always be smaller
than the actual disk space used, because MS-DOS never writes a record smaller
than the "cluster" size -- which is 1024 bytes on a 9-sector floppy and 4096
bytes on a hard disk with only a DOS partition present.


    Option: -m    Variable for default setting: LSMORE

This option causes the listing to be paused every 22 lines and print the
message "--MORE--" if the listing is being output to the console.  You may
respond with "C" or "c" to continue with another 22 lines, "Q" or "q" to
terminate the listing immediately, or with a carriage return to receive one
more line of listing followed by another pause.


    Option: -r    Variable for default setting: LSRSORT

This option causes the order of the listing to be reversed, i.e., from
z to a for alphabetic sorts and and from earliest to latest for time sorts
(refer to the -t option).


    Option: -R    Default setting is always: OFF

The -R option will include (recursively) the contents of any subdirectories
encounterd, and their subdirectories, ad finitum.  This can be a lengthy
listing on a hard disk; if started in the root directory with the -a option
it lists the whole shebang.


    Option: -s    Default setting is always: OFF

This option omits filenames (unless they are specified on the command line)
and lists sizes only.  This effectively shuts off the -l, -t and -r options,
and turns -u on, yielding a nifty summary of disk usage by directory, along
with a total at the end and the space remaining on the drive.  Include -a if
you want hidden and system files to show up.

As a special case, the -s option recognizes the numerals "1" and "2" (they
must immediately follow the "s" option) and will use disk block sizes
appropriate to single-sided diskettes (-s1) or double-sided diskettes (-s2)
in the calculatation of actual disk usage.  This is useful if you want to
know if a given set of files is going to fit on a diskette that uses block
sizes different from those on the source disk.  For example, MS-DOS is far
more profligate with disk space on a hard disk than on a floppy, and disk
use appears to "shrink" onto a floppy backup.  These options can tell you
how much shrinkage to expect.


    Option: -t    Variable for default setting: LSTSORT

The listed filenames will be sorted according to their last modification time
if this option is set ON, normally latest first.


    Option: -u    Variable for default setting: LSDU

This option tells you how much disk space is actually used.  If only one
filename or directory is listed, its total disk use is shown, followed by
its identifying (path)name.  If the -l option is included with -u, the size
shown for each file is the amount of disk space used -- almost always larger
than the file size. More than one name on the command line will get you
successive listings, with disk use subtotals preceding the identifying
(path)name, and followed by the total disk space used by the files listed.
All this is followed by the space remaining on the drive; if more than one
drive is involved, it is the space remaining on the last one on the command
line.


    Option: none    Variable for default setting: LSID

This option tells ls that you want it to always print the directory name
with the listing.  Note that this option cannot be modified from the command
line.


    Option: none    Variable for default setting: LSQS

This option allows you to set the directory file pathname separator.  ls
assumes the character "\" is used for this purpose.  If you desire to
change this you may set the LSQS environemnt variable to the desired
character.  Actually, your only allowable alternative is the character "/",
the characters "\" and "/" are the only directory file pathname separators
supported by MS-DOS.


Installation:

To install and use, simply copy the file ls.com into you binary files
directory (to be accessed via you "path" setting) or in the directory
(or directories) in which you intend to use this command.  If you
wish to change default settings, simply execute a set command for
each setting you wish to change (excellent use for an autoexec.bat
file).

If you want to mess with the code, the following information is useful:
compiller used was Microsoft C 5.1
cl ls.c

Using "ls":

The program has to be loaded into memory before it can run, then it must
consult the disk directory to find things.  This is a bit slow on a floppy
but is gratifyingly fast if the program is located on a hard disk or in
a ram disk, if there are less than a screenful of filenames to be shown.
It starts a bit slower if disk usage is requested, and it takes a second
or so to find and sort more than a hundred filenames at one whack.

Since the program has several options, you might want to encapsulate useful
combinations as ".bat" files, and give each a different name.  For example,
I have a file called "ll.bat" that contains

    ls -l %1 %2 %3 %4 %5 %6 %7 %8 %9

so that "ll" means "long listing."  Other options can be included on the "ll"
command line and they will work properly.  I have another called "du.bat" that
contains

    ls -asR %1 %2 %3 %5 %6 %7 %8 %9

and summarizes disk use in a compact format.


Bugs/Deficiencies:

The options are far from being mutually orthogonal; in particular, the
command "ls -u filename", for a single file that is not a directory, gives
a dumb-looking printout.

If you find yourself using DIR after you have used "ls" then I have
failed.