List(V1.3, 2.x, 3.x in C:) NAME List - List contents of a directory. SYNOPSIS List listname Dir P=PAT/k KEYS/s DATES/s NODATES/s SUB/k SINCE/k SORT/s TO/k UPTO/k QUICK/s BLOCK=BLOCKS/s NOHEAD/s FILES/s DIRS/s LFORMAT/k DESCRIPTION List displays the contents of a given directory. By contents, we mean the names of the subordinate files and directories, not the file data. Typing the List command by itself with no parameters generates a listing of the current directory. It also lists any comments attached by a FILENOTE command. THE LISTING DISPLAY List displays your files and directories one per line, with all the protection flags currently turned on right next to the filename. The fields which may appear in a Listed file are name [KEY] size/type protection date time :comment Methods are provided for getting a selective listing of files, as well as suppressing/adding most of the above display elements. A description of each one of the above elements is given below: Name The name of the file or directory. This can be a device or volume name. AmigaDOS wildcards are supported 100%. The inclusion of wildcards eliminates the need for the P (or PAT) keyword. PAT is retained to keep compatiblility with older versions of AmigaDOS. KEY This is the actual block number of the file or directory block header. This is not displayed by default, you must use the KEYS switch to generate this element of the listing. size/type This element gives the size of the file in bytes, or the string "empty" if the file is empty. If this is a directory and not a file, then the directory indicator ("Dir") will appear here. protection The protection bits of the current file, in the order hsparwed. If any of these is disabled, a dash (-) will appear in its place. The protection bits stand for "hidden, script, pure, archived, read, write, execute and delete", respectively. date time The date and time of the last modification to the file or directory. The format of the date display is determined by the value of the environment variable dateformat. These elements of the listing appear by default, but may be selectively added or subtracted by using the DATES or NODATES keywords. comment The comment as set by Filenote. If no comment exists, this field will not be displayed. Note that it is displayed on a line by itself, preceded by a colon. SELECTIVE LISTING OF FILES The methods described in this section allow you to list a portion of the files and directories on your disks. Ways exist to generate a list of files that conform to a certain pattern, or that were created/modified before or after a certain date. You may also combine these options, for example, you may get a list of all files which end in .c and were created or modified since a certain date. These options are described below: Dir List this directory instead of the current directory. This parameter may be a filename, in which case the single file is shown. You may also use any legal AmigaDos pattern in this position, in which case the files and directories listed will be those which match the pattern, if any. (This feature was added to the BCPL List in the V1.3 enhancer.) PAT List only files and directories which match the pattern. You must specify the keyword PAT or its abbreviation P. This is no longer truly necessary with the expanded capabilities of AmigaDOS wildcards, since it is usually more convenient to simply include the pattern in the directory specification as described above. It is included for BCPL compatibility. SUB In this option the SUB keyword must come before the string. If spaces are in the string, it must be enclosed in quotes. With the inclusion of AmigaDOS wildcards, this keyword is really not needed. It searches for an occurence of the substring anywhere within the directory name or filename. Think of this as a short form of "List PAT *substring*" or a long form of "List *substring*". List will reject any attempts to combine the use of PAT and S. Wildcards in the initial DIR argument are matched and then checked again to match against the substring. SINCE While the pattern matching options above filter files and directories on the basis of their names, this option, and the following UPTO option, filter out files based on their last modification date. SINCE displays only files which have been created or modified on or later than the specified date. All older files are not displayed. You may specify the date in the currently defined dateformat (see Environment Variables) or you may use a word such as SUNDAY, TODAY, YESTERDAY, etc. UPTO The inverse of SINCE, this option displays only files and directories which have been modified or created on or before the specified date. Files younger than this date are not displayed. See SINCE for a description of the date format list expects. FILES Display only files, and not the directories. DIRS Display only directories, and not the files. CONTROLLING THE DISPLAY The options below allow you to alter the format of the display listing, or to send it to another file or output display device (that's usually a printer). TO You can specify a file or a device you wish the listing to be sent to using this keyword. If not specified, the default of the current screen will be used. If the file already exists then the old file will be replaced (and gone forever) while being replaced with this new file. If the protection bit is set on the old file LIST will not work. It is very useful to LIST TO prt: to get a hard copy of your disk listing. DATES Forces the date and time of creation to be displayed in the current dateformat. This keyword does not have to be used unless you are using the QUICK or NODATES keywords. NODATES Will not display time and date information, only the filename, size, protection and comment fields will be displayed. Using DATES with this will force the creation dates and times to display. QUICK Displays only the filename field, one filename per line, with no trailing spaces. You can LIST just the files or direcotries by using the FILES or DIR options. You can combine this with other options such as DATES and KEYS to selectively enable these fields. Under 2.x/3.x KEYS no longer works with this keyword. KEYS Displays the block number of each file header or directory header. All files are assigned using block numbers. This is how AmigaDOS keeps track of your files. Each file has a unique block number assigned to it. This is its address on the disk. The block number appears to the left of the file length. SORT Sorts the file and directory names into ascending alphabetical order. Case is disregarded. Note that this is an option available only with the ARP list. Sorts by DATE if you include the DATES keyword. BLOCK=BLOCKS Displays filesizes in blocks, rather than bytes. NOHEAD Suppresses the default "Directory..." header and the "x files -x directories -x blocks used" footer display. LFORMAT LFORMAT can be used to control the output of list, and especially to generate command lines to be fed to the shell. LFORMAT can is most useful when you want to generate a script file. To send the LIST output to a script file, you can either redirect LIST's output using the ">" or "TO" keywords. LFORMAT takes a string as an argument which can be any ascii string. The LFORMAT substring can be used multiple times. This allows you to use the listing name more than once per line. The second time you use the string the first relative path will be replaced by %S, and the path of the second argument will be used (BTW, a relative path is merely the list of directories you must traverse to get from the specified directory to the current one.) If you use three substrings, then the first will be replaced by the relative path, while the second and third will be the file or subdirectory names. If you use it four times, the first and third will be the relative paths, and the second and fourth will be the subdirectory or file names. To include the output of List in this string, you can use the "%S" sequence under 1.3 or 2.x/3.x as follows: "%S" Filename "%S%S" Pathname/Filename "%S%S%S" Pathname/FilenamePathname "%S%S%S%S" Pathname/FilenamePathname/Filename The following information may be substituted for the string as output and is for 2.x/3.x Only: %A :Attributes (protection flags) %B :Size of file in blocks %C :Comments attached to the file %D :Date of file creation or last update %F :The complete absolute path (starting with the volume name) %K :Key block number %L :Length of the file in bytes %N :Name of the file %P :The relative path(starting at the current directory) %T :Time of creation or last update The following information may be substituted for the string as output and is for 2.1/3.x Only: %E :Extension only (the part of the filename after the last period) %M :Filename minus the extension (everything up to the last period) ALL :Lists the contents of all the subdirectories of the specified directory, as well as the directory itself. The %S's may be separated by spaces, other ascii text or nothing, as above. Here is an example of LFORMAT that will create a script to Type each file: List LFORMAT="Type %S%S" Of course, to use this, you must save it in a file using TO or one of the IO Redirection operators ('>', '>>'). If you are using 2.x/3.x, you can also pipe the output of List directly into the Execute command. ENVIRONMENT VARIABLES The List uses the same dateformat variable as used by the Date command, and in essentially the same way. If it is not defined, or if it has an illegal value, the default AmigaDOS display and input is used. Otherwise, the display and the input of dates is determined as follows: 0 AmigaDOS format DD-MMM-YY. 1 International format YY-MM-DD. 2 U.S. format MM-DD-YY. 3 Canada DD-MM-YY If you prefix the above numbers with a dash, then the display of names like TODAY, MONDAY, FUTURE, etc., will be disabled and the format string as defined above will be used exclusively. Note that this governs the format that List expects as input as well as the format List uses for display. EXAMPLES 1. To display all files in df1: ending with the characters "#?.c" which were modified later than TUESDAY at 00:00 hours. List df1:#?.c SINCE WEDNESDAY 2. To output just the names and dates for items in the current directory beginning with the letters 'stuff' that were created or last updated on or before April 16, 1967. Sent the output out to a file called 'StuffOut' in the Ram:T directory. LIST stuff#? QUICK DATES UPTO 16-Nov-67 TO Ram:T/StuffOut 3. To list the information about the contents of the current CLI directory. LIST 4. To print the block number of all the files in the current directory. LIST KEYS to PRT: or LIST > PRT: KEYS 5. To display the information about the files in the directory art/adult whose names contain the string 'girls' LIST art/adult/#?girls#? (note: Information about both 'Really Ugly Girls' and PrettyGirls would be displayed) 6. To set the pure bit of every file in the stuff: directory. LIST >RAM:ThisFile stuff:#? LFORMAT "protect %S +p" (now you have a file called Ram:ThisFile which contains the commands to set the PROTECT bit on all the files in the stuff: directory. Now, just EXECUTE RAM:ThisFile