home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 8 / FreshFishVol8-CD2.bin / bbs / util / uuinout-1.03.lha / uuInOut / uuOut.v1.03.doc < prev    next >
Text File  |  1993-12-16  |  12KB  |  293 lines
  1. $VER: uuOut.doc 1.03 (15.12.93)
  2.  
  3.            uuOut v1.03 by Nicolas Dade
  4.  
  5. uuOut version 1.03 is copyright 1993 by Nicolas Dade. All Rights
  6. Reserved. Permission is hereby granted for non-commercial
  7. duplication and distribution, and for distribution by BBSs which do
  8. not charge for downloads, and for distribution in disk collections
  9. which charge a nominal fee per disk. This is not shareware.
  10.  
  11. That out of the way, what is it?
  12.  
  13. It's a uudecoder to decode uuencoded text (an encoding scheme that
  14. is used to send binary files over links that only support textual
  15. characters---ie email and internet news)
  16.  
  17.  
  18. --Why is this decoder better than those already available?--
  19.  
  20. * It's very fast at decoding (and it uses a different, even faster
  21.   decode routine if a 68020 or higher is detected).
  22.   On top of that it uses a simplification of the Boyer-Moore search
  23.   algorithm when searching for 'begin' lines, so scanning files that
  24.   are largely not uuencoded-data for data is also very quick.
  25.   (It's 100% assembly)
  26.  
  27. * It sanity checks its input so that non-uuencoded data lines are
  28.   skipped over instead of being "decoded" and producing garbage.
  29.   Sanity checking includes checking trailing checksums, M's and X's,
  30.   and the 'size' line. Some sanity checking can be disabled in case
  31.   compatibility with the original uudecode is desired.
  32.  
  33. * It allows you to specify the output directory in which to place
  34.   the decoded file(s) so that they don't have to go to the
  35.   current directory, and paths in the encoded filenames can be
  36.   ignored or obeyed (needed dirs are created automatically)
  37.  
  38. * Output files have their protection flags set to reflect the
  39.   owner's rwx unix protection bits specified in the uuencoded
  40.   data.
  41.  
  42. * It will take its input from its standard input, as well as from
  43.   a file.
  44.  
  45. * It decodes all files encoded in its input, not just the first one.
  46.  
  47. * Partially complete files (missing data lines or missing 'end' lines)
  48.   don't mess up the other, complete, files.
  49.  
  50. * It does its own io buffering using user sizeable buffers, so
  51.   your harddrive won't be slowed by thrashing if uuOut's input
  52.   and output come from and go to that harddrive.
  53.  
  54. * It's pure and it's small---you can make it resident and it
  55.   won't cost you over 4K
  56.  
  57. * uuOut reports all errors and strange conditions with descriptive
  58.   error messages, and aborts if it is sent a break signal
  59.   (Control-C).
  60.  
  61.  
  62. --Requirements--:
  63.  
  64. WorkBench 2.04 or higher.
  65.  
  66.  
  67. --Use--:
  68.  
  69. the template for uuOut is: INFILE,OUTPATH,BUFSIZE/K/N,VERBOSE/S
  70.  
  71. INFILE....the file from which to read the uuencoded data. If no
  72.       INFILE is specified, standard input is used.
  73.  
  74. OUTPATH...a directory from which the uudecoded files's location is
  75.       based. Usually that means that the output files go in
  76.       OUTPATH, but if the output file's name contains a path
  77.       along with a filename (i.e. "dir1/dir2/filename") then
  78.       the uudecoded file will appear in OUTPATH/dir1/dir2/filename.
  79.       (the directories "dir1" and "dir2" are created if they do
  80.       not already exist)
  81.       If OUTPATH is not specified the current-directory is used
  82.       in its place.
  83.       If this directory does not exist it too will be created.
  84.  
  85. BUFSIZE...allows you to specify the size of the input and
  86.       output buffers uuOut should use in kilobytes. The default
  87.       is 32K which is a little small for a harddrive to
  88.       harddrive decode. Try 150K or higher, until the accesses
  89.       to the harddrive become a second or so apart. If there
  90.       isn't sufficient memory available to allocate buffers of
  91.       the specified size, uuOut keeps trying small and smaller
  92.       sizes (half as large each time) until the buffer would be
  93.       smaller than 1K, at which point uuOut gives up and aborts
  94.       with an error message explaining that there isn't enough
  95.       memory in the system for the buffers. Note that if you
  96.       don't have 2K free you've got more problems on your hands
  97.       than uuOut refusing to run. :)
  98.  
  99. USEBASENAME...instead of (if need be) creating directories and placing
  100.       the uudecoded files in those directories, all uudecoded files
  101.       are created in the current-directory (or OUTPATH if specified).
  102.       i.e. "begin 644 dir1/dir2/file" would be decoded into
  103.       <current-dir>/file or OUTPATH/file, instead of
  104.       <current-dir>/dir1/dir2/file or OUTPATH/dir1/dir2/file.
  105.  
  106. IGNORETERMINATION...ignores all data from the last of the data characters
  107.       to the EOL of each line. This is to be used only when not using
  108.       it causes bad checksum error messages but you think the data is
  109.       good. It makes uuOut act like the original unix uudecode, which
  110.       means that the data can be followed by anything, including
  111.       things the usual input-checking code doesn't know about.
  112.  
  113. VERBOSE...uuOut reports each step it takes to standard-error.
  114.  
  115.  
  116. --Examples--:
  117.  
  118. To decode any uuencoded files in the file "t:FreshEmail.txt" and
  119. create the paths+files starting from the "work:" directory
  120.  
  121.   uuOut t:FreshEmail.txt work:
  122.  
  123. and to use 150K io buffers instead of the default 32K when doing this
  124.  
  125.   uuOut t:FreshEmail.txt work: BUFSIZE=150
  126.  
  127. and to have all the files go in the work: directory and not some
  128. sub-directories of work:
  129.  
  130.   uuOut t:FreshEmail.txt work: BUFSIZE=150 USEBASENAME
  131.  
  132. To decode the standard input stream and create the output files
  133. in the current directory
  134.  
  135.   uuOut
  136.  
  137. (kind of easy, no?)
  138. And to decode the standard input stream and create the output
  139. files in "t:"
  140.  
  141.   uuOut OUTPATH=t:
  142.  
  143. just saying "uuOut t:" will not work because t: will be
  144. interpreted to be the name of the input file, and uuOut will then
  145. try to open and read from the "file" t:, find that it cannot, and
  146. abort with an error message.
  147.  
  148. Decoding data that is stored in multiple files can be done with
  149. the help of the C= join command: (BTW if you're just going to feed
  150. the data to uuOut then don't bother with multiple files, they just
  151. slow things down---instead create one giant file and feed it to uuOut)
  152.  
  153.   run join file1 file2 file3 ... to pipe:file
  154.   uuOut pipe:file
  155.  
  156. or, if you have set the __pchar local variable to | and have the
  157. pipe command installed, then it is easier to use
  158.  
  159.   join file1 file2 file3 ... to out: | uuOut
  160.  
  161. (yes, the C= shell can do nameless piping, it's just not documented.)
  162. Or if you have csh installed,
  163.  
  164.   cat file1 file2 file3 ... | uuOut
  165.  
  166. And as usual, to see the template
  167.  
  168.  uuOut ?
  169.  
  170. and to see the full built-in help and copyright text, give a
  171. second "?" at the prompt following the template.
  172.  
  173.  
  174. --Speed Comparisons--:
  175.  
  176. On a 7.14MHz NTSC 68000 based Amiga (ie A500, A1000 or A2000) using
  177. the command line "uuOut ram:440KByteFile ram:", decoding the
  178. 440Kbyte file which contains a 310 KByte uuencoded file:
  179.  
  180. using:      version:    takes:        speed:
  181. uuOut      1.03        5.7 secs       77Kb/s
  182. UUDecodeX 1.02           27.7 secs       16KB/s
  183. UUxT      2.2           41.3 secs       11Kb/s
  184. uudecode  ?**           64.3 secs    7Kb/s
  185.  
  186. ** by Mark Horton and Alan J. Rosenthal. I couldn't find any version
  187. information.
  188.  
  189. I don't have a 68020 Amiga handy, but on a 22MHz 68030 based
  190. A2000 the same commands took:
  191.  
  192. using:      version:    takes:        speed:
  193. uuOut      1.03        1.0 secs       440Kb/s
  194. UUDecodeX 1.02        4.7 secs    94KB/s
  195. UUxT      2.2        7.2 secs    61Kb/s
  196. uudecode   ?           10.0 secs    44Kb/s
  197.  
  198.  
  199. --Sanity Checking of Input--:
  200.  
  201. uuOut's input-checking keeps it from trying to decode lines that
  202. obviously aren't data lines, and it's difficult to fool, unlike a
  203. certain other uudecoder that advertises this feature. uuOut insists
  204. a data line contain only the characters 0x20 (space) through 0x40
  205. (backquote) inclusive (0x40 is considered equivalent to 0x20), and
  206. have the right number of characters (the first byte of a data line
  207. is a count). Furthermore the data line must end with (optionally)
  208. a checksum character, (optionally) an X or M, and then either a
  209. LF or a CR, and the checksum, if it is present, must be correct.
  210. (If a line looks good except that it's checksum is bad, uuOut
  211. ignores the data in the line, but warns you that a line that
  212. looked like data but had a bad checksum is being skipped.)
  213.  
  214. This means that mail and news header lines aren't considered data
  215. because the header names contain lowercase characters or, if they
  216. don't, rarely (that's the .1% of the time) contain the right
  217. number of characters. You _can_ 99.9% of the time pass mail or news