tools/mpack-1.6/README.unix

                    mpack/munpack version 1.6 for unix

Mpack and munpack are utilities for encoding and decoding
(respectively) binary files in MIME (Multipurpose Internet Mail
Extensions) format mail messages.  For compatibility with older forms
of transferring binary files, the munpack program can also decode
messages in split-uuencoded format.  The Macintosh version can also
decode messages in split-BinHex format.

The canonical FTP site for this software is ftp.andrew.cmu.edu:pub/mpack/
Binaries are no longer provided. The pc, os2, amiga and archimedes ports
have been removed. The mac version probably doesn't compile anymore, but
is still included (MacOS X users can use the unix version...)

This MIME implementation is intended to be as simple and portable as
possible.  For a slightly more sophisticated MIME implementation, see
the program MetaMail, available via anonymous FTP to
thumper.bellcore.com, in directory pub/nsb


Decoding MIME messages:

First, you have to compile the munpack program.  See the instructions
in the section "Compilation" below.  If, after reading the
instructions, you are still unsure as to how to compile munpack,
please try to find someone locally to help you.

To decode a MIME message, first save it to a text file.  If possible,
save it with all headers included.  Munpack can decode some MIME files
when the headers are missing or incomplete, other files it cannot
decode without having the information in the headers.  In general,
messages which have a statement at the beginning that they are in MIME
format can be decoded without the headers.  Messages which have been
split into multiple parts generally require all headers in order to be
reassembled and decoded.

Some LAN-based mail systems and some mail providers (including America
Online, as of the writing of this document) place the mail headers at
the bottom of the message, instead of at the top of the message.  If
you are having problems decoding a MIME message on such a system, you
need to convert the mail back into the standard format by removing the
system's nonstandard headers and moving the standard Internet headers
to the top of the message (separated from the message body with a
blank line).

There must be exactly one message per file.  Munpack cannot deal with
multiple messages in a single file, to decode things correctly it must
know when one message ends and the next one begins.

To decode a message, run the command:

        munpack file

where "file" is the name of the file containing the message.  More than
one filename may be specified, munpack will try to decode the message in
each file.  For more information on ways to run munpack, see the section
"Using munpack" below.


Reporting bugs:

Bugs and comments should be reported to mpack-bugs@andrew.cmu.edu.
When reporting bugs or other problems, please include the following
information:

  * The version number of Mpack
  * The platform (Unix, PC, OS/2, Mac, Amiga, Archimedes)
  * The EXACT output of any unsuccessful attempts.
  * If having a problem decoding, the first couple of lines
    of the input file.


Compilation:

Mpack uses autoconf and automake on unix.
refer to INSTALL for more information

Using mpack:

Mpack is used to encode a file into one or more MIME format messages.
The program is invoked with:

        mpack [options] -o outputfile file

or 

        mpack [options] file address...

or

        mpack [options] -n newsgroups file

Where "[options]" is one or more optional switches described below.
"-o outputfile" is also described below. "file" is the name of the
file to encode, "address..." is one or more e-mail address to mail the
resulting messages to and "newsgroups" is a comma-separated list of
newsgroups to post the resulting messages to.

The possible options are:

     -s subject
          Set the Subject header field to Subject.   By default,
          mpack will prompt for the contents of the subject
          header.

     -d descriptionfile
          Include the contents of the file descriptionfile in an
          introductory section at the beginning of the first
          generated message.

     -m maxsize
          Split the message (if necessary) into partial messages,
          each not exceeding maxsize characters.  The default
          limit is the value of the SPLITSIZE environment 
          variable, or no limit if the environment variable
          does not exist.  Specifying a maxsize of 0 means there
          is no limit to the size of the generated message.

     -c content-type
          Label the included file as being of MIME type
          content-type, which must be a subtype of application,
          audio, image, or video.  If this switch is not given,
          mpack examines the file to determine its type.

     -o outputfile
          Write the generated message to the file outputfile.  If
          the message has to be split, the partial messages will
          instead be written to the files outputfile.01,
          outputfile.02, etc.

The environment variables which control mpack's behavior are:

     SPLITSIZE
          Default value of the -m switch.  Default "0".

     TMPDIR
          Directory to store temporary files.  Default "/tmp".


Using munpack:

Munpack is used to decode one or more messages in MIME or
split-uuencoded format and extract the embedded files.  The program is
invoked with:

        munpack [options] filename...

