Amiga Elysian Archive/AmigaElysianArchive.iso/newc_dev/ls40.lzh/ls.doc

Text File | 1990-05-11 | 20KB | 498 lines

     LS(1)                        AmigaOS 1.3                    LS(1)


     NAME
      ls - list contents of directory


     SYNOPSIS
      ls [ [ -options <args> ] [ names ] ] ...


     DESCRIPTION
      For each directory name argument, ls lists the contents of the
      directory; for each file name argument (non-wildcarded), ls
      lists the entry using the long listing format.  If wildcards
      (* or ?) are passed to ls, it internally expands the filespec
      into a list of names, and lists them in the requested format
      (short, long, or single column).

      The output is sorted alphabetically, by default, and the short
      format listing is used unless the argument name is a "fully named
      path" (i.e., one without wildcards), or an option flag requests a
      different format.

      When no argument is given, the current directory is listed.  When
      several arguments are given, the arguments are processeed in the
      order presented, with "non-sticky" option flags being reset to the
      default value between arguments.  Option flags may preceed the
      individual name arguments.

      There are three major listing formats.  The default format is to
      list the entries in a short, columnar format, with entries sorted
      down the columns.  The long and single column (one entry per line)
      formats are enabled with various options.

      For the short format, ls reads the size of the current window to
      determine the character positions available on one line, and the
      number of lines available without scrolling.    If this information
      cannot be obtained, ls assumes 77 columns by 23 lines.  A builtin
      "pager" is available by default when the short format is used.

      The output formats and applicable option switches are designed to
      emulate the UNIX(R) equivalent as closely as possible.

      The options are as follows:

           -a   Lists entries including those whose names begin with a
            dot (.)  These are not listed by default.

           -b   Normally, the long format listing shows the total number
            of blocks used by an entry (including the File Header
            and Extension blocks).  This option limits the block
            count to the number of Data Blocks only.

           -c   Shows the comment/filenote for an entry, if any.  The
            comment is shown enclosed in quote marks on a line
            beneath the entry.    This option implies the long format
            listing.

           -d   Show only entries that are directories.

           -e   By default, ls shows the "execute" attribute bit in the
            long format listing as an "x".  This option changes that
            to an "e".  [sticky]

           -f   Show only entries that are files (i.e., not directories).

           -h   Lists entries including those whose "hidden" attribute
            bit is set.  These are not listed by default.

           -i   Lists entries including those whose names end with the
            string ".info".  These are not listed by default.

           -k   The output listing is sorted by the disk "key" value of
            the entries.  [sticky]

           -l   Lists in long format, giving the entrys' attribute bits,
            comment present flag, disk key (if -k or -K specified),
            size in blocks, size in bytes, date, and name.

           -m   Lists entries with the case "mixed".  Normally, the case
            of entry names is respected when sorting.

           -n   No sorting of entries is performed.  Entries are listed
            the order in which they are Examined by the system.

           -o   Use the old ls version (v3.1) long format when a long
            listing is requested.  Note: this option does not cause
            a long listing by itself, but only specifies that the
            old format be used, should a long listing be requested
            (see notes below).

           -p   Puts a slash (/) after each entry name if that entry is
            a directory.

           -q   Normally, ls will continue to process name arguments
            until the argument list is exhausted.  This option will
            cause ls to terminate when an entry is not found.  (This
            option only has meaning for "fully named path" args).

           -r   Reverses the sort order to get reverse alphabetic, oldest,
            smallest, or highest key first as appropriate.

           -s   Sort by size, with largest first.  [sticky]

           -t   Sort by date, with newest first.  [sticky]

           -u   Display a short usage summary, showing syntax and options.

           -v   Use variable column widths in the short format listing.
            Normally, ls bases the column widths on the longest name
            in the directory, and uses that value for all columns.
            This option allows each column's width to be determined
            by the longest name in the column itself.

           -x pat
            Excludes entries matching the pattern "pat" from the
            listing.  The pattern string may contain "*" and "?",
            which are interpreted as wildcards with the usual meaning.
            [sticky]

           -z   Overrides the calculation of the block counts, and shows
            the value found in the filesystem's NumBlocks entry.
            This option is useful for getting an indication of a
            file's current block size if the file is being written to,
            or if the file resides on a psuedo-device (such as a
            "pathass" assign) that has no inherent bytes/block value.
            Note: the block count reported should only be used as an
            indicator, as it may not be exact.

           -A   Lists all entries.    This option is equivalent to using
            the a, h, and i options together.  Note: entries matching
            the exclude pattern (-x) are not listed.

           -B size
            Normally, ls computes an entry's block count using the
            bytes/block value appropriate for the filesystem or
            device on which the entries reside (currently 512 for the
            FFS, and 488 for the OFS).    This option allows that value
            to be specified directly, which can be useful to determine
            if an entry or entries will "fit" on a device which has a
            different bytes/block value.  In such usage, the "size"
            of the target device would be specified by the option's
            argument, and the block count obtained then compared to
            the number of blocks available on the target device (with
            Info, for example).  [sticky]

           -C   Single column (one entry per line) output format.  Note:
            this usage of "-C" is exactly opposite UNIX's usage.

           -D   Normally, files and directories are intermixed in the
            output listings.  With this option, all directories will
            appear seperately, and last in the listing.

           -E   Normally, ANSI escape codes are used to highlight names
            of directory entries and comments.    This option disables
            such highlighting.    Note: ANSI escape codes are normally
            automatically disabled when the ls output is redirected
            to stdout or is piped.  [sticky]

           -F <format>
            Allows the specification of the output format when the
            old long format is used.  This option implies -l and -o
            (see notes below).

           -G   Disables the subdirectory-by-subdirectory summary totals
            normally provided when the long format listing is used.

           -H   Disables printing of the subdirectory name header line
            normally provided for other than the current directory.

           -I   Normally, when using the short format, if the number of
            entries is larger than can be displayed in the window ls
            is using, a builtin "pager" is invoked to prevent the
            list from scrolling.  This option (as well as output re-
            direction or pipeing) inhibits the pager.

           -K   Display disk "keys" in the long format listing.  Normally,
            they are not shown.  This option implies the long format.

           -Ln  Recursively lists subdirectories encountered, with depth
            limited to "n" levels.  A depth of n = 1 lists only the
            current directory.

           -M   Ignore alphabetic case when matching directory contents
            with wildcard patterns.  Normally, the case of names is
            respected.    This option applies to both name arguments,
            and exclude (-x) patterns.

           -N name
            Show only entries that are newer than entry "name".
            "Name" cannot be wildcarded.

           -O name
            Show only entries that are older than entry "name".
            "Name" cannot be wildcarded.

           -P   Show entry names as full (absolute) path names.  This
            option implies the long format.

           -Q   Normally, ls disables the system requesters that pop up
            when a device is empty, etc, and presents an error msg.
            This option turns them on again.  [sticky]

           -R   Recursively lists subdirectories encountered.

           -S   Normally, files and directories are intermixed in the
            output listings.  With this option, all directories will
            appear seperately, and first in the listing.

           -T   Provides a grand total of all files and directories, and
            their sizes, for all entries processed.  This option is
            valid with all formats.  Note: the seperate totalization
            line will not be printed, if the information is simply a
            duplication (as it would be for just a long format list
            of the current directory).

           -V   Show entry names as relative (to the current directory)
            path names.  This option implies the long format.

           -W   Normally, when a "wildcarded match" occurs on a directory
            entry, its contents are listed.  This option prevents the
            contents from being listed.  Only the directory name will
            be printed.

           -X width
            Forces the short format to use "width" for the number of
            columns available in ls's window.  [sticky]

           -Y height
            Forces the short format to use "height" for the number of
            lines available in ls's window.  [sticky]

           -Z   Forces output of ANSI escape sequences for highlighting,
            even though the ls output may be redirected to stdout, or
            piped.  See also, -E.  [sticky]

           -0 thru
           -6   Specifies the format to be used for the date in the long
            listing (not applicable to the -o long format).  [sticky]

            Available formats are:
               0: age to years:  mmm  d hh:mm  aging to  mmm dd  yyyy
               1: full:      mmm dd yyyy  hh:mm:ss
               2: dash alpha:     dd-mmm-yy hh:mm:ss
               3: dash numeric:  mm-dd-yy hh:mm:ss
               4: slash:     mm/dd/yy hh:mm:ss
               5: european:     dd/mm/yy hh:mm:ss
               6: dot:         yy.mm.dd hh:mm:ss

            Format 0 is the default, and is the format used by UNIX.
            The "aging" period is 180 days, and the day may be either
            one or two digits, as required.

           -?   Synonym for "-u".  Displays a short usage summary.

           -    Forces the next argument to be interpreted as a name.
            This is useful for specifying entries whose names begin
            with the "-" character.


      The attribute bits printed in the default long format consist of a
      nine character string.  Each position contains a letter if the
      attribute it represents is "true", or a "-" otherwise.  If all
      attributes were to apply to a single entry, the string would appear
      as "dhsparwxd", where:

         d    indicates the entry is a directory
         h    indicates the entry is a hidden entry
         s    indicates the entry is a script file
         p    indicates the entry is a pure executable (residentable)
         a    indicates the entry has been archived, and not modified since
         r    indicates the entry is readable
         w    indicates the entry is writable
         x    indicates the entry is executable (or "e" with the -e option)
         d    indicates the entry is deletable

      It should be noted that AmigaOS 1.3 includes only marginal support
      of the attribute bits, and enforces few of them.  The above however
      is their formal definition.  Also, "directory" is not an attribute
      bit, but is included in the attribute string.  Further, a "c" flag
      will appear to the right of the attribute string should an entry
      have an associated comment/filenote (or a blank if not).

      AmigaOS makes provisions for additional attributes, some of which
      may be application specific.    Should any of these be set, ls will
      display a "+" instead of a "-" in the hidden attribute position,
      or an "H" if the hidden attribute itself also applies.


      The ls -l (default long list) command prints its output as follows:

           --sa-rw-d c   136    65383  May    5 18:15  fubar

      This horizontal configuration provides a good deal of information.
      From right to left, you see that the current directory holds one
      file, named "fubar".  It was created (or at least last modified) at
      6:15 P.M. on May 5th.  It contains 65,383 bytes, and occupies 136
      blocks on the device where it is located (including the file header
      block, and any extension blocks).  There is a comment associated
      with the file, and it is (supposedly) a script file that has been
      archived, and may be read, written, and deleted.


     EXAMPLES
           ls -a

      This command prints the names of all files in the current directory,
      including those that begin with a dot (.), which normally are not
      printed.  The short format is used.


           ls -cAKP1

      This command provides you with a maximum amount of information on
      all files in the current directory, including those that normally
      do not print (A), associated comments, if any (c), the disk key
      numbers (K), the full path name (P), and the full date format (1).
      A long format listing is implied (both c and P).


           ls -ARTB488

      This command prints the names of all files in the current directory
      (A), and all subdirectories below it (R), with a grand total of the
      counts and sizes at the end (T).  Block counts are computed as if
      the files were located on an OFS (Old File System) device (B488),
      and the short format is used.

      If the files were actually located on an FFS (Fast File System)
      device, such as a hard disk partition, comparing the grand total of
      the block counts to the available blocks on an OFS floppy (with say,
      Info) would tell you if the tree would fit on the floppy.


           ls -hrtX50 -Y 15 -Tx*zoo

      This command prints a short format listing of the current directory,
      including hidden files (h), sorted by date (t), with oldest files
      first (r).  The output "window" is restricted to 50 columns (X50),
      by 15 lines (Y 15).  A totalization of all entries is requested (T),
      and entries ending with the string "zoo" will be excluded (x*zoo).


           ls -lN df0:emily.c -sOdf1:lynn.c df0:*.c

      This command prints a long format listing (l) of all files ending
      with the string ".c" on df0: that are newer than "df0:emily.c"
      (N df0:emily.c), but are older than "df1:lynn.c" (Odf1:lynn.c).
      The listing will be sorted by size, with largest files first (s).


     NOTES
      Wildcards:
      ----------
      Normal wildcards may be used in file names and in the last level of
      a directory path name.  The "*" character is used to match any
      number of characters (including zero), and a "?" matches any single
      character.  Wildcards may also be used in specifying an exclusion
      pattern (-x).

      If the shell that is used to invoke ls expands the wildcards itself,
      they MUST be quoted in some manner for ls to work as intended.
      Some common shell quoting methods are:  "*" or \* or '*   See your
      shell documentation for details.


      Options:
      --------
      Option flags may be given in any order.  Where options conflict,
      such as specifying both -s and -t, the last option encountered is
      the one used.

      Option flags may be given grouped or seperately.  E.g., "-lsR" is
      logically the same as "-l -s -R".

      Options requiring an argument, such as -x or -B, must be the last
      option in a group, or given seperately, and must be immediately
      followed by the argument (with or without seperating blanks).  The
      forms:  "-ltB488",  "-ltB 488",  "-lt -B488",  and "-l -B   488 -t"
      are all correct, and logically the same.  The form "-lB488t" is
      NOT correct, and will result in unspecified behavior.

      Options are normally reset to their default state between name
      arguments.  Some flags however, apply to all name arguments, and
      are identified as "sticky" in the option descriptions above.


      Pathnames:
      ----------
      A pathname with spaces in it like "Wombat Soup", must be surrounded
      by quotes.  Up to 30 seperate pathname patterns can be processed by
      ls per command.


      Aborting:
      ---------
      ls may be aborted at any time by issuing a control-C (assuming the
      invoking shell passes ^C's along to the applications).  ls will
      print the string "**BREAK" and then terminate when this occurs.


      Formatted Output:
      -----------------
      For customized output, there is a special option that expects a
      format rule as the next argument:

      -F <format>
           Format output with <format), using the following symbols:
          %p  print the attribute bits
          %d  print the date: yy-mm-dd
          %t  print the time: hh-mm-ss
          %b  print the number of blocks used by the entry
          %s  print the number of bytes  used by the entry
          %n  print the name of the entry
          %%  print a percent symbol
          \n  print a linefeed
          \t  print a tab
          \\  print a backslash symbol

           The default format rule that ls uses for old format long
           listings is:  -F "%p %d %t %4b %8s %n\n".   Note that a format
           specification that contains spaces must be quoted.

           Any of the format options that begin with the '%' symbol can
           have an optional pad count that lets you specify how many
           columns to use.    For example:  -F "%40n\n"  would print each
           entry name right justified in a field of 40 columns.

           The attribute bits in this format are as described above, with
           one exception: the first position is used to indicate that the
           entry has an associated comment.  If so, a "c" is used (else a
           "-").

           You can use this feature of ls to help create simple batch
           command files.  For example, the command:

          ls -PF "copy %n RAM:\n" df0:*.h

           tells ls to perform a listing using full pathnames with a
           special format, matching only filenames that end with ".h" in
           directory df0:.    Suppose df0: has the following files in it:

          joe.h  fred.h  pete.h  ted.h

           The example ls command would result in the following list of
           commands:

          copy df0:fred.h RAM:
          copy df0:joe.h RAM:
          copy df0:pete.h RAM:
          copy df0:ted.h RAM:

           A script file from this by redirecting the output of ls to a
           temporary file:

          ls >ram:templist -PF "copy %n RAM:\n" df0:*.h
          execute ram:templist      ; do the script,
          delete ram:templist      ;    and delete it


      Tip:
      ----
      To list files older or newer than a certain date, rather than a
      certain file, you can do this:

           echo >RAM:datemark "Marker"    ; create a temp file in RAM:
           setdate RAM:datemark 07-Jul-89 ; set datestamp for temp file
           ls -N ram:datemark df0:          ; list files newer than "datemark"
           delete ram:datemark          ; remove temp file


     CAVEATS/BUGS
      Refer to the README file accompanying this distribution for notes
      of any currently known bugs or limitations.


     AUTHORS
      Justin V. McCormick is the author of the of ls (v3.1), and other
      earlier revisions.  Version 3.1 was used as a base on which to
      develop the current revision (v4.0k), because of its excellent
      "inline" sorting and its columnation algorithms, as well as its
      small size, and fast code.

      Kim E. DeVaughn provided the numerous enhancements, fixes, etc, to
      bring v3.1 up to the current v4.0k.


     COPYRIGHT
      ls v4.0k is (c) Copyright 1990, Kim E. DeVaughn, all rights
      reserved.  See the "License" accompanying this distribution for
      limitations, and other details.

      UNIX is a registered trademark of AT&T.  They had nothing to do
      with any of this code, but did provide the "model" for some of its
      output formats and options.