Ls User's Manual Directory Listing Utility for the CLI Environment V1.0 15-Aug-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. Purpose: 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". Usage: 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 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". Pattern Matching: 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). Output Format: "ls" lists files within directories in alphanumeric sorted order. If 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 Directory: :Textfiles 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 Directory: :Textfiles frog.txt 6908/15 Today serpent.doc 13498/28 Thursday toad.txt 6330/13 27-Jun-1987 26736 bytes, 56 blocks in 3 files Sub-directory: gfile Sub-directory: iff 1> ls -a :Textfiles Directory: :Textfiles frog.txt 6908/15 Today serpent.doc 13498/28 Thursday toad.txt 6330/13 27-Jun-1987 26736 bytes, 56 blocks in 3 files Directory: :Textfiles/gfile gfile.doc 15293/32 22-Jun-1987 gfile.txt 196/1 Thursday 15489 bytes, 33 blocks in 2 files Directory: :Textfiles/iff 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. Pipe Output: The output of "ls" can be redirected to a file which can be read by another application program. This other program may take advantage 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". Output Redirection and Aborts: 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". In Closing: 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: JBrack) 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.