Debian Codegraph @

upstream/debian-unstable/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: 08/28/2025
8 .\" Manual: Double Precision, Inc.
9 .\" Source: Courier Mail Server
10 .\" Language: English
11 .\"
12 .TH "MAKEMIME" "1" "08/28/2025" "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 by 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 .PP
64 For this to work the file with the option gets opened with a specific file descriptor, and then the options are read from that file descriptor:
65 .sp
66 .if n \{\
67 .RS 4
68 .\}
69 .nf
70 # Open options\&.txt on file descriptor 3,
71 # then specify that options
72 # are read from file descriptor 3\&.
73 # Quote special shell character "&"
74
75 makemime "@&3" 3<options\&.txt
76
77 .fi
78 .if n \{\
79 .RE
80 .\}
81 .PP
82 With
83 options\&.txt
84 contents:
85 .sp
86 .if n \{\
87 .RS 4
88 .\}
89 .nf
90 \-c
91 auto
92
93 \-C
94 utf\-8
95
96 \-N
97 text8bit
98
99 # options\&.txt is opened on file descriptor 3, read this MIME
100 # section starting after the \- terminator
101
102 &3
103 \-
104 [contents of the MIME section]
105
106 .fi
107 .if n \{\
108 .RE
109 .\}
110 .SS "MIME overview"
111 .PP
112 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
113 \fBmakemime\fR
114 utility\&. See
115 \m[blue]\fBRFC 2045\fR\m[]\&\s-2\u[1]\d\s+2,
116 \m[blue]\fBRFC 2046\fR\m[]\&\s-2\u[2]\d\s+2,
117 \m[blue]\fBRFC 2047\fR\m[]\&\s-2\u[3]\d\s+2,
118 \m[blue]\fBRFC 2048\fR\m[]\&\s-2\u[4]\d\s+2, and
119 \m[blue]\fBRFC 2049\fR\m[]\&\s-2\u[4]\d\s+2
120 for a formal definition of MIME\-formatted messages\&.
121 .PP
122 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
123 \fBmakemime\fR
124 will always contain another header, "Content\-Transfer\-Encoding:"\&. This header gives the encoding method used for the file; it is an optional header, but
125 \fBmakemime\fR
126 always creates it\&.
127 .PP
128 The MIME encoding method defaults to "7bit" if this header is absent\&.
129 7bit
130 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)\&.
131 .PP
132 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"\&.
133 .PP
134 MIME sections that contain textual content may also use the
135 base64
136 encoding method, they are not required to use
137 7bit,
138 8bit, or
139 quoted\-printable\&. "text/pdf" sections, that contain PDF files, typically contain binary data and must use the
140 base64
141 encoding\&. Consequently, MIME sections that typically contain binary data, such as
142 image/gif
143 and
144 audio/x\-wav, are free to use encodings other than
145 base64, as long as all the data can be represented by printable characters (but, in practice, that never happens)\&.
146 .PP
147 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
148 \fBmakemime\fR
149 by using the
150 \fB\-a\fR
151 option, as described below\&. These headers play no part in creating the overall structure of a MIME\-encoded message, and
152 \fBmakemime\fR
153 does not care much about these headers\&. It simply includes them, and their content, upon request\&.
154 .PP
155 Multiple files are formatted as a single 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\&.
156 .SS "Creating a single MIME section"
157 .HP \w'\fBmakemime\fR\ 'u
158 \fBmakemime\fR {\-c\ "\fItype\fR"} [\-e\ "\fIencoding\fR"] [\-o\ \fIoutputfile\fR] [\-C\ "\fIcharset\fR"] [\-N\ "\fIname"\fR] [\-a\ "\fIheader:\ value"\fR...] {\fIfilename\fR}
159 .PP
160 The
161 \fB\-c\fR
162 option reads
163 filename, encodes it appropriately, adds the "Content\-Type: \fItype\fR" and "Content\-Transfer\-Encoding:" MIME headers, then writes the result to standard output\&.
164 type
165 can be any valid MIME type, except for
166 multipart\&. Setting
167 filename
168 to "\-" reads from standard input\&. Setting
169 filename
170 to "&\fIn\fR" reads from file descriptor #\fIn\fR\&.
171 .PP
172 The
173 \fB\-C\fR
174 option sets the MIME
175 charset
176 attribute for
177 text/plain
178 content\&. The
179 \fB\-N\fR
180 option sets the
181 name
182 attribute for
183 Content\-Type:\&.
184 .PP
185 \fIencoding\fR
186 argument should be specified\&. It\*(Aqs more efficient to do so\&.
187 \fIencoding\fR
188 must be one of the following:
189 7bit,
190 8bit,
191 quoted\-printable, or
192 base64\&.
193 .PP
194 If
195 \fIencoding\fR
196 is not specified,
197 \fBmakemime\fR
198 reads the
199 filename
200 twice \- once to figure out the best encoding method, and the second time to encode
201 filename\&. If
202 filename
203 is a pipe
204 \fBmakemime\fR
205 creates a temporary file, which is not very efficient if
206 filename
207 is large\&. However letting
208 \fBmakemime\fR
209 pick the encoding method is more convenient if
210 filename
211 is relatively small\&.
212 .PP
213 Another possibility is to omit
214 \fIencoding\fR
215 and set
216 \fItype\fR
217 to
218 auto\&. This combination sets "Content\-Type:" to either
219 text/plain, or
220 application/octet\-stream, based on the selected
221 \fIencoding\fR\&.
222 .PP
223 By default the encoded MIME section is written to standard output\&. The
224 \fB\-o\fR
225 option writes the MIME section to
226 \fIoutputfile\fR\&.
227 \fIoutputfile\fR
228 may be "&\fIn\fR", which writes the MIME section to a pipe on file descriptor #\fIn\fR\&.
229 .PP
230 \fBmakemime\fR
231 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
232 \fB\-a\fR
233 option, which may be used multiple times to insert multiple headers\&.
234 \fBmakemime\fR
235 doesn\*(Aqt do anything with them except to insert the headers into the generated MIME section\&.
236 .PP
237 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\&.
238 .if n \{\
239 .sp
240 .\}
241 .RS 4
242 .nr an-no-space-flag 1
243 .nr an-break-flag 1
244 .br
245 .ps +1
246 \fBNote\fR
247 .ps -1
248 .br
249 .PP
250 The
251 \fB\-c\fR
252 option must occur listed first, the remaining options must follow the
253 \fB\-c\fR
254 option\&.
255 .sp .5v
256 .RE
257 .SS "Creating a multipart MIME collection"
258 .HP \w'\fBmakemime\fR\ 'u
259 \fBmakemime\fR {\-m\ "multipart/\fItype\fR"} [\-o\ \fIoutputfile\fR] [\-a\ "\fIheader:\ value"\fR...] {\fIfilename\fR}
260 .PP
261 The
262 \fB\-m\fR
263 option is similar to the
264 \fB\-c\fR
265 option, except for three differences\&.
266 .PP
267 \fItype\fR
268 must be either "multipart/mixed", "multipart/alternative", or some other MIME multipart content type\&. There is no explicit encoding\&. Also:
269 filename
270 must be a MIME\-formatted section, NOT a regular file\&. Usually
271 filename
272 is created by a previous invocation of
273 \fBmakemime\fR
274 (it can also be a pipe, like the
275 \fB\-c\fR
276 option), but it can be created via any other means\&.
277 .PP
278 The
279 \fB\-m\fR
280 option creates an initial multipart MIME collection, that contains only one MIME section, taken from
281 filename\&. The collection is written to standard output, or the pipe or to
282 \fIoutputfile\fR\&.
283 .SS "Creating a multipart MIME section"
284 .HP \w'\fBmakemime\fR\ 'u
285 \fBmakemime\fR {\-j\ \fIfile1\fR} [\-o\ \fIoutputfile\fR] {\fIfile2\fR}
286 .PP
287 This option adds a MIME section to an existing MIME collection\&.
288 \fIfile1\fR
289 must be a MIME collection that was previously created by the
290 \fB\-m\fR
291 option\&.
292 \fIfile2\fR
293 must be a MIME section that was previously created by the
294 \fB\-c\fR
295 option\&. The
296 \fB\-j\fR
297 options adds the MIME section in
298 \fIfile2\fR
299 to the MIME collection in
300 \fIfile1\fR\&. The result is written to standard output or to
301 \fIoutputfile\fR\&.
302 .PP
303 \fIfile1\fR
304 and/or
305 \fIfile2\fR
306 may be "@&\fIn\fR" which reads from file descriptor #\fIn\fR\&. The
307 \fIoutputfile\fR
308 may also specify a file descriptor\&.
309 .PP
310 \fIfile1\fR
311 and
312 \fIfile2\fR
313 should ideally be created by
314 \fBmakemime\fR
315 as well\&. It\*(Aqs also possible to use MIME\-formatted files created by other software, but with some degree of care\&.
316 \fBmakemime\fR
317 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\&.
318 \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
319 \fBmakemime\fR, and it may not be able to handle them\&.
320 .SS "Recursive MIME collections"
321 .PP
322 MIME collection may contain other MIME collections as well as MIME sections\&. The
323 \fB\-m\fR
324 and the
325 \fB\-j\fR
326 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:
327 .PP
328 1\&. Create a MIME collection that has a
329 text/plain
330 and a
331 text/html
332 MIME section\&.
333 .PP
334 2\&. Create a MIME collection consisting of the MIME section generated in step one, plus additional MIME sections containing other attachments\&.
335 .PP
336 For example:
337 .sp
338 .if n \{\
339 .RS 4
340 .\}
341 .nf
342 # Take two files containing the text and the html version of a message, and
343 # add MIME headers to them\&.
344
345 makemime \-c "text/plain; charset=iso\-8859\-1" \-o tmp1\&.txt msg\&.txt
346 makemime \-c "text/html; charset=iso\-8859\-1" \-o tmp1\&.html msg\&.html
347
348 # Combine the result into a multipart/alternative collection
349
350 makemime \-m "multipart/alternative" \-a "Content\-Disposition: inline" \e
351 \-o tmp\&.ma1 tmp1\&.txt
352 makemime \-j tmp\&.ma1 \-o tmp\&.ma2 tmp1\&.html
353
354 # Add MIME headers to an image attachment\&.
355
356 makemime \-c "image/gif" \-a "Content\-Disposition: attachment" \e
357 \-o tmp2\&.gif attachment\&.gif
358
359 # Create the final multipart/mixed collection
360
361 makemime \-m "multipart/mixed" \-a "Mime\-Version: 1\&.0" \e
362 \-o tmp\&.mm1 tmp\&.ma2
363 makemime \-j tmp\&.mm1 \-o output\&.msg tmp2\&.gif
364 .fi
365 .if n \{\
366 .RE
367 .\}
368 .PP
369 output\&.msg
370 now contains the complete MIME collection\&. Just add the
371 Subject:,
372 From:, and
373 To:
374 headers (can also be done by additional
375 \fB\-a\fR
376 options, of course), and send it on its way\&.
377 .SS "Building complex MIME encodings"
378 .PP
379 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\&.
380 .PP
381 This can be done manually, by hand\&. It is also possible to have
382 \fBmakemime\fR
383 do this automatically\&.
384 \fBmakemime\fR
385 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\&.
386 .PP
387 Any file that\*(Aqs read by the
388 \fB\-c\fR,
389 \fB\-m\fR, and
390 \fB\-j\fR
391 options (
392 \fB\-o\fR
393 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
394 \fBmakemime\fR
395 can only use one
396 \fB\-c\fR,
397 \fB\-m\fR, or
398 \fB\-j\fR
399 option\&. However, another
400 \fB\-c\fR,
401 \fB\-m\fR, or
402 \fB\-j\fR
403 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
404 \fBmakemime\fR
405 can be replaced with the following command:
406 .sp
407 .if n \{\
408 .RS 4
409 .\}
410 .nf
411 makemime \-j \e( \e
412 \-m "multipart/alternative" \e
413 \-a "Content\-Disposition: inline" tmp1\&.txt \e
414 \e) \-o tmp\&.ma2 \e
415 tmp1\&.html
416 .fi
417 .if n \{\
418 .RE
419 .\}
420 .PP
421 Note that the parenthesis must be backslashed, to avoid their special meaning to the shell\&. An equivalent argument file would have the following contents:
422 .sp
423 .if n \{\
424 .RS 4
425 .\}
426 .nf
427 \-j
428 (
429 \-m
430 multipart/alternative
431 \-a
432 Content\-Disposition: inline
433 tmp1\&.txt
434 )
435 \-o
436 tmp\&.ma2
437 tmp1\&.html
438 .fi
439 .if n \{\
440 .RE
441 .\}
442 .PP
443 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:
444 .sp
445 .if n \{\
446 .RS 4
447 .\}
448 .nf
449 makemime \-j \e
450 \e( \e
451 \-m "multipart/mixed" \e
452 \-a "Mime\-Version: 1\&.0" \e
453 \e( \e
454 \-j \e
455 \e( \e
456 \-m "multipart/alternative" \e
457 \-a "Content\-Disposition: inline" \e
458 \e( \e
459 \-c "text/plain; charset=iso\-8859\-1" \e
460 msg\&.txt \e
461 \e) \e
462 \e) \e
463 \e( \e
464 \-c "text/html; charset=iso\-8859\-1" \e
465 msg\&.html \e
466 \e) \e
467 \e) \e
468 \e) \e
469 \-o output\&.msg \e
470 \e( \e
471 \-c "image/gif" \e
472 \-a "Content\-Disposition: attachment" \e
473 attachment\&.gif \e
474 \e)
475 .fi
476 .if n \{\
477 .RE
478 .\}
479 .PP
480 An equivalent argument file would be:
481 .sp
482 .if n \{\
483 .RS 4
484 .\}
485 .nf
486 \-j
487 (
488 \-m
489 multipart/mixed
490 \-a
491 Mime\-Version: 1\&.0
492 (
493 \-j
494 (
495 \-m
496 multipart/alternative
497 \-a
498 Content\-Disposition: inline
499 (
500 \-c
501 text/plain; charset=iso\-8859\-1
502 msg\&.txt
503 )
504 )
505 (
506 \-c
507 text/html; charset=iso\-8859\-1
508 msg\&.html
509 )
510 )
511 )
512 \-o
513 output\&.msg
514 (
515 \-c
516 image/gif
517 \-a
518 Content\-Disposition: attachment
519 attachment\&.gif
520 )
521 .fi
522 .if n \{\
523 .RE
524 .\}
525 .SH "SEE ALSO"
526 .PP
527 \m[blue]\fB\fBmaildrop\fR(1)\fR\m[]\&\s-2\u[5]\d\s+2,
528 \m[blue]\fB\fBmaildropfilter\fR(5)\fR\m[]\&\s-2\u[6]\d\s+2,
529 \m[blue]\fB\fBreformail\fR(1)\fR\m[]\&\s-2\u[7]\d\s+2,
530 \m[blue]\fB\fBreformime\fR(1)\fR\m[]\&\s-2\u[8]\d\s+2,
531 \fBegrep\fR(1),
532 \fBgrep\fR(1),
533 \m[blue]\fB\fBcourier\fR(8)\fR\m[]\&\s-2\u[9]\d\s+2,
534 \fBsendmail\fR(8),
535 \m[blue]\fBRFC 2045\fR\m[]\&\s-2\u[1]\d\s+2,
536 \m[blue]\fBRFC 2046\fR\m[]\&\s-2\u[2]\d\s+2,
537 \m[blue]\fBRFC 2047\fR\m[]\&\s-2\u[3]\d\s+2,
538 \m[blue]\fBRFC 2048\fR\m[]\&\s-2\u[4]\d\s+2,
539 \m[blue]\fBRFC 2049\fR\m[]\&\s-2\u[4]\d\s+2\&.
540 .SH "AUTHOR"
541 .PP
542 \fBSam Varshavchik\fR
543 .RS 4
544 Author
545 .RE
546 .SH "NOTES"
547 .IP " 1." 4
548 RFC 2045
549 .RS 4
550 \%http://www.rfc-editor.org/rfc/rfc2045.txt
551 .RE
552 .IP " 2." 4
553 RFC 2046
554 .RS 4
555 \%http://www.rfc-editor.org/rfc/rfc2046.txt
556 .RE
557 .IP " 3." 4
558 RFC 2047
559 .RS 4
560 \%http://www.rfc-editor.org/rfc/rfc2047.txt
561 .RE
562 .IP " 4." 4
563 RFC 2048
564 .RS 4
565 \%http://www.rfc-editor.org/rfc/rfc2048.txt
566 .RE
567 .IP " 5." 4
568 \fBmaildrop\fR(1)
569 .RS 4
570 \%http://www.courier-mta.org/maildrop/maildrop.html
571 .RE
572 .IP " 6." 4
573 \fBmaildropfilter\fR(5)
574 .RS 4
575 \%http://www.courier-mta.org/maildrop/maildropfilter.html
576 .RE
577 .IP " 7." 4
578 \fBreformail\fR(1)
579 .RS 4
580 \%http://www.courier-mta.org/maildrop/reformail.html
581 .RE
582 .IP " 8." 4
583 \fBreformime\fR(1)
584 .RS 4
585 \%http://www.courier-mta.org/maildrop/reformime.html
586 .RE
587 .IP " 9." 4
588 \fBcourier\fR(8)
589 .RS 4
590 \%http://www.courier-mta.org/maildrop/courier.html
591 .RE