1                    mpack/munpack version 1.6 for unix
2
3Mpack and munpack are utilities for encoding and decoding
4(respectively) binary files in MIME (Multipurpose Internet Mail
5Extensions) format mail messages.  For compatibility with older forms
6of transferring binary files, the munpack program can also decode
7messages in split-uuencoded format.  The Macintosh version can also
8decode messages in split-BinHex format.
9
10The canonical FTP site for this software is ftp.andrew.cmu.edu:pub/mpack/
11Binaries are no longer provided. The pc, os2, amiga and archimedes ports
12have been removed. The mac version probably doesn't compile anymore, but
13is still included (MacOS X users can use the unix version...)
14
15This MIME implementation is intended to be as simple and portable as
16possible.  For a slightly more sophisticated MIME implementation, see
17the program MetaMail, available via anonymous FTP to
18thumper.bellcore.com, in directory pub/nsb
19
20
21Decoding MIME messages:
22
23First, you have to compile the munpack program.  See the instructions
24in the section "Compilation" below.  If, after reading the
25instructions, you are still unsure as to how to compile munpack,
26please try to find someone locally to help you.
27
28To decode a MIME message, first save it to a text file.  If possible,
29save it with all headers included.  Munpack can decode some MIME files
30when the headers are missing or incomplete, other files it cannot
31decode without having the information in the headers.  In general,
32messages which have a statement at the beginning that they are in MIME
33format can be decoded without the headers.  Messages which have been
34split into multiple parts generally require all headers in order to be
35reassembled and decoded.
36
37Some LAN-based mail systems and some mail providers (including America
38Online, as of the writing of this document) place the mail headers at
39the bottom of the message, instead of at the top of the message.  If
40you are having problems decoding a MIME message on such a system, you
41need to convert the mail back into the standard format by removing the
42system's nonstandard headers and moving the standard Internet headers
43to the top of the message (separated from the message body with a
44blank line).
45
46There must be exactly one message per file.  Munpack cannot deal with
47multiple messages in a single file, to decode things correctly it must
48know when one message ends and the next one begins.
49
50To decode a message, run the command:
51
52	munpack file
53
54where "file" is the name of the file containing the message.  More than
55one filename may be specified, munpack will try to decode the message in
56each file.  For more information on ways to run munpack, see the section
57"Using munpack" below.
58
59
60Reporting bugs:
61
62Bugs and comments should be reported to mpack-bugs@andrew.cmu.edu.
63When reporting bugs or other problems, please include the following
64information:
65
66  * The version number of Mpack
67  * The platform (Unix, PC, OS/2, Mac, Amiga, Archimedes)
68  * The EXACT output of any unsuccessful attempts.
69  * If having a problem decoding, the first couple of lines
70    of the input file.
71
72
73Compilation:
74
75Mpack uses autoconf and automake on unix.
76refer to INSTALL for more information
77
78Using mpack:
79
80Mpack is used to encode a file into one or more MIME format messages.
81The program is invoked with:
82
83	mpack [options] -o outputfile file
84
85or
86
87	mpack [options] file address...
88
89or
90
91	mpack [options] -n newsgroups file
92
93Where "[options]" is one or more optional switches described below.
94"-o outputfile" is also described below. "file" is the name of the
95file to encode, "address..." is one or more e-mail address to mail the
96resulting messages to and "newsgroups" is a comma-separated list of
97newsgroups to post the resulting messages to.
98
99The possible options are:
100
101     -s subject
102          Set the Subject header field to Subject.   By default,
103          mpack will prompt for the contents of the subject
104          header.
105
106     -d descriptionfile
107          Include the contents of the file descriptionfile in an
108          introductory section at the beginning of the first
109          generated message.
110
111     -m maxsize
112          Split the message (if necessary) into partial messages,
113          each not exceeding maxsize characters.  The default
114          limit is the value of the SPLITSIZE environment
115	  variable, or no limit if the environment variable
116          does not exist.  Specifying a maxsize of 0 means there
117          is no limit to the size of the generated message.
118
119     -c content-type
120          Label the included file as being of MIME type
121          content-type, which must be a subtype of application,
122          audio, image, or video.  If this switch is not given,
123          mpack examines the file to determine its type.
124
125     -o outputfile
126          Write the generated message to the file outputfile.  If
127          the message has to be split, the partial messages will
128          instead be written to the files outputfile.01,
129          outputfile.02, etc.
130
131The environment variables which control mpack's behavior are:
132
133     SPLITSIZE
134          Default value of the -m switch.  Default "0".
135
136     TMPDIR
137	  Directory to store temporary files.  Default "/tmp".
138
139
140Using munpack:
141
142Munpack is used to decode one or more messages in MIME or
143split-uuencoded format and extract the embedded files.  The program is
144invoked with:
145
146	munpack [options] filename...
147
148which reads the messages in the files "filename...".  Munpack may also
149be invoked with just:
150
151	munpack [options]
152
153which reads a message from the standard input.
154
155If the message suggests a file name to use for the imbedded part, that
156name is cleaned of potential problem characters and used for the
157output file.  If the suggested filename includes subdirectories, they
158will be created as necessary.  If the message does not suggest a file
159name, the names "part1", "part2", etc are used in sequence.
160
161If the imbedded part was preceded with textual information, that
162information is also written to a file. The file is named the same as
163the imbedded part, with any filename extension replaced with
164".desc"
165
166The possible options are:
167
168     -f
169          Forces the overwriting of existing files.  If a message
170          suggests a file name of an existing file, the file will be
171          overwritten.  Without this flag, munpack appends ".1", ".2",
172          etc to find a nonexistent file.
173
174     -t
175	  Also unpack the text parts of multipart messages to files.
176	  By default, text parts that do not have a filename parameter
177	  do not get unpacked.
178
179     -q
180          Be quiet--suppress messages about saving partial messages.
181
182     -C directory
183          Change the current directory to "directory" before reading
184          any files.  This is useful when invoking munpack
185          from a mail or news reader.
186
187The environment variables which control munpack's behavior are:
188
189     TMPDIR
190          Root of directory to store partial messages awaiting
191          reassembly.  Default is "/tmp".   Partial messages
192	  are stored in subdirectories of $TMPDIR/m-prts-$USER/
193
194
195Acknowledgements:
196
197Written by John G. Myers, jgm+@cmu.edu
198
199The mac version was written by Christopher J. Newman, chrisn+@cmu.edu
200
201Send all bug reports to mpack-bugs@andrew.cmu.edu
202
203Thanks to Nathaniel Borenstein for testing early versions of mpack and
204for making many helpful suggestions.
205
206
207PGP signature:
208
209The mpack 1.6 distribution is not pgp signed.
210
211Legalese:
212
213(C) Copyright 1993,1994 by Carnegie Mellon University
214All Rights Reserved.
215
216Permission to use, copy, modify, distribute, and sell this software
217and its documentation for any purpose is hereby granted without fee,
218provided that the above copyright notice appear in all copies and that
219both that copyright notice and this permission notice appear in
220supporting documentation, and that the name of Carnegie Mellon
221University not be used in advertising or publicity pertaining to
222distribution of the software without specific, written prior
223permission.  Carnegie Mellon University makes no representations about
224the suitability of this software for any purpose.  It is provided "as
225is" without express or implied warranty.
226
227CARNEGIE MELLON UNIVERSITY DISCLAIMS ALL WARRANTIES WITH REGARD TO
228THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
229AND FITNESS, IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY BE LIABLE
230FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
231WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
232AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING
233OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
234SOFTWARE.
235
236Portions of this software are derived from code written by Bell
237Communications Research, Inc. (Bellcore) and by RSA Data Security,
238Inc. and bear similar copyrights and disclaimers of warranty.
239
240