home *** CD-ROM | disk | FTP | other *** search
/ Amiga Elysian Archive / AmigaElysianArchive.iso / newc_dev / ls40.lzh / README < prev    next >
Text File  |  1990-06-05  |  16KB  |  356 lines
  1. README                  ls v4.0k                  05/11/90
  2.  
  3. ls v4.0k is (c) Copyright 1990, Kim E. DeVaughn, all rights reserved.
  4.  
  5.  
  6. Introduction:
  7.  
  8. What?!    Another version of "ls" ...?  Why in the world does the world need
  9. Yet Another Version of such a common command?  Actually, that's the answer
  10. (as well as the question).
  11.  
  12. If you kept track of such things (like some operating systems do), you'd
  13. probably find the "most executed" command is by far, "ls" (or dir, etc).
  14.  
  15. We use "ls" not only to see what's where, but when what's there got there,
  16. how big it is, what it's attributes are, etc.  We also use "ls" to check our
  17. spelling, make lists of files, and so forth.
  18.  
  19. Because of this high usage, we'd like it to work the way we think it ought
  20. to, or at least the way we're used to.  For alot of people, this means
  21. "like UNIX(R)".*   Not that the UNIX way is the *best* way, but when you have
  22. to deal with UNIX at work, etc, it makes it much more convenient and prod-
  23. uctive (not to mention much less error prone), to have the Amiga environment
  24. "similar".  At least in the CLI/shell environment.
  25.  
  26.            * - UNIX is a registered trademark of AT&T, if you didn't know.
  27.  
  28. To that end, I've reworked Justin McCormick's "ls" (v3.1) so it's output and
  29. option flags (where applicable) are much closer to UNIX's implementation, by
  30. default.  It still isn't a "perfect" emulation, but it's quite close.
  31.  
  32. Along the way, I've fixed a number of bugs (none terribly major), added some
  33. additional features, and just about run out of letters for the option flags!
  34.  
  35. If Justin thought "ls" was getting bloated with options in his most recent
  36. rev (v3.1), he'll surely gag after seeing what I've done :-).  Still, with
  37. all the new options, etc, "ls" is only about 16K.  And it can still be made
  38. resident, etc.    In fact, with the right set of switches, you can make it
  39. behave just like v3.1 (bug fixes excepted) if you want!
  40.  
  41. The reason for this is that I'm a very firm believer in letting people "have
  42. it their way".  I'm sure I could chop out about 4K or more if I just did it
  43. "my way", but other people have other ideas.  The default way however, *is*
  44. "my way" ... or actually "the UNIX way".
  45.  
  46.     [ BTW ... if you want this version of "ls" to look/work like v3.1, the ]
  47.     [ following switches will do it for you:  -AMSWbemoqv  ... :-)       ]
  48.  
  49.  
  50.  
  51. Installation:
  52.  
  53. Just copy "ls" to a directory in your path.  If the "p" (pure) bit has been
  54. stripped of somewhere along the way, you can turn it on using the Protect
  55. command (or chmod, etc) if you want to make "ls" a "resident" command.
  56.  
  57.  
  58.  
  59. Distribution:
  60.  
  61. Here is a listing of what you should have received in this distribution:
  62.  
  63. -----rw-d    7     2444  May 10 18:23  License
  64. -----rw-d      33    15901  Jun  5 11:31  README
  65. -----rw-d    4     1204  Jun  5 11:09  README.1ST
  66. ---p-rwxd      34    16028  May 11 02:13  ls
  67. -----rw-d      43    20124  May 11 09:46  ls.doc
  68. d----rwxd    1     0  Jun  5 10:35  src
  69. Dirs: 1    Files: 5    Blocks: 122   Bytes: 54949
  70.  
  71. src:
  72. -----rw-d    2      457  May 10 19:07  Linkfile
  73. -----rw-d    3      590  May 10 18:52  Makefile
  74. -----rw-d     137    65576  May 11 02:02  ls.c
  75. -----rw-d    9     3685  May 10 18:53  ls.h
  76. -----rw-d      73    34948  May 10 18:51  lssup.a
  77. -----rw-d      12     5160  Jul 29  1989  mycres.a
  78. -----rw-d    4     1104  Jul 29  1989  mycres.o
  79. Dirs: 0    Files: 7    Blocks: 240   Bytes: 111520
  80.  
  81. Totals:
  82. Dirs: 1    Files: 12    Blocks: 362   Bytes: 166469
  83.  
  84.  
  85.  
  86. What's New  (see "ls.doc" for details, etc):
  87.  
  88.     o  New (default) long listing format that *looks* like UNIX's (except for
  89.        things like owner, group ID, etc).
  90.  
  91.     o  Block sizes now include *all* blocks associated with a file, and are
  92.        finally accurate for FFS devices.
  93.  
  94.     o  By default, upper/lower case *is* significant in the output listing,
  95.        and in the wildcard pattern matching.
  96.  
  97.     o  By default, directories and files are intermixed, according to their
  98.        alphabetic position.
  99.  
  100.     o  By default, the short listing format uses fixed width columns, based
  101.        on the length of the longest filename in the directory.    Variable
  102.        width columns are still available.
  103.  
  104.     o  By default, "hidden", "*.info", and "dot" files (eg, .foo) are not
  105.        displayed.  There are switches for each, as well as an "all" flag.
  106.  
  107.     o  Several new options like the ability to limit the "-R" recursion depth;
  108.        ability to show absolute and relative path names in the long format
  109.        listing;  additional control of directory header and totalization
  110.        lines;  elimination of redundent totalization lines;  showing/sorting
  111.        on files' "disk keys";  control of the date format;  sort by date/size
  112.        defaults to newest/biggest first;  and a few other things.
  113.  
  114.     o  Improved error handling and error msgs.    Better "break" handling.  No
  115.        more "memory leaks" (yes, there is one in v3.1 ... it looses 300 bytes
  116.        on an error exit).
  117.  
  118.     o  The assignment of option flags has been "rationalized".  Applicable
  119.        flags from the UNIX "ls" were assigned 1st, followed by other flags
  120.        from v3.1, followed by new flags added in this rev.  However ... some
  121.        flag assignments from previous revs were changed when better mnemonic
  122.        values could be found, etc.   So ... check the usage, and/or docs.
  123.        Caveat emptor!
  124.  
  125.     o  Flags requiring arguments (eg, -N) may or may not be seperated from
  126.        the argument by spaces.    So, "-Nfoo" is just as legal as "-N  foo".
  127.  
  128.  
  129.  
  130. What's Not (yet) Done ... and Limitations/Caveats:
  131.  
  132.     o  Wildcard expansion is still done by "ls", rather than left to the shell
  133.        to do so (which is where it should be done, IMHO).  This is to avoid
  134.        the braindead limitation of being able to pass a command line of only
  135.        255 chars or so max to Exec() under AmigaOS 1.3.  Hopefully this limit
  136.        will be removed under AmigaOS 2.0.
  137.  
  138.        This also means that if the shell you're using expands normal wildcards
  139.        ("*" and "?") itself, you need to "quote" the wildcards in some manner
  140.        for "ls" to work as intended.  Depending on the shell you use, things
  141.        like "*" or \* or '* may work.  See your shell documentation.
  142.  
  143.     o  Each "fully named path" is still processed seperately, and will give
  144.        you an automatic "long format list" for each file encountered, or a
  145.        "short format list" for each subdirectory encountered.  This is why
  146.        you will get some rather weird output listings if you let your shell
  147.        expand wildcards, rather than passing the wildcards intact to "ls".
  148.        (A "fully named path" is a filespec that contains no wildcards ... in
  149.        other words, an actual file or dir name).
  150.  
  151.        This will change.  How it wiil change is somewhat dependent on what is
  152.        done in AmigaOS 2.0 with command line length limits, links, etc.
  153.  
  154.     o  Many flag settings get reset to the default values between each "fully
  155.        named path".  Some do not, and are identified in "ls.doc" as being
  156.        "sticky".
  157.  
  158.        This will change when the "fully named path" and wildcard expansion
  159.        issues are resolved.
  160.  
  161.     o  Doesn't support AmigaOS v2.0 links (or any other 2.0 enhancements),
  162.        since CBM hasn't finalized it (besides, I don't have 2.0 yet).
  163.  
  164.     o  I want to allow the user to override the default operation with flags
  165.        provided in environment variables.  This will require reworking "ls's"
  166.        startup code (or the use of the standard "cres", with accompanying
  167.        bloat of the executable) due to the current env var implementation as
  168.        files.  Dumb.
  169.  
  170.     o  The filename arguments required for the -N and -O options must be fully
  171.        specified.  Wildcards don't work here.
  172.  
  173.     o  The -N and -O options accept only filenames; they do not accept actual
  174.        dates.
  175.  
  176.     o  You must hit "return" to clear the short format's builtin pager's
  177.        "More ..." line (see -I), and continue with the listing.  I'd like to
  178.        change this to being able to hit any key.
  179.  
  180.        Also, the builtin pager works only on a directory-by-directory basis.
  181.        It'd be nice (read: this probably won't happen) if it worked on the
  182.        output as a whole.  And if it worked with the long format listing.
  183.  
  184.     o  When a long format listing is requested of a "psuedo-device", the
  185.        block count may be inaccurate, since such "devices" do not necessarily
  186.        have an inherent (or constant) bytes/block value.  Currently, the only
  187.        such case known are assignments made with the "pathass" utility.  When
  188.        this situation occurs, a warning message is issued to the effect that
  189.        the block counts may be inaccurate.
  190.  
  191.  
  192.  
  193. Known Bugs:
  194.  
  195.     o  Multiple wildcards in a given path do not work properly.  For example,
  196.        the command: "ls ls*/*.o"  lists the entire contents of the "ls40"
  197.        subdirectory, not just the ".o" files.
  198.  
  199.     o  Certain options are slightly incompatible.  The known instances occur
  200.        with the old (v3.1) long format, and the variable column form of the
  201.        short format, as I didn't touch that code much.  Known instances are:
  202.  
  203.        Show keys (-K) does not work with the old (-o) long format.
  204.  
  205.        Append "/" to dir names (-p) does not work with the variable
  206.        column short format (-vp will NOT append a "/").  However, if no
  207.        ANSI escape sequences (-E) is specified along with -v, they will
  208.        be appended to dir names.  This is the same behavior as "ls" v3.1.
  209.  
  210.     o  Seperate subdir totalization for "fully named path" entries does not
  211.        work.  However, their contribution to a grand total (-T) is included.
  212.  
  213.  
  214.  
  215. Quick Look:
  216.  
  217. usage: ls [ [-options <args>]  [names] ] ...
  218.   a  Show dot files      s  Sort by size        M  Ignore case w/wildcard
  219.   b  Show data blks      t  Sort by date        N <name> Show newer than
  220.   c  Show filenotes      u  Usage  [also -?]        O <name> Show older than
  221.   d  Show dirs only      v  Vari col short list    P  Show full pathnames
  222.   e  Execute bit is "e"   x <pat> Exclude files     Q  Requesters enabled
  223.   f  Show files only      z  Override blk calc        R  Recursive listing
  224.   h  Show hidden files      A  Show all  [= -ahi]     S  Show dirs first
  225.   i  Show *.info files      B <blk> Force blk size    T  Totals for all entries
  226.   k  Sort by disk key      C  Single column list     V  Show rel pathnames
  227.   l  Long listing      D  Show dirs last        W  No contents (wild dir)
  228.   m  Mixed case output      E  No ANSI escape codes   X <wide> Set output cols
  229.   n  No sort          G  No subdir totals        Y <high> Set output rows
  230.   o  Old long list fmt      H  No headings        Z  Force ANSI sequences
  231.   p  Append "/" to dirs   I  No page prompts       0-6 Date format (new long)
  232.   q  Quit on not found      K  Show disk keys        -  Next arg is filename
  233.   r  Reverse sort      L <n> Limited recursion
  234.   F <format> Format output [-o fmt] (default: "%p %d %t %4b %8s %n\n")
  235.  
  236.  
  237.  
  238. Tech Notes:
  239.  
  240.     o  This version of "ls" was compiled/assembled using Lattice v5.05, with
  241.        optimization on.  See the Makefile and Linkfile for details.  Also
  242.        note that to use the source level debugger "cpr", you need to use one
  243.        of the commented out CFLAG strings in the Makefile with -d3, as well
  244.        as uncommenting the ADDSYM statement in the Linkfile.
  245.  
  246.     o  The file "mycres.o" is included, as I couldn't get "mycres.a" to
  247.        assemble ... no includes called "exec/funcdef.i" anywhere I could find,
  248.        etc.  I didn't have a real reason to muck with that code, so I didn't
  249.        pursue the matter.  The "mycres.o" file is from the v3.1 distribution,
  250.        and works fine (except when you try using getenv() ...).
  251.  
  252.     o  My enhancements to "ls" have evolved bit-by-bit over a period of about
  253.        a year.    Consequently, the code is somewhat less than "pristine".  I'm
  254.        sure it can be cleaned up a bit, though I tried to keep my changes from
  255.        getting too ugly.  Also, I've tried to more or less stay with Justin's
  256.        coding style, but I know that hasn't been completely successful either.
  257.        Anyway, you've been warned;  if you go reading the code, send flames
  258.        to /dev/null ... :-)
  259.  
  260.  
  261.  
  262. Revision History:
  263.  
  264.     Kim E. DeVaughn
  265.  
  266.     v4.0k  May 11, 1990  Pretty much completely revised the output formats.
  267.              Much more like UNIX's "ls" in its output, options,
  268.              etc.  Several bugs fixed.  Many new options.
  269.  
  270.     Justin V. McCormick
  271.  
  272.     v3.1  July 29, 1989  Bug fixes, new output width and height options.
  273.     v3.0  July 25, 1989  Instant sorting, best-fit output, new features.
  274.     v2.2  December 1988  Fixed status return and multiple wildcard pathnames.
  275.     v2.1  December 1988  Minor size reduction, fixed a few bugs from 2.0.
  276.     v2.0  November 1988  Revised for Lattice 5.0 and made 1.3 compatible.
  277.     v1.0    August 1986  Written from scratch, my first Amiga project.
  278.  
  279.  
  280.  
  281. Acknowledgements, Etc:
  282.  
  283. First, let me thank Justin McCormick for providing "ls" v3.1, and the very
  284. good algorithms from which I was able to build upon.  His inline sorting in
  285. particular made his version the one I chose to enhance because of it's speed.
  286.  
  287. A very excellent job, and my sincere thanks go to him for a job well done!
  288.  
  289. Second, let me thank Tom Rokicki for the "date" algorithm I used, and to
  290. Rob Peck for publishing it in his excellent book, "Programmer's Guide to the
  291. Amiga" (Sybex).  Both of these people have contributed much to the Amiga
  292. development community!
  293.  
  294. Third, I want to thank Matt Dillon for providing his fine DME editor, and
  295. many, *many* examples of how to program the Amiga.  If you ever need to know
  296. how to do something, take a look a Matt's code ... chances are he's done it,
  297. and in a lean, mean, fast way!
  298.  
  299.  
  300. Finally, I want to mention that this version of "ls" is copyrighted, whereas
  301. Justin's previous versions were explicitly "public domain".  Specifically, I
  302. am copyrighting this version of the executable "ls", the "ls.c" and "ls.h"
  303. source files, and the "ls.doc" and "README" files.
  304.  
  305. This is completely legal, since the base version I used had been declared to
  306. be in the "public domain".  I feel totally justified in doing so due to the
  307. extensive changes that I've made.
  308.  
  309. You'll note, if you read the "License", that I'm not trying to restrict the
  310. use or redistribution of this version of "ls", other than to insure that it
  311. isn't used by anyone to make money out of, myself included.  In particular,
  312. certain "diskzines" seem to be unscrupulously "raiding" the freely redistrib-
  313. utable software base lately, in an attempt to help sell their disk/magazines.
  314.  
  315. Most of the ones I've seen are *trash*, and the prices they charge are a bit
  316. outrageous, considering what they provide.  I do not wish to help them.  Not
  317. even in a slight way.
  318.  
  319. Anyway, I hope nobody has a big problem with this.  If you do, lemee hear
  320. from you.
  321.  
  322.  
  323.  
  324. The Future:
  325.  
  326. There will definitely be at least one more release of my version of "ls".  It
  327. will address those items mentioned in the "What's Not Done" and "Known Bugs"
  328. sections above.  In particular, it will support AmigaOS 2.0's enhancements,
  329. such as links.    Given 2.0's probable availability, I doubt this will happen
  330. much before the end of 1990.  We shall see.
  331.  
  332. In the meantime, let me hear from you if there are things you like (or don't).
  333. And especially if you find any bugs, "features", or anomalies.  And if (God
  334. forbid), there's a useful option I've managed to overlook, don't hesitate to
  335. put in a request ... there are still a few option flags left ... :-)
  336.  
  337. In addition to my electronic addresses (see signature below), I can be
  338. reached at:
  339.  
  340.     Kim E. DeVaughn
  341.     750 Sylvan Av,  #32
  342.     Mt. View, CA  94041
  343.  
  344. However, email to my USENET/UUCP address is probably the surest way to get
  345. in touch with me, and should be used if at all possible.
  346.  
  347.  
  348. /kim   /\oo/\
  349.  
  350. --
  351. UUCP:  kim@uts.amdahl.com
  352.   or:  {sun,decwrl,hplabs,pyramid,uunet,oliveb,ames}!amdahl!kim
  353. DDD:   408-746-8462
  354. USPS:  Amdahl Corp.  M/S 249,  1250 E. Arques Av,  Sunnyvale, CA 94086
  355. BIX:   kdevaughn     GEnie:   K.DEVAUGHN     CIS:   76535,25
  356.