home *** CD-ROM | disk | FTP | other *** search
/ Usenet 1994 October / usenetsourcesnewsgroupsinfomagicoctober1994disk2.iso / misc / volume7 / nstrings.bsd / README < prev    next >
Encoding:
Text File  |  1989-06-03  |  7.4 KB  |  209 lines
  1. 1.) What do we have here?
  2.  
  3. This is the README file for 'strings'. 'strings' is a rewrite
  4. and replacement for the 4BSD program of the same name.
  5. 'strings' looks for sequences of printable characters in a file and
  6. outputs them.
  7.  
  8. Current version is 1.6.9.
  9.  
  10. (To get best results when reading these files, use an option in your
  11.  favourite editor to expand a TAB to 4 SPACEs. E.g. in vi it is
  12.  "set tabstop=4")
  13.  
  14. You should have the files:
  15.     README        - this file
  16.     COPYING        - Copyright Notice
  17.     Makefile    - Makefile
  18.     strings.h
  19.     config.h
  20.     tune.h
  21.     strings.c    - the main source
  22.     limits.c    - the UNIX (trademark of AT&T) specific stuff to identify
  23.                   an initialized data segment
  24.     output.c    - output routines
  25.     test_input    - a file containing the 2 characters the original strings
  26.                   stumbled over. Unpack it with atob.
  27.     strings.1    - manual page.
  28.     strings.txt - manual page without nroff sequences
  29.  
  30. 2.) How to build strings.
  31.  
  32. Now that you have strings you will want to build it.
  33. The program is shipped with UFLAGS undefined (see below for an explanation).
  34. On UNIX (trademark of AT&T) systems, you should be able to build the
  35. program by just typing "make". On non-UNIX systems you might have problems.
  36.  
  37. a.) edit Makefile. If you want to play it safe, set UFLAGS=-DSAFETY_FIRST.
  38.     strings should now compile without any problems.
  39.     You won't get the UNIX specific stuff: the program does not
  40.     try to identify the initialized data segment.
  41.  
  42. b.) If you don't want to play it safe, but rather you want to configure
  43.     strings to your system, take a look at config first. There is a
  44.     list of systems. If one of these is yours, edit Makefile and
  45.     set UFLAGS to nothing. When compiling the defines for the system
  46.     are used.
  47.     WARNING: some things may differ between different versions of the
  48.     same system. On some machines there is no easy way to distinguish
  49.     between such versions.
  50.     If you were wrong, and the system you are using is not in the
  51.     list of known symbols, the minimal defaults, like in a.) will be
  52.     used.
  53.  
  54. c.) You want to configure strings, and your system is not in the list
  55.     of known systems.
  56.     Edit Makefile and set UFLAGS=-DUSE_USER_DEFINES.
  57.     Edit tune.h and set things up for your system. The variables are
  58.     commented.
  59.  
  60. There are 3 header files. The inclusion works like this.
  61. (you can skip this)
  62.  
  63.         (reading strings.h)
  64.                |
  65.                v
  66.         (including config.h)
  67.                |
  68.                v
  69.     <----- is SAFETY_FIRST defined?
  70.     |          |
  71.     |          | -
  72.     |          v                      +
  73.     |  is USE_USER_DEFINES defined? ---->use stuff from tune.h ---> continue
  74.     |          |
  75.     |          | -
  76.     |          v
  77.     |      is this machine 1 ?
  78.     |          |
  79.     |          | -
  80.     |          v
  81.     |      is this machine 2 ?
  82.     |          |
  83.     |          | -
  84.     |          v
  85.     |         ...
  86.     |          |
  87.     |          | -
  88.     v          v
  89.     use safe defaults
  90.     |
  91.     v
  92.     continue
  93.  
  94. The program, or rather the headerfiles know about the following machines:
  95.  
  96. - VAX 11/780 (4.3 BSD) by "unix" and "vax" and not "ultrix"
  97. - SIEMENS PC-MX2 (SINIX v2.1) by "nsc3200" and "sinix" and "ns16000"
  98. - Sun 3/260 (SunOS 3.5) by "unix" and "sun" and "mc68020"
  99. - VAX 6800 (Ultrix 2.1) by "unix" and "ultrix" and "bsd4_2"    
  100. - uVAX (VMS 5.1) by "vms" and "vax"
  101.  
  102. 3.) Why is this strings better than the standard one?
  103.  
  104.     a.) This version of strings is at least 4 times faster than the original
  105.         one. If the minimal string length is set to something else, it might
  106.         even be 10 times faster.
  107.     b.) The original one had several bugs.
  108.     c.) This one is public domain. You get source.
  109.  
  110.     ad a.)
  111.         Here are results of some tests:
  112.  
  113.         machine: PC-MX2,   OS: SINIX v2.1        file: /vmsinix    (289084)
  114.         old :        u    43.6        s    1.1            =    44.7
  115.         new :        u     3.8        s    2.3            =     6.1
  116.  
  117.         machine: VAX 11/780       OS: 4.3BSD        file: /vmunix    (329728)
  118.         old :        u    18.0        s    2.7            =    20.7
  119.         new :        u     1.5        s    0.9            =     2.4
  120.  
  121.         machine: SUN 3/260        OS: SunOS 3.5     file: /vmunix    (558359)
  122.         old :        u     6.5        s    0.6            =     7.1
  123.         new :        u     1.6        s    0.2            =     1.8
  124.  
  125.         machine: VAX 6800         OS: Ultrix 2.1    file: /vmunix    (662528)
  126.         old :        u     5.2        s    0.4            =     5.6
  127.         new :        u     0.6        s    0.0            =     0.6
  128.  
  129.         User, sys and total times in seconds.
  130.  
  131.     ad b.)
  132.         The original strings
  133.         - thinks control-L (0x0c) is a printable character
  134.         - under some circumstances thinks 0x80 is printable. In the
  135.           package there is a file, test_input. Unpack this file with
  136.           atob. The file now contains several lines of characters including
  137.           a line with control-L and one with a 0x80. The original strings
  138.           errs for both cases.
  139.         - did not get the start address of the initialized data right on
  140.           some systems.
  141.         - had problems when dealing with the standard input.
  142.         The first two bugs have been found on 43BSD, SunOS and ULTRIX, the
  143.         third only on MX2 SINIX v2.1.
  144.  
  145. 4.) What about bugs?
  146.  
  147.     If you find bugs, tell me. If you fixed them or if you made an
  148.     extension which really is one, drop me a note.
  149.  
  150. 5.) Notes
  151.  
  152.     This program is about 7 times faster than the orignal one.
  153.     There are two reasons for this:
  154.     - It does not use fgetc/fputc to get or put characters, but
  155.       reads characters in blocks. It does not copy them but rather moves
  156.       pointers around on the input buffer. There is no
  157.       procedure call needed to get at each character.
  158.       When a sequence is found, it is put into the output buffer in one
  159.       block, thus there is no need, like in fputc, to check for possible
  160.       overflow for each character.
  161.     - When the program searches for a sequence of printable characters
  162.       it only examines each min_str_len character instead of each one.
  163.        min_str_len defaults to 4 and can be set with command line option
  164.       like "strings -3".
  165.  
  166.     It can be sped up some more, but then it would be difficult to port
  167.     it to different systems.
  168.     Example:
  169.     Currently the program takes 6.0 seconds on MX2 for /vmsinix.
  170.     The improved version only needs 5.5 seconds. It is also much smaller:
  171.     6976 bytes compared to 10596.
  172.     Ways to improve the program:
  173.     - On some machines another method to test whether a character is printable
  174.       will be faster. Now the program uses an array (isp), uses a character
  175.       cast to a (signed) integer as index into this array (isp_mid is the
  176.       base from which offsets are computed).
  177.       On MX2, and, if I believe my tests, on VAX, it is faster, to use
  178.       unsigned characters as index into this array.
  179.       If you want to play around with this, just change CHAR_TYPE to
  180.       'unsigned byte' and define the macro IS_PRINTABLE accordingly to
  181.       '(isp[c])'
  182.     - It makes a difference (although a small one), what basic type you
  183.       choose for the isp array. On MX2 short is best, but char is nearly
  184.       as good.
  185.     - You can make it smaller. The program does not need stdio. But
  186.       exit normally closes file descriptors, and therefore includes a
  187.       large part of the stdio stuff. Well, about 4 K on some systems.
  188.       If you know what your exit does, you can substitute a suitable
  189.       routine of your own. E.g. on MX2, exit calls _cleanup, which
  190.       only closes all open file descriptors. As I know that only the
  191.       standard descriptors are open at the end of the program, I can
  192.       write a _cleanup which only does a close on 0, 1, and 2.
  193.  
  194.     The savings that you get are almost invisible, they are not easily
  195.     portable, but rather require a certain amount of research on part
  196.     of the person doing the  porting. I chose not to fit the programs with
  197.     options to adjust these things.
  198.  
  199.     There are still some DEBUG statements in the code. You get them
  200.     if you set DEBUGFLAGS=-DDEBUG.
  201.  
  202. 6.) Status
  203.  
  204.     This program is placed into the public domain.
  205.     The Copyright Notice in COPYING applies.
  206.  
  207. Absorb, apply and enjoy,
  208.         Michael Greim
  209.