


                  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