which reads the messages in the files "filename...".  Munpack may also
be invoked with just:

        munpack [options]

which reads a message from the standard input.

If the message suggests a file name to use for the imbedded part, that
name is cleaned of potential problem characters and used for the
output file.  If the suggested filename includes subdirectories, they
will be created as necessary.  If the message does not suggest a file
name, the names "part1", "part2", etc are used in sequence.

If the imbedded part was preceded with textual information, that
information is also written to a file. The file is named the same as
the imbedded part, with any filename extension replaced with
".desc"

The possible options are:

     -f
          Forces the overwriting of existing files.  If a message
          suggests a file name of an existing file, the file will be
          overwritten.  Without this flag, munpack appends ".1", ".2",
          etc to find a nonexistent file.

     -t
          Also unpack the text parts of multipart messages to files.
          By default, text parts that do not have a filename parameter
          do not get unpacked.

     -q
          Be quiet--suppress messages about saving partial messages.

     -C directory
          Change the current directory to "directory" before reading
          any files.  This is useful when invoking munpack
          from a mail or news reader.

The environment variables which control munpack's behavior are:

     TMPDIR
          Root of directory to store partial messages awaiting 
          reassembly.  Default is "/usr/tmp".   Partial messages
          are stored in subdirectories of $TMPDIR/m-prts-$USER/


Acknowledgements:

Written by John G. Myers, jgm+@cmu.edu

The mac version was written by Christopher J. Newman, chrisn+@cmu.edu

Send all bug reports to mpack-bugs@andrew.cmu.edu 

Thanks to Nathaniel Borenstein for testing early versions of mpack and
for making many helpful suggestions.


PGP signature:

The mpack 1.6 distribution is not pgp signed.

Legalese:

(C) Copyright 1993,1994 by Carnegie Mellon University
All Rights Reserved.

Permission to use, copy, modify, distribute, and sell this software
and its documentation for any purpose is hereby granted without fee,
provided that the above copyright notice appear in all copies and that
both that copyright notice and this permission notice appear in
supporting documentation, and that the name of Carnegie Mellon
University not be used in advertising or publicity pertaining to
distribution of the software without specific, written prior
permission.  Carnegie Mellon University makes no representations about
the suitability of this software for any purpose.  It is provided "as
is" without express or implied warranty.

CARNEGIE MELLON UNIVERSITY DISCLAIMS ALL WARRANTIES WITH REGARD TO
THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
AND FITNESS, IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY BE LIABLE
FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING
OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
SOFTWARE.

