Category : File Managers
Archive   : LIST.ZIP
Filename : L.DOC

L (list/locate)

Locates and lists to stdout, files and/or subdirectories of:
an entire disk,
any (sub)directory,
any subdirectory and all of its descendants.

Directories "." and ".." are never listed.

New filename matching characteristics: see "Rules for file/directory
names".

Handles the character å properly in file, directory and path names.


L.COM uses several types of parameters. If redundant or conflicting
parameters are present, the program terminates with the message:

L: invalid parameter

written to stderr. If L.COM is renamed, it will find its name
when executed.


Parameters may be entered in any order. Lower case is converted to upper.
Only spaces and tabs are recognized as separators, however the forward slash
'/' always begins a new parameter. Normal errors terminate the program
with a message similar to the above. Unexpected errors caught by the
operating system cause the message:

L: error status =

where is the error code returned by MS-DOS. L returns from all errors
with a return code of 255.


For the purpose of this documentation, the path to the directory searched
or to the root of the (sub)tree searched, which is not necessarily the
root directory, shall be called the root path.


Parameters:

The (sub)directory or root path of the (sub)tree to be searched, if
given in a parameter, is normally expected to be in a separate
parameter from the filespecs. The exception is one of the two
conditions covered in the section on reinterpretation of parameters.

Root path:

All components of the root path are optional. If the whole parameter
is omitted, each individual default is in effect. No blanks or tabs
may separate components. The components are:
a drivename, (the current drive if omitted)
a backslash, (the current path if omitted)
one or more subdirectory names separated by backslashes.
(none if omitted)
A root path parameter is recognized if it contains a colon or
a backslash and no forward slash. The parameters "." and ".."
are also recognized as root paths. Only one root path may be used.
*** NOTE ***
The final subdirectory name may be followed by a backslash. This
serves no purpose except when the parameter contains no colon and
no other backslash, in which case it is required in order that the
parameter may be recognized as a path. See also "Reinterpretation of
Parameters".

example:

L BIN\

lists files *.* in the BIN subdirectory of the current (sub)directory,
while:

L BIN

lists files BIN.* in the current (sub)directory.

File and/or directory names:

A parameter which is not "." or ".." and contains no '/', '\' or ':'
indicates the files and/or directories to be listed. If none are
present, the default of "*.*" is used. If it contains no '.',
then ".*" is appended to the parameter. If it begins with a '.',
then it is prefixed with a '*'. Multiple file/directory names may
be used.

Rules for file/directory names:

Some, but not all, useless or redundant filename constructs, are
rejected by L. Any parameter that implies a filename that may have
more than eight characters or a filetype that may have more than
three characters is an invalid parameter. Every character
except '*' or '?' must match a character in a directory entry for a
successful match. L has three "wild cards".

'*' matches zero or more characters, and may occur anywhere in a
filename or filetype.
example:

*SET*

can match

MYSETS
YOURSET
SET
SETALL

'?' matches one character unless there are no more characters to match,
in which case it is skipped.

'+' must match one character. If there are no more characters to match
then the match fails.

Two asterisks ("**") may not appear together in a parameter.

The number of characters may not exceed eight in the name or three in
the type. However, more than one '*' are all counted as one character.

example:

*A*B*C*D*E*F*G*.*X*Y*

is a valid parameter since one of the asterisks in the name and/or
one in the type may match another character.

example:

*A*B*C*D*E*F*G*H*.*X*Y*
and
*A*B*C*D*E*F*G*.XYZ*

are NOT valid parameters since they imply that there may be more than
eight characters in the name or more than three in the type.

Attributes:

"/D": search and list directories and files.
(may not be used with "/O" or "/F")
"/O": search and list directories only.
(may not be used with "/D", "/A" or "/B")
"/A": search and list any hidden or system files or volume name.
(may not be used with "/O")
default: search and list files only; excluding system and hidden files.

Range:

"/S": search all descendant paths beginning with root path.
default: search root path only.

Format:

"/H": omit all headings, totals and empty lines: anything not
useful when piped to a sorter.
(may not be used with "/B" or "/F")
default: for each (sub)directory searched that yields a nonempty
listing, write an empty line followed by the heading:

directory of

After all lists have been written, write an empty line.
If "/O" has not been selected, write:

files =

If "/D" or "/O" has been selected, write:

subdirectories =

"/2": place two names on each line.
"/4": place four names on each line.
"/5": place five names on each line.
"/6": place six names on each line.
"/8": place eight names on each line.
(these are mutually exclusive and may not be used with "/F")
default: place one name on each line with attributes, sizes, dates
and times.

"/2", "/6" and "/8" assume a 132 column screen.

