home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / uuencdec.zip / MANUAL next >
Text File  |  1987-08-26  |  7KB  |  182 lines
  1.                                UUENCODE, UUDECODE
  2.  
  3. Filters used to send binary documents via NetMail, by converting 3 binary bytes
  4. into 4 printable ASCII bytes.
  5.  
  6.  
  7. Unix Author:  Mark Horton
  8. MSDOS Author: Keith Gregory (complete rewrite)
  9.  
  10.  
  11. This program set was written to follow conventions established in the Unix
  12. community.
  13.  
  14. This source code/manual is hereby placed into the public domain by the author,
  15. who accepts no responsibility for anything that might happen to you or anyone
  16. else from its use (what do you expect for nothing, a RRRRRRubbber Biscuit?).
  17.  
  18. Redistibution of this program MUST include full source code and this manual.
  19. If you only receive the executables, then you should probably be wary (as a
  20. hint, the original sizes: UUENCODE = 18064, UUDECODE = 18160).
  21.  
  22. This code compiles with Lattice C, Version 3.1.  It has not been tested for
  23. compilability with any other compiler (but Turbo-C should work OK, as I use
  24. its reference manual for looking up system calls).
  25.  
  26.  
  27. *******************************************************************************
  28. *******************************************************************************
  29.  
  30.                                 Part I - Usage
  31.  
  32. -------------------------------------------------------------------------------
  33.  
  34. uuencode [-options] [inputfile]
  35.  
  36.  
  37. This program takes an optional input file, encodes it into printable ASCII
  38. characters, adds header information which is acceptable to Un*x versions, and
  39. outputs the encoded file to Standard Output.  If an input file is not specified
  40. then input will be taken from Standard Input, and the name "UUENCODE.000" will
  41. be stored in the encoded file.
  42.  
  43. One option is currently defined:
  44.  
  45.     -Mnnn   Specify file mode.
  46.             This is used for exchange with Un*x systems only, where the
  47.             user wants to specify permission codes for the destination.
  48.             Normally, files are stored with a permission code for User
  49.             Read/Write, Group Read, and nothing for World.  If the user
  50.             desires something different, then the desired protection code
  51.             should be specified as a three-digit octal number.
  52.  
  53.  
  54. -------------------------------------------------------------------------------
  55.  
  56. uudecode [inputfile]
  57.  
  58.  
  59. This program is the counterpart to UUENCODE.  It reads the input file, removes
  60. any header or trailer information (which would be added by some mail systems),
  61. and converts the encoded file back into binary.
  62.  
  63. The input file is optional.  If it exists, it will be used.  If it does not
  64. exist or is not specified, then input will be taken from Standard Input.  The
  65. name of the output file is encoded with the file's data.  If the output file
  66. already exists, then UUDECODE will not overwrite the existing file - it will
  67. abort. [Note - this may cause problems when reading files from Standard Input,
  68. where the original text is not retrievable].
  69.  
  70. *******************************************************************************
  71.  
  72.                       Part II - Bugs / Future Features
  73.  
  74. -------------------------------------------------------------------------------
  75.  
  76.     The Unix version of UUENCODE/UUDECODE allows a user to be specified with
  77.     the filename.  This is designed for use with mail systems, where the
  78.     reciever (UUDECODE) must place encoded files into their proper accounts.
  79.     Since MS-DOS doesn't have any idea of what a user is, this won't work.
  80.     If a file is specified in this format, the user portion will be removed.
  81.  
  82.     At this time, fill pathnames will not be used by either UUENCODE or
  83.     UUDECODE.  In a future release they will be.  Currently, UUENCODE will
  84.     trim any path specification from the name that is stored into the encoded
  85.     file - however the user may specify a complete path for file access.
  86.     UUDECODE will also trim pathnames for output - all output files will be
  87.     placed in the current directory (this may be used to get around the
  88.     problem mentioned above).  Note that UUDECODE will only trim Unix-style
  89.     pathnames (which use / instead of \).  Since UUENCODE does not store paths,
  90.     trimming DOS-style pathnames was not considered necessary.
  91.  
  92.     Currently, the mode stored bears no relationship to the DOS file, it is
  93.     strictly for Unix compatibility.  UUENCODE stores a likely mode (User Read/
  94.     Write, Group/World Read), and UUDECODE ignores the mode completely.  In a
  95.     future release, UUENCODE will store the file's current read/write status,
  96.     and UUDECODE will set the read/write status based on the Unix-style mode.
  97.  
  98.  
  99. *******************************************************************************
  100.  
  101.                                Part III - Format
  102.  
  103. -------------------------------------------------------------------------------
  104.  
  105. 1 - An encoded file is made up of the following parts
  106.  
  107.     __header_lines__
  108.  
  109.     begin _mode_ _name_
  110.  
  111.     _encoded_lines_
  112.  
  113.     end
  114.  
  115.     __trailer_lines__
  116.  
  117.  
  118.     ------------------------------------------------------------------------
  119.  
  120.     Header and trailer lines are optional - they may be tacked onto the file
  121.     by mail software.
  122.  
  123.     "begin" line contains the name of the destination file and its mode (in
  124.     octal).  If the filename starts with a tilde (~), it is composed of a
  125.     user/filename combination (in form "~user/filename"), and UUDECODE (on
  126.     Unix systems, at least) will place the file in the proper directory.
  127.  
  128.     Encoded lines are explained below.
  129.  
  130.     "end" line signifies the end of the encoded file.
  131.  
  132.  
  133.  
  134. 2 - Encoded lines contain a size byte, followed by data bytes.  All bytes are
  135.     encoded as printable ASCII characters.  This means that each byte may
  136.     contain no more than 6 bits of information.
  137.  
  138.         6_bit_value + ASC(' ') = 7_bit_value, printable ASCII
  139.  
  140.  
  141.  
  142. 3 - Since each encoded byte contains 6 bits of information, the file will grow,
  143.     since four 6-bit bytes are needed to contain the information from 3 8-bit
  144.     bytes.  The conversion is as follows:
  145.  
  146.     A = Input Byte #1
  147.     B = Input Byte #2
  148.     C = Input Byte #3
  149.     D = Output Byte #1
  150.     E = Output Byte #2
  151.     F = Output Byte #3
  152.     G = Output Byte #4
  153.  
  154.  
  155.     D = High order 6 bits of A in bits 0..5
  156.     E = Low  order 2 bits of A in bits 4..5
  157.         High order 4 bits of B in bits 0..3
  158.     F = Low  order 4 bits of B in bits 2..5
  159.         High order 2 bits of C in buts 0..1
  160.     G = Low  order 6 bits of C in bits 0..5
  161.  
  162.  
  163.  
  164. 4 - Sample Conversion
  165.  
  166.     Input Line -- "This is a test"
  167.  
  168.     Output Line - ".5&AI<R!I<R!A('1E<W0"
  169.  
  170.  
  171.     "."    - Length, 14  (32 + 14 = 46 = ".")
  172.     "5&AI" - "Thi"
  173.  
  174.              Bit Numbers:   76543210 76543210 76543210 76543210
  175.              Encoded Bits:  00110101 00100110 01000001 01001001
  176.              Convrtd Bits:  00010101 00000110 00100001 00101001
  177.              Decoded Bits:  01010100 01101000 01101001
  178.              Decoded Text:         T        h        i
  179.     .
  180.     .
  181.     .
  182.