Portions of this software are derived from code written by Bell
Communications Research, Inc. (Bellcore) and by RSA Data Security,
Inc. and bear similar copyrights and disclaimers of warranty.
1	edhill	1.1	mpack/munpack version 1.6 for unix
2
3			Mpack and munpack are utilities for encoding and decoding
4			(respectively) binary files in MIME (Multipurpose Internet Mail
5			Extensions) format mail messages. For compatibility with older forms
6			of transferring binary files, the munpack program can also decode
7			messages in split-uuencoded format. The Macintosh version can also
8			decode messages in split-BinHex format.
9
10			The canonical FTP site for this software is ftp.andrew.cmu.edu:pub/mpack/
11			Binaries are no longer provided. The pc, os2, amiga and archimedes ports
12			have been removed. The mac version probably doesn't compile anymore, but
13			is still included (MacOS X users can use the unix version...)
14
15			This MIME implementation is intended to be as simple and portable as
16			possible. For a slightly more sophisticated MIME implementation, see
17			the program MetaMail, available via anonymous FTP to
18			thumper.bellcore.com, in directory pub/nsb
19
20
21			Decoding MIME messages:
22
23			First, you have to compile the munpack program. See the instructions
24			in the section "Compilation" below. If, after reading the
25			instructions, you are still unsure as to how to compile munpack,
26			please try to find someone locally to help you.
27
28			To decode a MIME message, first save it to a text file. If possible,
29			save it with all headers included. Munpack can decode some MIME files
30			when the headers are missing or incomplete, other files it cannot
31			decode without having the information in the headers. In general,
32			messages which have a statement at the beginning that they are in MIME
33			format can be decoded without the headers. Messages which have been
34			split into multiple parts generally require all headers in order to be
35			reassembled and decoded.
36
37			Some LAN-based mail systems and some mail providers (including America
38			Online, as of the writing of this document) place the mail headers at
39			the bottom of the message, instead of at the top of the message. If
40			you are having problems decoding a MIME message on such a system, you
41			need to convert the mail back into the standard format by removing the
42			system's nonstandard headers and moving the standard Internet headers
43			to the top of the message (separated from the message body with a
44			blank line).
45
46			There must be exactly one message per file. Munpack cannot deal with
47			multiple messages in a single file, to decode things correctly it must
48			know when one message ends and the next one begins.
49
50			To decode a message, run the command:
51
52			munpack file
53
54			where "file" is the name of the file containing the message. More than
55			one filename may be specified, munpack will try to decode the message in
56			each file. For more information on ways to run munpack, see the section
57			"Using munpack" below.
58
59
60			Reporting bugs:
61
62			Bugs and comments should be reported to mpack-bugs@andrew.cmu.edu.
63			When reporting bugs or other problems, please include the following
64			information:
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
73			Compilation:
74
75			Mpack uses autoconf and automake on unix.
76			refer to INSTALL for more information
77
78			Using mpack:
79
80			Mpack is used to encode a file into one or more MIME format messages.
81			The program is invoked with:
82
83			mpack [options] -o outputfile file
84
85			or
86
87			mpack [options] file address...
88
89			or
90
91			mpack [options] -n newsgroups file
92
93			Where "[options]" is one or more optional switches described below.
94			"-o outputfile" is also described below. "file" is the name of the
95			file to encode, "address..." is one or more e-mail address to mail the
96			resulting messages to and "newsgroups" is a comma-separated list of
97			newsgroups to post the resulting messages to.
98
99			The 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
131			The 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
140			Using munpack:
141
142			Munpack is used to decode one or more messages in MIME or
143			split-uuencoded format and extract the embedded files. The program is
144			invoked with:
145
146			munpack [options] filename...
147
148			which reads the messages in the files "filename...". Munpack may also
149			be invoked with just:
150
151			munpack [options]
152
153			which reads a message from the standard input.
154
155			If the message suggests a file name to use for the imbedded part, that
156			name is cleaned of potential problem characters and used for the
157			output file. If the suggested filename includes subdirectories, they
158			will be created as necessary. If the message does not suggest a file
159			name, the names "part1", "part2", etc are used in sequence.
160
161			If the imbedded part was preceded with textual information, that
162			information is also written to a file. The file is named the same as
163			the imbedded part, with any filename extension replaced with
164			".desc"
165
166			The 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
187			The environment variables which control munpack's behavior are:
188
189			TMPDIR
190			Root of directory to store partial messages awaiting
191	jmc	1.3	reassembly. Default is "/usr/tmp". Partial messages
192	edhill	1.1	are stored in subdirectories of $TMPDIR/m-prts-$USER/
193
194
195			Acknowledgements:
196
197			Written by John G. Myers, jgm+@cmu.edu
198
199			The mac version was written by Christopher J. Newman, chrisn+@cmu.edu
200
201			Send all bug reports to mpack-bugs@andrew.cmu.edu
202
203			Thanks to Nathaniel Borenstein for testing early versions of mpack and
204			for making many helpful suggestions.
205
206
207			PGP signature:
208
209			The mpack 1.6 distribution is not pgp signed.
210
211			Legalese:
212
213			(C) Copyright 1993,1994 by Carnegie Mellon University
214			All Rights Reserved.
215
216			Permission to use, copy, modify, distribute, and sell this software
217			and its documentation for any purpose is hereby granted without fee,
218			provided that the above copyright notice appear in all copies and that
219			both that copyright notice and this permission notice appear in
220			supporting documentation, and that the name of Carnegie Mellon
221			University not be used in advertising or publicity pertaining to
222			distribution of the software without specific, written prior
223			permission. Carnegie Mellon University makes no representations about
224			the suitability of this software for any purpose. It is provided "as
225			is" without express or implied warranty.
226
227			CARNEGIE MELLON UNIVERSITY DISCLAIMS ALL WARRANTIES WITH REGARD TO
228			THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
229			AND FITNESS, IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY BE LIABLE
230			FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
231			WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
232			AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING
233			OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
234			SOFTWARE.
235
236			Portions of this software are derived from code written by Bell
237			Communications Research, Inc. (Bellcore) and by RSA Data Security,
238			Inc. and bear similar copyrights and disclaimers of warranty.