Debian Codegraph @

upstream/debian-trixie/man1/makemime.1

raw
1 '\" t
2 .\"<!-- Copyright 2001-2007 Double Precision, Inc. See COPYING for -->
3 .\"<!-- distribution information. -->
4 .\" Title: makemime
5 .\" Author: Sam Varshavchik
6 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
7 .\" Date: 11/04/2020
8 .\" Manual: Double Precision, Inc.
9 .\" Source: Courier Mail Server
10 .\" Language: English
11 .\"
12 .TH "MAKEMIME" "1" "11/04/2020" "Courier Mail Server" "Double Precision, Inc\&."
13 .\" -----------------------------------------------------------------
14 .\" * Define some portability stuff
15 .\" -----------------------------------------------------------------
16 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
17 .\" http://bugs.debian.org/507673
18 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
19 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
20 .ie \n(.g .ds Aq \(aq
21 .el .ds Aq '
22 .\" -----------------------------------------------------------------
23 .\" * set default formatting
24 .\" -----------------------------------------------------------------
25 .\" disable hyphenation
26 .nh
27 .\" disable justification (adjust text to left margin only)
28 .ad l
29 .\" -----------------------------------------------------------------
30 .\" * MAIN CONTENT STARTS HERE *
31 .\" -----------------------------------------------------------------
32 .SH "NAME"
33 makemime \- Create MIME\-formatted messages
34 .SH "SYNOPSIS"
35 .HP \w'\fBmakemime\fR\ 'u
36 \fBmakemime\fR [\fIoptions\fR...]
37 .HP \w'\fBmakemime\fR\ 'u
38 \fBmakemime\fR [@\fIfilename\fR]
39 .SH "DESCRIPTION"
40 .PP
41 \fBmakemime\fR
42 creates MIME\-formatted messages of arbitrary complexity\&.
43 \fBmakemime\fR
44 reads one or more individual files, MIME\-encodes them, adds basic MIME headers, and adds any additional headers specified bye command line options\&. The result is saved to another file or standard output\&. Complex MIME\-formatted messages are created by piping together multiple instances of
45 \fBmakemime\fR\&. Advanced options direct
46 \fBmakemime\fR
47 to
48 \fBfork\fR() itself, and handle the details of setting up all the pipelines\&.
49 .PP
50 In most cases, options for
51 \fBmakemime\fR
52 come directly from the command line\&. @filename
53 reads the options from a file\&. "@&\fIn\fR" reads options from a pipe on file descriptor #\fIn\fR\&. "@\-" is a shortcut for "@&0", which reads options from standard input\&.
54 .PP
55 When options are read from a file or a pipe, each option must be on a line by itself\&. If an option requires an argument, the argument must follow on the next line\&.
56 .PP
57 For readability, leading whitespace is deleted when options are read from a file or a pipe\&. Empty lines are also ignored, as well as lines that begin with the \*(Aq#\*(Aq character\&.
58 .PP
59 Options and their arguments may contain characters that are special characters to the shell, such as \*(Aq(\*(Aq and \*(Aq)\*(Aq\&. These characters must be backslashed when specified on the command line, to avoid their special meaning to the shell\&. These characters MUST NOT be backslashed when options are read from a file or a pipe\&. Similarly, the contents of most headers nearly always include spaces\&. Therefore they must be quoted when specified on the command line\&. Header contents MUST NOT be quoted when options come from a file or a pipe\&.
60 .PP
61 \fBmakemime\fR
62 reads the content to be formatted as a MIME message from some other file\&. The files can also be a pipe\&. It is possible to supply both the options and a file from the same pipe, by terminating the options list with a line containing the single character "\-"\&. The remainder of the pipe will be available to be used as an input file (which must be explicitly specified by one of the options)\&. Of course, only one input file can come from a single pipe\&.
63 .SS "MIME overview"
64 .PP
65 A MIME\-formatted message contains one or several MIME sections\&. MIME headers specify how multiple MIME sections are to be interpreted as a whole (whether they are attached together; whether they are alternative representations of the same content; or something even more esoteric)\&. This manual page gives a very brief, terse, overview of basic MIME concepts\&. The description is biased towards describing the functionality of the
66 \fBmakemime\fR
67 utility\&. See
68 \m[blue]\fBRFC 2045\fR\m[]\&\s-2\u[1]\d\s+2,
69 \m[blue]\fBRFC 2046\fR\m[]\&\s-2\u[2]\d\s+2,
70 \m[blue]\fBRFC 2047\fR\m[]\&\s-2\u[3]\d\s+2,
71 \m[blue]\fBRFC 2048\fR\m[]\&\s-2\u[4]\d\s+2, and
72 \m[blue]\fBRFC 2049\fR\m[]\&\s-2\u[4]\d\s+2
73 for a formal definition of MIME\-formatted messages\&.
74 .PP
75 Each file in a MIME message is encoded as a single MIME section\&. A MIME section consists of at least one header line, "Content\-Type:"\&. The "Content\-Type:" header gives the type of the data ontained in the file\&. Other header lines may also be present\&. Their relative order does not matter\&. MIME headers are followed by a blank line, then the contents of the file, encoded appropriately\&. All MIME sections generated by
76 \fBmakemime\fR
77 will always contain another header, "Content\-Transfer\-Encoding:"\&. This header gives the encoding method used for the file; it is an optional header, but
78 \fBmakemime\fR
79 always creates it\&.
80 .PP
81 The MIME encoding method defaults to "7bit" if this header is absent\&.
82 7bit
83 encoding is only suitable for plain text messages in the US\-ASCII character set\&. The "8bit" encoding method is used by plain text messages in other character sets that use octets with the high bit set\&. An alternative to 8bit encoding is "quoted\-printable"\&. The "base64" encoding method is used for files containing binary data (anything other than plain text)\&.
84 .PP
85 MIME sections that contain text messages have their "Content\-Type:" header set to "text/plain"; or "text/html" for HTML messages\&. There are also several other, rare, content types that can be used\&. MIME sections that contain other kinds of data will use some other, appropriate "Content\-Type:" header, such as "image/gif", or "audio/x\-wav"\&.
86 .PP
87 MIME sections that contain textual content may also use the
88 base64
89 encoding method, they are not required to use
90 7bit,
91 8bit, or
92 quoted\-printable\&. "text/pdf" sections, that contain PDF files, typically contain binary data and must use the
93 base64
94 encoding\&. Consequently, MIME sections that typically contain binary data, such as
95 image/gif
96 and
97 audio/x\-wav, are free to use encodings other than
98 base64, as long as all the data can be represented by printable characters (but, in practice, that never happens)\&.
99 .PP
100 MIME sections may also contain other, optional, headers such as "Content\-Disposition:", "Content\-ID:", and "Content\-Name:"\&. Consult the appropriate RFCs for the specific usage of these headers\&. These headers can be added by
101 \fBmakemime\fR
102 by using the
103 \fB\-a\fR
104 option, as described below\&. These headers play no part in creating the overall structure of a MIME\-encoded message, and
105 \fBmakemime\fR
106 does not care much about these headers\&. It simply includes them, and their content, upon request\&.
107 .PP
108 Multiple files are formatted as a single message MIME message in two steps: first, by creating a MIME section for each file; and then creating a single MIME section that contains other MIME sections\&. A "multipart/mixed" MIME section contains a collection of MIME sections that represent different objects, attached together\&. A "multipart/alternative" MIME section contains a collection of MIME sections which are alternative representations of the same object, such as an HTML and a plain text version of the same message\&. Other "multipart" MIME sections also exist, and their usage is defined by their respective RFCs\&.
109 .SS "Creating a single MIME section"
110 .HP \w'\fBmakemime\fR\ 'u
111 \fBmakemime\fR {\-c\ "\fItype\fR"} [\-e\ "\fIencoding\fR"] [\-o\ \fIoutputfile\fR] [\-C\ "\fIcharset\fR"] [\-N\ "\fIname"\fR] [\-a\ "\fIheader:\ value"\fR...] {\fIfilename\fR}
112 .PP
113 The
114 \fB\-c\fR
115 option reads
116 filename, encodes it appropriately, adds the "Content\-Type: \fItype\fR" and "Content\-Transfer\-Encoding:" MIME headers, then writes the result to standard output\&.
117 type
118 can be any valid MIME type, except for
119 multipart\&. Setting
120 filename
121 to "\-" reads from standard input\&. Setting
122 filename
123 to "&\fIn\fR" reads from file descriptor #\fIn\fR\&.
124 .PP
125 The
126 \fB\-C\fR
127 option sets the MIME
128 charset
129 attribute for
130 text/plain
131 content\&. The
132 \fB\-N\fR
133 option sets the
134 name
135 attribute for
136 Content\-Type:\&.
137 .PP
138 \fIencoding\fR
139 argument should be specified\&. It\*(Aqs more efficient to do so\&.
140 \fIencoding\fR
141 must be one of the following:
142 7bit,
143 8bit,
144 quoted\-printable, or
145 base64\&.
146 .PP
147 If
148 \fIencoding\fR
149 is not specified,
150 \fBmakemime\fR
151 reads the
152 filename
153 twice \- once to figure out the best encoding method, and the second time to encode
154 filename\&. If
155 filename
156 is a pipe
157 \fBmakemime\fR
158 creates a temporary file, which is not very efficient if
159 filename
160 is large\&. However letting
161 \fBmakemime\fR
162 pick the encoding method is more convenient if
163 filename
164 is relatively small\&.
165 .PP
166 Another possibility is to omit
167 \fIencoding\fR
168 and set
169 \fItype\fR
170 to
171 auto\&. This combination sets "Content\-Type:" to either
172 text/plain, or
173 application/octet\-stream, based on the selected
174 \fIencoding\fR\&.
175 .PP
176 By default the encoded MIME section is written to standard output\&. The
177 \fB\-o\fR
178 option writes the MIME section to
179 \fIoutputfile\fR\&.
180 \fIoutputfile\fR
181 may be "&\fIn\fR", which writes the MIME section to a pipe on file descriptor #\fIn\fR\&.
182 .PP
183 \fBmakemime\fR
184 does not generate any other headers\&. Particularly, the "Mime\-Version:" header is required for MIME\-formatted E\-mail messages\&. Additional headers are specified by the
185 \fB\-a\fR
186 option, which may be used multiple times to insert multiple headers\&.
187 \fBmakemime\fR
188 doesn\*(Aqt do anything with them except to insert the headers into the generated MIME section\&.
189 .PP
190 Note that "Mime\-Version:" is only required for the top level MIME section\&. This header is not required for individual MIME sections that are later combined into a multipart MIME collection\&.
191 .if n \{\
192 .sp
193 .\}
194 .RS 4
195 .it 1 an-trap
196 .nr an-no-space-flag 1
197 .nr an-break-flag 1
198 .br
199 .ps +1
200 \fBNote\fR
201 .ps -1
202 .br
203 .PP
204 The
205 \fB\-c\fR
206 option must occur listed first, the remaining options must follow the
207 \fB\-c\fR
208 option\&.
209 .sp .5v
210 .RE
211 .SS "Creating a multipart MIME collection"
212 .HP \w'\fBmakemime\fR\ 'u
213 \fBmakemime\fR {\-m\ "multipart/\fItype\fR"} [\-e\ "\fIencoding\fR"] [\-o\ \fIoutputfile\fR] [\-a\ "\fIheader:\ value"\fR...] {\fIfilename\fR}
214 .PP
215 The
216 \fB\-m\fR
217 option is identical to the
218 \fB\-c\fR
219 option, except for three differences\&.
220 .PP
221 \fItype\fR
222 must be either "multipart/mixed", "multipart/alternative", or some other MIME multipart content type\&. Additionally, "\fIencoding\fR" can only be "7bit" or "8bit", and will default to "8bit" if not specified\&. Finally,
223 filename
224 must be a MIME\-formatted section, NOT a regular file\&. Usually
225 filename
226 is created by a previous invocation of
227 \fBmakemime\fR
228 (it can also be a pipe, like the
229 \fB\-c\fR
230 option), but it can be created via any other means\&.
231 .PP
232 The
233 \fB\-m\fR
234 option creates an initial multipart MIME collection, that contains only one MIME section, taken from
235 filename\&. The collection is written to standard output, or the pipe or to
236 \fIoutputfile\fR\&.
237 .SS "Creating a multipart MIME section"
238 .HP \w'\fBmakemime\fR\ 'u
239 \fBmakemime\fR {\-j\ \fIfile1\fR"} [\-o\ \fIoutputfile\fR] {\fIfile2\fR}
240 .PP
241 This option adds a MIME section to an existing MIME collection\&.
242 \fIfile1\fR
243 must be a MIME collection that was previously created by the
244 \fB\-m\fR
245 option\&.
246 \fIfile2\fR
247 must be a MIME section that was previously created by the
248 \fB\-c\fR
249 option\&. The
250 \fB\-j\fR
251 options adds the MIME section in
252 \fIfile2\fR
253 to the MIME collection in
254 \fIfile1\fR\&. The result is written to standard output or to
255 \fIoutputfile\fR\&.
256 .PP
257 \fIfile1\fR
258 and/or
259 \fIfile2\fR
260 may be "@&\fIn\fR" which reads from file descriptor #\fIn\fR\&. The
261 \fIoutputfile\fR
262 may also specify a file descriptor\&.
263 .PP
264 \fIfile1\fR
265 and
266 \fIfile2\fR
267 should ideally be created by
268 \fBmakemime\fR
269 as well\&. It\*(Aqs also possible to use MIME\-formatted files created by other software, but with some degree of care\&.
270 \fBmakemime\fR
271 is not intended to be a MIME parser, but a MIME generator\&. However some amount of MIME parsing is necessary to append a MIME section to an existing MIME collection\&.
272 \fBmakemime\fR\*(Aqs parsing is sufficient for appending a new section to a MIME collection, as long as the MIME headers in the MIME collections are straightforward\&. Very convoluted MIME headers may confuse
273 \fBmakemime\fR, and it may not be able to handle them\&.
274 .SS "Recursive MIME collections"
275 .PP
276 MIME collection may contain other MIME collections as well as MIME sections\&. The
277 \fB\-m\fR
278 and the
279 \fB\-j\fR
280 options may use a multipart MIME collection in place of a MIME section automatically because a multipart MIME collection is just a special type of a MIME section\&. The following example encodes a text message that can be alternatively represented as HTML or plain text, with some additional attachments:
281 .PP
282 1\&. Create a MIME collection that has a
283 text/plain
284 and a
285 text/html
286 MIME section\&.
287 .PP
288 2\&. Create a MIME collection consisting of the MIME section generated in step one, plus additional MIME sections containing other attachments\&.
289 .PP
290 For example:
291 .sp
292 .if n \{\
293 .RS 4
294 .\}
295 .nf
296 # Take two files containing the text and the html version of a message, and
297 # add MIME headers to them\&.
298
299 makemime \-c "text/plain; charset=iso\-8859\-1" \-o tmp1\&.txt msg\&.txt
300 makemime \-c "text/html; charset=iso\-8859\-1" \-o tmp1\&.html msg\&.html
301
302 # Combine the result into a multipart/alternative collection
303
304 makemime \-m "multipart/alternative" \-a "Content\-Disposition: inline" \e
305 \-o tmp\&.ma1 tmp1\&.txt
306 makemime \-j tmp\&.ma1 \-o tmp\&.ma2 tmp1\&.html
307
308 # Add MIME headers to an image attachment\&.
309
310 makemime \-c "image/gif" \-a "Content\-Disposition: attachment" \e
311 \-o tmp2\&.gif attachment\&.gif
312
313 # Create the final multipart/mixed collection
314
315 makemime \-m "multipart/mixed" \-a "Mime\-Version: 1\&.0" \e
316 \-o tmp\&.mm1 tmp\&.ma2
317 makemime \-j tmp\&.mm1 \-o output\&.msg tmp2\&.gif
318 .fi
319 .if n \{\
320 .RE
321 .\}
322 .PP
323 output\&.msg
324 now contains the complete MIME collection\&. Just add the
325 Subject:,
326 From:, and
327 To:
328 headers (can also be done by additional
329 \fB\-a\fR
330 options, of course), and send it on its way\&.
331 .SS "Building complex MIME encodings"
332 .PP
333 There are several different ways to build complete MIME encodings from multiple MIME sections\&. One way is to use temporary files to create MIME sections, then combine them together into a single MIME collection\&. A slightly more complicated approach involves setting up pipes between multiple makemime processes, in order to avoid using temporary files\&.
334 .PP
335 This can be done manually, by hand\&. It is also possible to have
336 \fBmakemime\fR
337 do this automatically\&.
338 \fBmakemime\fR
339 will set up these pipes and run multiple instances of itself to create a single MIME collection, with multiple attachments of complexity limited only by your system\*(Aqs limit on the maximum number of open files and pipes\&.
340 .PP
341 Any file that\*(Aqs read by the
342 \fB\-c\fR,
343 \fB\-m\fR, and
344 \fB\-j\fR
345 options (
346 \fB\-o\fR
347 specifies a file to create, and doesn\*(Aqt count) may be replaced by a single argument containing a left parenthesis, additional options, then a single argument containing a right parenthesis\&. A single invocation of
348 \fBmakemime\fR
349 can only use one
350 \fB\-c\fR,
351 \fB\-m\fR, or
352 \fB\-j\fR
353 option\&. However, another
354 \fB\-c\fR,
355 \fB\-m\fR, or
356 \fB\-j\fR
357 option may be specified inside the left and the right parenthesis, and its output is used in place of the file it replaced\&. In the previous example the third and the fourth invocation of
358 \fBmakemime\fR
359 can be replaced with the following command:
360 .sp
361 .if n \{\
362 .RS 4
363 .\}
364 .nf
365 makemime \-j \e( \e
366 \-m "multipart/alternative" \e
367 \-a "Content\-Disposition: inline" tmp1\&.txt \e
368 \e) \-o tmp\&.ma2 \e
369 tmp1\&.html
370 .fi
371 .if n \{\
372 .RE
373 .\}
374 .PP
375 Note that the parenthesis must be backslashed, to avoid their special meaning to the shell\&. An equivalent argument file would have the following contents:
376 .sp
377 .if n \{\
378 .RS 4
379 .\}
380 .nf
381 \-j
382 (
383 \-m
384 multipart/alternative
385 \-a
386 Content\-Disposition: inline
387 tmp1\&.txt
388 )
389 \-o
390 tmp\&.ma2
391 tmp1\&.html
392 .fi
393 .if n \{\
394 .RE
395 .\}
396 .PP
397 These constructs can be arbitrarily nested, and are limited by the amount of available memory and resources\&. The entire sequence in the previous section is equivalent to the following command:
398 .sp
399 .if n \{\
400 .RS 4
401 .\}
402 .nf
403 makemime \-j \e
404 \e( \e
405 \-m "multipart/mixed" \e
406 \-a "Mime\-Version: 1\&.0" \e
407 \e( \e
408 \-j \e
409 \e( \e
410 \-m "multipart/alternative" \e
411 \-a "Content\-Disposition: inline" \e
412 \e( \e
413 \-c "text/plain; charset=iso\-8859\-1" \e
414 msg\&.txt \e
415 \e) \e
416 \e) \e
417 \e( \e
418 \-c "text/html; charset=iso\-8859\-1" \e
419 msg\&.html \e
420 \e) \e
421 \e) \e
422 \e) \e
423 \-o output\&.msg \e
424 \e( \e
425 \-c "image/gif" \e
426 \-a "Content\-Disposition: attachment" \e
427 attachment\&.gif \e
428 \e)
429 .fi
430 .if n \{\
431 .RE
432 .\}
433 .PP
434 An equivalent argument file would be:
435 .sp
436 .if n \{\
437 .RS 4
438 .\}
439 .nf
440 \-j
441 (
442 \-m
443 multipart/mixed
444 \-a
445 Mime\-Version: 1\&.0
446 (
447 \-j
448 (
449 \-m
450 multipart/alternative
451 \-a
452 Content\-Disposition: inline
453 (
454 \-c
455 text/plain; charset=iso\-8859\-1
456 msg\&.txt
457 )
458 )
459 (
460 \-c
461 text/html; charset=iso\-8859\-1
462 msg\&.html
463 )
464 )
465 )
466 \-o
467 output\&.msg
468 (
469 \-c
470 image/gif
471 \-a
472 Content\-Disposition: attachment
473 attachment\&.gif
474 )
475 .fi
476 .if n \{\
477 .RE
478 .\}
479 .SH "SEE ALSO"
480 .PP
481 \m[blue]\fB\fBmaildrop\fR(1)\fR\m[]\&\s-2\u[5]\d\s+2,
482 \m[blue]\fB\fBmaildropfilter\fR(5)\fR\m[]\&\s-2\u[6]\d\s+2,
483 \m[blue]\fB\fBreformail\fR(1)\fR\m[]\&\s-2\u[7]\d\s+2,
484 \m[blue]\fB\fBreformime\fR(1)\fR\m[]\&\s-2\u[8]\d\s+2,
485 \fBegrep\fR(1),
486 \fBgrep\fR(1),
487 \m[blue]\fB\fBcourier\fR(8)\fR\m[]\&\s-2\u[9]\d\s+2,
488 \fBsendmail\fR(8),
489 \m[blue]\fBRFC 2045\fR\m[]\&\s-2\u[1]\d\s+2,
490 \m[blue]\fBRFC 2046\fR\m[]\&\s-2\u[2]\d\s+2,
491 \m[blue]\fBRFC 2047\fR\m[]\&\s-2\u[3]\d\s+2,
492 \m[blue]\fBRFC 2048\fR\m[]\&\s-2\u[4]\d\s+2,
493 \m[blue]\fBRFC 2049\fR\m[]\&\s-2\u[4]\d\s+2\&.
494 .SH "AUTHOR"
495 .PP
496 \fBSam Varshavchik\fR
497 .RS 4
498 Author
499 .RE
500 .SH "NOTES"
501 .IP " 1." 4
502 RFC 2045
503 .RS 4
504 \%http://www.rfc-editor.org/rfc/rfc2045.txt
505 .RE
506 .IP " 2." 4
507 RFC 2046
508 .RS 4
509 \%http://www.rfc-editor.org/rfc/rfc2046.txt
510 .RE
511 .IP " 3." 4
512 RFC 2047
513 .RS 4
514 \%http://www.rfc-editor.org/rfc/rfc2047.txt
515 .RE
516 .IP " 4." 4
517 RFC 2048
518 .RS 4
519 \%http://www.rfc-editor.org/rfc/rfc2048.txt
520 .RE
521 .IP " 5." 4
522 \fBmaildrop\fR(1)
523 .RS 4
524 \%http://www.courier-mta.org/maildrop/maildrop.html
525 .RE
526 .IP " 6." 4
527 \fBmaildropfilter\fR(5)
528 .RS 4
529 \%http://www.courier-mta.org/maildrop/maildropfilter.html
530 .RE
531 .IP " 7." 4
532 \fBreformail\fR(1)
533 .RS 4
534 \%http://www.courier-mta.org/maildrop/reformail.html
535 .RE
536 .IP " 8." 4
537 \fBreformime\fR(1)
538 .RS 4
539 \%http://www.courier-mta.org/maildrop/reformime.html
540 .RE
541 .IP " 9." 4
542 \fBcourier\fR(8)
543 .RS 4
544 \%http://www.courier-mta.org/maildrop/courier.html
545 .RE