home *** CD-ROM | disk | FTP | other *** search
/ 17 Bit Software 3: The Continuation / 17-Bit_The_Continuation_Disc.iso / files / amg11.dms / amg11.adf / Ls / ls.doc < prev   
Text File  |  1993-12-02  |  10KB  |  251 lines
  1.  
  2.  
  3.      Ls User's Manual
  4.  
  5.  
  6.                Directory Listing Utility for the CLI Environment
  7.                                 V1.0  15-Aug-87
  8.  
  9.  
  10.                           Copyright (c) 1987  J. Brack
  11.                               All Rights Reserved
  12.  
  13.      This   software   and/or   documentation   is   released   for  public
  14.      distribution  for  personal,  non-commercial use only.  Limited rights
  15.      to  use, modify and redistribute are hereby granted for non-commercial
  16.      purposes,  provided  that  all copyright notices remain intact and all
  17.      changes  are  clearly documented.  The author makes no warranty of any
  18.      kind  with  respect  to  this  product  and  explicitly  disclaims any
  19.      implied  warranties  of  merchantability or fitness for any particular
  20.      purpose.   In  no  event  will  the author be liable for consequential
  21.      damages  even  if  the  author  has been advised of the possibility of
  22.      such damages.  
  23.  
  24.      You  may freely copy and redistribute this product. It may be uploaded
  25.      to  any  information  service  except  those  that  attempt  to  claim
  26.      copyright on individual uploads.  
  27.  
  28.  
  29.      Purpose:
  30.  
  31.      The  AmigaDOS  "Dir"  utility  provides  a  neat,  sorted  listing  of
  32.      filenames  within  a  directory.   When the "opt a" qualifier is used,
  33.      "Dir"   will  descend  through  any  sub-directories  it  finds.   The
  34.      AmigaDOS  "List"  utility  provides  an  unsorted yet more informative
  35.      listing  of  files,  their  sizes, their protection and their creation
  36.      dates.   "List"  also provides pattern matching on file names but will
  37.      not  descend  into  sub-directories.  I wanted a utility that combined
  38.      the best features of both "Dir" and "List", so I wrote "ls".  
  39.  
  40.  
  41.      Usage:
  42.  
  43.      Place "ls" in your "c:" directory, and use it as follows: 
  44.  
  45.              ls [switches] [name]
  46.  
  47.      Where [switches] may be:
  48.                      -a      Descend through "all" sub-directories
  49.                      -d      Show sub-directories along with files
  50.                      -n      List only the "new" files created today
  51.                      -p      Provide output in "pipe" format
  52.                      -s      List only the files that match a pattern
  53.                      -v      Display "ls" version number information
  54.                      ?       Display small "usage" help message
  55.                      [NULL]  Default to list all files in default directory
  56.  
  57.      Where [name] may be:
  58.                      1. [NULL] - default to current directory
  59.                      2. Any valid directory path
  60.                      3. Any valid device name
  61.                      4. Any valid filename
  62.  
  63.      Examples:
  64.  
  65.              ls 
  66.              List  all  files  in  the  default directory.  Sub-directories
  67.              will not be included in the list of files.  
  68.  
  69.              ls -d 
  70.              List   all   files   in   the   default   directory  and  list
  71.              sub-directories.    Files   within   sub-directories  are  not
  72.              listed.  
  73.  
  74.              ls -n -p 
  75.              List  all  files  in  the  default directory that were created
  76.              today in "pipe" format (pipe format is explained later).  
  77.  
  78.              ls -a df1: 
  79.              List all files in all directories on device "df1:".  
  80.  
  81.              ls -a -n Textfiles 
  82.              List  all  files created today in directory "Textfiles" and in
  83.              sub-directories nested within "Textfiles".  
  84.  
  85.              ls foo 
  86.              List  all  files  in  directory  "foo",  or  if "foo" is not a
  87.              directory, list information about the file "foo".  
  88.  
  89.  
  90.      Pattern Matching:
  91.  
  92.      The  "-s" switch lets you search for files using the famous "*" (match
  93.      any  number  of  characters)  and  "?"  (match  any  single character)
  94.      wildcards.  Alphabetic matching is case-insensitive.  For example: 
  95.  
  96.              ls -s*.doc 
  97.              List  all  files  in  current  directory  whose names end with
  98.              ".doc" 
  99.  
  100.              ls -se* Basic 
  101.              List  all  files  in  the  "Basic" directory whose names start
  102.              with "e".  
  103.  
  104.              ls -s??? -a df0: 
  105.              List all files on device "df0:" that are 3 characters long.  
  106.  
  107.              ls -sncd.? -n programs/c 
  108.              List  all  files  created today in directory "programs/c" that
  109.              are  5  characters long beginning with "ncd." (e.g.: ncd.c and
  110.              ncd.o might match this string).  
  111.  
  112.      Output Format:
  113.  
  114.      "ls"  lists files within directories in alphanumeric sorted order.  If
  115.      sub-directories  are found within the specified directory and the "-d"
  116.      switch   has   been   used,   the  directory  names  are  indented  in
  117.      alphanumeric  order  using  a  contrasting  text  color  following the
  118.      files.   If the "-a" switch has been used, the contents of the current
  119.      directory  is  printed  followed by the contents of each sub-directory
  120.      with  the directories appearing in alphanumeric sorted order.  Typical
  121.      listings may appear as follows: 
  122.  
  123.      1> ls :Textfiles
  124.       Directory: :Textfiles
  125.      frog.txt           6908/15     Today
  126.      serpent.doc       13498/28     Thursday
  127.      toad.txt           6330/13     27-Jun-1987
  128.        26736 bytes, 56 blocks in 3 files
  129.  
  130.      1> ls -d :Textfiles
  131.       Directory: :Textfiles
  132.      frog.txt           6908/15     Today
  133.      serpent.doc       13498/28     Thursday
  134.      toad.txt           6330/13     27-Jun-1987
  135.        26736 bytes, 56 blocks in 3 files
  136.  
  137.        Sub-directory: gfile
  138.        Sub-directory: iff
  139.  
  140.      1> ls -a :Textfiles
  141.       Directory: :Textfiles
  142.      frog.txt           6908/15     Today
  143.      serpent.doc       13498/28     Thursday
  144.      toad.txt           6330/13     27-Jun-1987
  145.        26736 bytes, 56 blocks in 3 files
  146.  
  147.         Directory: :Textfiles/gfile
  148.        gfile.doc      15293/32     22-Jun-1987
  149.        gfile.txt        196/1      Thursday
  150.          15489 bytes, 33 blocks in 2 files
  151.  
  152.         Directory: :Textfiles/iff
  153.        iff.doc          3201/7      10-Jul-1987
  154.        iff.help         6801/14     11-Feb-1987
  155.          10002 bytes, 21 blocks in 2 files
  156.  
  157.      In  the  first  example  the  "-d"  switch  was  not specified, so the
  158.      presence  of sub-directories "gfile" and "iff" was not listed.  In the
  159.      second  example  the "-d" switch was specified causing sub-directories
  160.      "gfile"  and  "iff"  to  be  listed in contrasting text color.  In the
  161.      third   example  the  "-a"  switch  causes  "ls"  to  descend  to  the
  162.      sub-directories and list their contents.  
  163.  
  164.  
  165.      Pipe Output:
  166.  
  167.      The  output  of  "ls" can be redirected to a file which can be read by
  168.      another  application  program.   This other program may take advantage
  169.      of   the  pattern  matching,  directory  descent  and  date  selection
  170.      features  of "ls".  In a well known operating system whose name starts
  171.      with  "U",  this  is  known  as  "pipe" communications.  In support of
  172.      piping,  "ls"  provides  the "-p" switch.  As an example, consider the
  173.      pipe output format of the directory and file structure used above: 
  174.  
  175.              1> ls -a -p :Textfiles
  176.              :Textfiles/frog.txt
  177.              :Textfiles/serpent.doc
  178.              :Textfiles/toad.txt
  179.              :Textfiles/gfile/gfile.doc
  180.              :Textfiles/gfile/gfile.txt
  181.              :Textfiles/iff/iff.doc
  182.              :textfiles/iff/iff.help
  183.  
  184.      Note  that  all the "frills" are stripped from the pipe output format.
  185.      This  format  is  not  pretty  for  human  beings,  but it is nice for
  186.      program  input.  When "-p" is specified, the "-d" switch is turned off
  187.      so  that  you  never  need to worry about directory names appearing in
  188.      pipe  output.   If  you  can't  think  of  a  program  that could take
  189.      advantage  of  this  feature, stay tuned to your download area, I have
  190.      many things "in the pipe".  
  191.  
  192.  
  193.      Output Redirection and Aborts:
  194.  
  195.      Like  all  good  C programs, the output of "ls" may be redirected to a
  196.      file or the printer: 
  197.  
  198.              1> ls >a.tmp -p (sends pipe listing to disk file named "a.tmp")
  199.              1> ls >prt: -a  (sends listing of all directories to printer)
  200.  
  201.      To abort a lengthy listing, type "control-C".  
  202.  
  203.  
  204.      In Closing:
  205.  
  206.      The  "-a"  and  "-d"  switches  are,  in  fact,  contradictory but not
  207.      illegal  in  combination.   If  both  switches  are specified, "-a" is
  208.      assumed.  
  209.  
  210.      The  "-n"  switch  does  not list new directories.  The search applies
  211.      only to new files within some directory.  
  212.  
  213.      The  choice  of  switch  names  for  options  "a"  and  "s"  may  seem
  214.      unimaginative,  but  I  chose  them to be compatible with the AmigaDOS
  215.      "Dir  opt  a"  and "List -s" standard.  It may also be argued that the
  216.      name  "ls"  is  trite  since  there  are  several  hundred  previously
  217.      existing  programs  of  the  same name.  Well "ls" is fewer keystrokes
  218.      than  "pumpkinseed"  and  a  standard  name  for  this function in the
  219.      operating system whose name ends in "X".  So there! 
  220.  
  221.      "ls"  buffers file names and directories in allocated memory.  If your
  222.      RAM  is close to full, "ls" may abort with a "not enough memory" error
  223.      when large directories are listed.  
  224.  
  225.      If  the  brightness  control  on your monitor is set too low, "ls" may
  226.      not  appear  to  work,  in  fact  it  may  appear that your machine is
  227.      broken.  Be sure you can easily read your screen for best results.  
  228.  
  229.      Why  doesn't  "ls"  show  file protection status?  Call it developer's
  230.      fiat.   I  never  play  with  file protection, so I don't show it.  If
  231.      "ls"  proves  to  be  popular  and  the  community sees a need for the
  232.      inclusion of file protection status, I will add it.  
  233.  
  234.      I  have  been  using  "ls"  for  several weeks without incident, and I
  235.      believe   that   it  is  bug-free.   If  you  have  any  bug  reports,
  236.      suggestions,  comments  or  money to send, I can be contacted on GEnie
  237.      (mail address: JBrack) or by snail at: 
  238.  
  239.              Ohio Imaging Inc.
  240.              23060 Miles Road
  241.              Bedford Heights, Ohio  44128-5443
  242.  
  243.      "ls"  is  a  product  crafted  by  J. Brack, purveyor of fine software
  244.      tools for over 1.0e-1 of a century.  
  245.  
  246.      "AmigaDOS" is a trademark of Commodore-Amiga Inc.  
  247.  
  248.      "ls"  is written in MANX Aztec C V3.4a.  Thanx to Manx for a wonderful
  249.      product.  
  250.  
  251.