With "/4", "/5", "/6" and "/8" only the names of files are listed.
Directory names, when listed, are preceeded by 'þ'.

"/.": if filetype is non-empty, it is separated from filename
by a period.
(may not be used with "/F")
default: filetype begins nine columns to the right of the beginning
of filename and separated by spaces.

"/F": files or directories, but not both, are listed with full drive
and pathnames, one on each line. The purpose is to produce a list
of files or directories that can be used as input for another
program or edited into a batch file. "/H" and "/." are implied.
When "/A" is used, volume names are not output. When "/O" is used,
the root path is listed as well as its subdirectories. It is always
the first line.
(may not be used with "/D", "/H", "/2", "/4", "/5", "/6", "/8",
"/." or "/B")

"/R": suppresses the "*** redef ***" output. See Reinterpretation of
Parameters.
(may not be used with "/F" or "/H")

Byte totals:

"/B": before the directory search, the boot sector is read. If a
valid BPB is recognized, the cluster size is determined. For
each FILE listed, the file size and the number of bytes allocated
(based on the cluster size) are added to the totals. At the end
of the output, the totals are listed.

bytes allocated =
bytes used =
waste =

If no valid BPB is recognized, the "/B" parameter is ignored.
(may not be used with "/O", "/H" or "/F")
default: no totals.

Reinterpretation of Parameters

There are two circumstances in which it may be advantageous to redefine
the meaning of a parameter. In either case the reinterpreted parameter
is used only if no listing was produced by the standard interpretation.
If a listing is produced by the reinterpreted parameters, then the
first line of the output is:

*** redef ***

unless the "/H" or "/R" parameter was used, in which case L.COM gives
no indication whether reinterpretation took place. Reinterpretation
is suppressed if the "/F" parameter is used. With these exceptions,
the first line of output is always empty if no reinterpretation has
taken place, and never empty if it has. If the output is piped to
another program that needs to tell the difference, it can use this.

If no root path and only one filespec is used, and nothing is found,
L will then treat the filespsc as part of the path and append "\*.*"
to it, if there is the possibility of finding something. In the above
example:

L BIN

if no files "BIN.*" were found in the current (sub)directory, then
L would attampt to find files "*.*" in the offspring directory "BIN"
of the current directory; just as if executing:

L BIN\

(If the subdirectory exists and the /D or /O parameters had been used,
a listing would already have been produced; therefore, reinterpretation
in this case is not attempted with either of these parameters.)

The other circumstance in which reinterpretation takes place is where
a recognizable pathname not terminated by a backslash is given, there
is no filespec, and /D, /O & /S are not used. If this results in a
"path not found" error; then before reporting the error, the name
following the last backslash is removed from the path and treated as
a separate filespec parameter. If no listing is produced, then it is
considered a "path not found" error.

example:

L C:\TURBO\V4\HEX

L would attempt to list the files "C:\TURBO\V4\HEX\*.*". If the
directory "C:\TURBO\V4\HEX" were nonexistent, L would then attempt
to list the files "C:\TURBO\V4\HEX.*".

No effective reinterpretation will take place if the parameters
have any of the following characteristics:
1: no pathname and no filename,
2: a pathname and at least one filename,
3: more than one filename,
4: a filename with an explicit wildcard,
5: the "/F" parameter.

Output:

If stdout is the int 0x29 device (normally CON is), then output
takes place one character at a time using this interrupt.

If stdout is another device, then output takes place by int 0x40
with each part of the output as it is ready.

If stdout is a file, then output is stored in a 4K buffer
and flushed when full and before exit.

DOS function 11 is executed before each search to check for
ctrl-S and ctrl-break or ctrl-C.

Wierd filenames:

L.COM accepts parameters enclosed in double quotes to accomodate
the search and listing of the one kind of anomalous filename that
can be produced without tampering with the directories. MS-DOS will
use filenames that have spaces and other characters mixed if the
first character is not a space.
example:

assume no file beginning with ZZ exists in your current directory.

type:

REM >ZZ

you now have an empty file named "ZZ".
now type:

RENAME ZZ ????ZZ.?ZZ

your file is now named "ZZ ZZ. ZZ".
now type:

L "ZZ ZZ. ZZ"
or
L "ZZ ZZ. ZZ"/.

L.COM produces a listing for only this file.
now type:

DEL ZZ*.*

to remove the file. (and any other files beginning with "ZZ")

No provision is made for including double quotes in quoted strings
since no valid parameter for L.COM has one. Under some circumstances,
a parameter such as 'AB"CDEF' will produce a "path not found" error,
otherwise this error is undetected and has no effect.