5 .\" include the -mh macro file
8 .TH MHN %manext1% MH.6.8 [%nmhversion%]
10 mhn \- display/list/store/cache MIME messages
14 mhn \%[+folder] \%[msgs] \%[\-file file]
16 \%[\-part number]... \%[\-type content]...
18 \%[\-show] \%[\-noshow]
19 \%[\-list] \%[-nolist]
21 \%[\-store] \%[\-nostore]
22 \%[\-cache] \%[\-nocache]
24 \%[\-headers] \%[\-noheaders]
25 \%[\-realsize] \%[\-norealsize]
27 \%[\-serialonly] \%[\-noserialonly]
30 \%[\-pause] \%[\-nopause]
31 \%[\-auto] \%[\-noauto]
33 \%[\-rcache policy] \%[\-wcache policy]
34 \%[\-check] \%[\-nocheck]
36 \%[\-verbose] \%[\-noverbose]
43 \%[\-ebcdicsafe] \%[\-noebcdicsafe]
45 \%[\-rfc934mode] \%[\-norfc934mode]
49 MHN SHOULD BE CONSIDERED DEPRECATED. IT IS RETAINED FOR THE PURPOSE
50 OF BACKWARD COMPATIBILITY, BUT EVERYONE SHOULD MIGRATE TO USING THE
51 COMMANDS MHSHOW, MHSTORE, AND MHLIST. CHECK THE INDIVIDUAL MAN PAGES
54 The \fImhn\fR command allows you to display, list, store, or cache the
55 contents of a MIME (multi-media) messages.
57 \fImhn\fR manipulates multi-media messages as specified in RFC\-2045
58 thru RFC\-2049. Currently \fImhn\fR only supports encodings in message
59 bodies, and does not support the encoding of message headers as specified
62 The switches `\-list', `\-show', `\-store', and `-cache' direct
63 the operation of \fImhn\fR. Only one of these switches may be used
64 at a time. These switches are used to operate on the content of
65 each of the named messages. By using the `\-part' and `\-type'
66 switches, you may limit the scope of the given operation to particular
67 subparts (of a multipart content) and/or particular content types.
69 The switch `\-build' is used to construct a MIME message. It is
70 for backward compatibility and instructs \fImhn\fR to execute the
71 \fImhbuild\fR command. It is preferred that you use the \fImhbuild\fR
72 command directly. See the \fImhbuild\fR(1) man page for details.
74 The option `\-file\ file' directs \fImhn\fR to use the specified file as
75 the source message, rather than a message from a folder. If you specify
76 this file as \*(lq-\*(rq, then \fImhn\fR will accept the source message
77 on the standard input. Note that the file, or input from standard input
78 should be a validly formatted message, just like any other \fInmh\fR
79 message. It should \fBNOT\fR be in mail drop format (to convert a file in
80 mail drop format to a folder of \fInmh\fR messages, see \fIinc\fR\0(1)).
82 A part specification consists of a series of numbers separated by dots.
83 For example, in a multipart content containing three parts, these
84 would be named as 1, 2, and 3, respectively. If part 2 was also a
85 multipart content containing two parts, these would be named as 2.1 and
86 2.2, respectively. Note that the `\-part' switch is effective for only
87 messages containing a multipart content. If a message has some other
88 kind of content, or if the part is itself another multipart content, the
89 `\-part' switch will not prevent the content from being acted upon.
91 A content specification consists of a content type and a subtype.
92 The initial list of \*(lqstandard\*(rq content types and subtypes can
93 be found in RFC\-2046.
95 A list of commonly used contents is briefly reproduced here:
103 multipart mixed, alternative, digest, parallel
104 message rfc822, partial, external-body
105 application octet-stream, postscript
113 A legal MIME message must contain a subtype specification.
115 To specify a content, regardless of its subtype, just use the
116 name of the content, e.g., \*(lqaudio\*(rq. To specify a specific
117 subtype, separate the two with a slash, e.g., \*(lqaudio/basic\*(rq.
118 Note that regardless of the values given to the `\-type' switch, a
119 multipart content (of any subtype listed above) is always acted upon.
120 Further note that if the `\-type' switch is used, and it is desirable to
121 act on a message/external-body content, then the `\-type' switch must
122 be used twice: once for message/external-body and once for the content
123 externally referenced.
125 .Uh "Checking the Contents"
126 The `\-check' switch tells \fImhn\fR to check each content for an
127 integrity checksum. If a content has such a checksum (specified as a
128 Content-MD5 header field), then \fImhn\fR will attempt to verify the
129 integrity of the content.
131 .Uh "Listing the Contents"
132 The `\-list' switch tells \fImhn\fR to list the table of contents
133 associated with the named messages.
135 The `\-headers' switch indicates that
136 a one-line banner should be displayed above the listing. The `\-realsize'
137 switch tells \fImhn\fR to evaluate the \*(lqnative\*(rq (decoded) format
138 of each content prior to listing. This provides an accurate count at
139 the expense of a small delay. If the `\-verbose' switch is present, then
140 the listing will show any \*(lqextra\*(rq information that is present in
141 the message, such as comments in the Content-Type header.
143 .Uh "Showing the Contents"
144 The `\-show' switch tells \fImhn\fR to display the contents of the named
147 The headers of each message are displayed with the \fImhlproc\fR
148 (usually \fImhl\fR), using the standard format file \fImhl.headers\fR.
149 You may specify an alternate format file with the `\-form formfile'
150 switch. If the format file \fImhl.null\fR is specified, then the display
151 of the message headers is suppressed.
153 Next, the contents are extracted from the message and are stored in
154 a temporary file. Usually, the name of the temporary file the
155 word "mhn" followed by a string of characters. Occasionally,
156 the method used to display a content (described next), requires that
157 the file end in a specific suffix. For example, the \fIsoffice\fR
158 command (part of the StarOffice package) can be used to display
159 MicroSoft Word content, but it uses the suffix to determine how to display
160 the file. If no suffix is present, the file is not correctly loaded.
161 Similarily, older versions of the \fIgs\fR command append a ".ps" suffix to
162 the filename if one was missing. As a result, these cannot be used to read
163 the default temporary file.
165 To get around this, your profile can contain lines of the form:
168 mhn-suffix-<type>/<subtype>: <suffix>
174 mhn-suffix-<type>: <suffix>
177 to specify a suffix which can be automatically added to the temporary
178 file created for a specific content type. For example, the following
179 lines might appear in your profile:
183 mhn-suffix-text: .txt
184 mhn-suffix-application/msword: .doc
185 mhn-suffix-application/PostScript: .ps
189 to automatically append a suffix to the temporary files.
191 The method used to display the different contents in the messages bodies
192 will be determined by a \*(lqdisplay string\*(rq. To find the display
193 string, \fImhn\fR will first search your profile for an entry of the form:
196 mhn-show-<type>/<subtype>
199 to determine the display string. If this isn't found, \fImhn\fR
200 will search for an entry of the form:
206 to determine the display string.
208 If a display string is found, any escapes (given below) will be expanded.
209 The result will be executed under \fB/bin/sh\fR, with the standard input
212 The display string may contain the following escapes:
217 %a Insert parameters from Content-Type field
218 %e exclusive execution
219 %f Insert filename containing content
220 %F %e, %f, and stdin is terminal not content
221 %l display listing prior to displaying content
222 %p %l, and ask for confirmation
223 %s Insert content subtype
224 %d Insert content description
225 %% Insert the character %
231 For those display strings containing the e- or F-escape, \fImhn\fR will
232 execute at most one of these at any given time. Although the F-escape
233 expands to be the filename containing the content, the e-escape has no
234 expansion as far as the shell is concerned.
236 When the p-escape prompts for confirmation, typing INTR (usually
237 control-C) will tell \fImhn\fR not to display that content. The p-escape
238 can be disabled by specifying the switch `\-nopause'. Further, when
239 \fImhn\fR is display a content, typing QUIT (usually control-\\) will
240 tell \fImhn\fR to wrap things up immediately.
242 Note that if the content being displayed is multipart, but not one of
243 the subtypes listed above, then the f- and F-escapes expand to multiple
244 filenames, one for each subordinate content. Further, stdin is not
245 redirected from the terminal to the content.
247 If a display string is not found, \fImhn\fR has several default values:
251 mhn-show-text/plain: %pmoreproc '%F'
252 mhn-show-message/rfc822: %pshow -file '%F'
256 If a subtype of type text doesn't have a profile entry, it will be
257 treated as text/plain.
259 \fImhn\fR has default methods for handling multipart messages of subtype
260 mixed, alternative, parallel, and digest. Any unknown subtype of type
261 multipart (without a profile entry), will be treated as multipart/mixed.
263 If none of these apply, then \fImhn\fR will check to see if the message
264 has an application/octet-stream content with parameter \*(lqtype=tar\*(rq.
265 If so, \fImhn\fR will use an appropriate command. If not, \fImhn\fR
269 Example entries might be:
273 mhn-show-audio/basic: raw2audio 2>/dev/null | play
274 mhn-show-image: xv '%f'
275 mhn-show-application/PostScript: lpr -Pps
279 Note that when using the f- or F-escape, it's a good idea to use
280 single-quotes around the escape. This prevents misinterpretation by
281 the shell of any funny characters that might be present in the filename.
283 Finally, \fImhn\fR will process each message serially\0--\0it won't start
284 showing the next message until all the commands executed to display the
285 current message have terminated. In the case of a multipart content
286 (of any subtype listed above), the content contains advice indicating if
287 the parts should be displayed serially or in parallel. Because this may
288 cause confusion, particularly on uni-window displays, the `\-serialonly'
289 switch can be given to tell \fImhn\fR to never display parts in parallel.
291 .Uh "Showing Alternate Character Sets"
292 Because a content of type text might be in a non-ASCII character
293 set, when \fImhn\fR encounters a \*(lqcharset\*(rq parameter for
294 this content, it checks if your terminal can display this character
295 set natively. \fIMhn\fR checks this by examining the the environment
296 variable MM_CHARSET. If the value of this environment variable is equal
297 to the value of the charset parameter, then \fImhn\fR assumes it can
298 display this content without any additional setup. If this environment
299 variable is not set, \fImhn\fR will assume a value of \*(lqUS-ASCII\*(rq.
300 If the character set cannot be displayed natively, then \fImhn\fR will
301 look for an entry of the form:
304 mhn-charset-<charset>
307 which should contain a command creating an environment to render
308 the character set. This command string should containing a single
309 \*(lq%s\*(rq, which will be filled-in with the command to display the
312 Example entries might be:
315 mhn-charset-iso-8859-1: xterm -fn '-*-*-medium-r-normal-*-*-120-*-*-c-*-iso8859-*' -e %s
319 mhn-charset-iso-8859-1: '%s'
322 The first example tells \fImhn\fR to start \fIxterm\fR and load the
323 appropriate character set for that message content. The second example
324 tells \fImhn\fR that your pager (or other program handling that content
325 type) can handle that character set, and that no special processing is
328 Note that many pagers strip off the high-order bit or have problems
329 displaying text with the high-order bit set. However, the pager
330 \fIless\fR has support for single-octet character sets. The source
331 to \fIless\fR is available on many ftp sites carrying free software.
332 In order to view messages sent in the ISO-8859-1 character set using
335 put these lines in your \&.login file:
339 setenv LESSCHARSET latin1
344 The first line tells \fIless\fR to use the ISO-8859-1 definition for
345 determining whether a character is \*(lqnormal\*(rq, \*(lqcontrol\*(lq,
346 or \*(lqbinary\*(rq. The second line tells \fIless\fR not to warn you
347 if it encounters a file that has non-ASCII characters. Then, simply
348 set the \fBmoreproc\fR profile entry to \fIless\fR, and it will get
349 called automatically. (To handle other single-octet character sets,
350 look at the \fIless\fR\0(1) manual entry for information about the
351 \fBLESSCHARDEF\fR environment variable.)
353 .Uh "Storing the Contents"
354 The `\-store' switch tells \fImhn\fR to store the contents of the
355 named messages in \*(lqnative\*(rq (decoded) format. Two things must
356 be determined: the directory to store the content, and the filenames.
357 Files are written in the directory given by the \fBnmh-storage\fR
366 If this entry isn't present,
367 the current working directory is used.
369 If the `\-auto' switch is given, then \fImhn\fR will check if the
370 message contains information indicating the filename that should be
371 used to store the content. This information should be specified as the
372 attribute \*(lqname=filename\*(rq in the Content-Type header for the
373 content you are storing. For security reasons, this filename will be
374 ignored if it begins with the character '/', '.', '|', or '!', or if it
375 contains the character '%'. For the sake of security, this switch is
376 not the default, and it is recommended that you do NOT put the `\-auto'
377 switch in your \&.mh\(ruprofile file.
379 If the `\-auto' switch is not given (or is being ignored for
380 security reasons) then \fImhn\fR will look in the user's profile for
381 a \*(lqformatting string\*(rq to determine how the different contents
382 should be stored. First, \fImhn\fR will look for an entry of the form:
385 mhn-store-<type>/<subtype>
388 to determine the formatting string. If this isn't found, \fImhn\fR will
389 look for an entry of the form:
395 to determine the formatting string.
397 If the formatting string starts with a \*(lq+\*(rq character, then
398 content is stored in the named folder. A formatting string consisting
399 solely of a \*(lq+\*(rq character is interpreted to be the current folder.
401 If the formatting string consists solely of a \*(lq-\*(rq character,
402 then the content is sent to the standard output.
404 If the formatting string starts with a '|', then the display string will
405 represent a command for \fImhn\fR to execute which should ultimately
406 store the content. The content will be passed to the standard input of
407 the command. Before the command is executed, \fImhn\fR will change to
408 the appropriate directory, and any escapes (given below) in the display
409 string will be expanded.
411 Otherwise the formatting string will represent a pathname in which to
412 store the content. If the formatting string starts with a '/', then the
413 content will be stored in the full path given, else the file name will
414 be relative to the value of \fBnmh-storage\fR or the current working
415 directory. Any escapes (given below) will be expanded, except for the
418 A command or pathname formatting string may contain the following escapes.
419 If the content isn't part of a multipart (of any subtype listed above)
420 content, the p-escapes are ignored.
425 %a Parameters from Content-type (only valid with command)
426 %m Insert message number
427 %P Insert part number with leading dot
428 %p Insert part number without leading dot
429 %t Insert content type
430 %s Insert content subtype
431 %% Insert character %
436 If no formatting string is found, \fImhn\fR will check to see if the
437 content is application/octet-stream with parameter \*(lqtype=tar\*(rq.
438 If so, \fImhn\fR will choose an appropriate filename. If the content
439 is not application/octet-stream, then \fImhn\fR will check to see if the
440 content is a message. If so, \fImhn\fR will use the value \*(lq+\*(rq.
441 As a last resort, \fImhn\fR will use the value \*(lq%m%P.%s\*(rq.
444 Example profile entries might be:
448 mhn-store-text: %m%P.txt
449 mhn-store-text: +inbox
450 mhn-store-message/partial: +
451 mhn-store-audio/basic: | raw2audio -e ulaw -s 8000 -c 1 > %m%P.au
452 mhn-store-image/jpeg: %m%P.jpg
453 mhn-store-application/PostScript: %m%P.ps
457 .Uh "Reassembling Messages of Type message/partial"
458 When asked to store a content containing a partial message, \fImhn\fR
459 will try to locate all of the portions and combine them accordingly.
460 The default is to store the combined parts as a new message in the
461 current folder, although this can be changed using formatting
462 strings as discussed above. Thus, if someone has sent you a message
463 in several parts (such as the output from \fIsendfiles\fR), you can
464 easily reassemble them all into a single message in the following
470 msg part type/subtype size description
471 5 message/partial 47K part 1 of 4
472 6 message/partial 47K part 2 of 4
473 7 message/partial 47K part 3 of 4
474 8 message/partial 18K part 4 of 4
476 reassembling partials 5,6,7,8 to folder inbox as message 9
477 % mhn -list -verbose 9
478 msg part type/subtype size description
479 9 application/octet-stream 118K
480 (extract with uncompress | tar xvpf -)
486 This will store exactly one message, containing the sum of the
487 parts. It doesn't matter whether the partials are specified in
488 order, since \fImhn\fR will sort the partials, so that they are
489 combined in the correct order. But if \fImhn\fR can not locate
490 every partial necessary to reassemble the message, it will not
493 .Uh "External Access"
494 For contents of type message/external-body,
496 \fImhn\fR supports these access-types:
508 For the \*(lqanon-ftp\*(rq and \*(lqftp\*(rq access types,
509 \fImhn\fR will look for the \fBnmh-access-ftp\fR
515 nmh-access-ftp: myftp.sh
518 to determine the pathname of a program to perform the FTP retrieval.
520 This program is invoked with these arguments:
524 domain name of FTP-site
530 \*(lqascii\*(rq or \*(lqbinary\*(rq
534 The program should terminate with an exit status of zero if the
535 retrieval is successful, and a non-zero exit status otherwise.
537 If this entry is not provided, then \fImhn\fR will use a simple
538 built-in FTP client to perform the retrieval.
540 .Uh "The Content Cache"
541 When \fImhn\fR encounters an external content containing a
542 \*(lqContent-ID:\*(rq field, and if the content allows caching, then
543 depending on the caching behavior of \fImhn\fR, the content might be
544 read from or written to a cache.
546 The caching behavior of \fImhn\fR is controlled with the `\-rcache'
547 and `\-wcache' switches, which define the policy for reading from,
548 and writing to, the cache, respectively. One of four policies may be
549 specified: \*(lqpublic\*(rq, indicating that \fImhn\fR should make use
550 of a publically-accessible content cache; \*(lqprivate\*(rq, indicating
551 that \fImhn\fR should make use of the user's private content cache;
552 \*(lqnever\*(rq, indicating that \fImhn\fR should never make use of
553 caching; and, \*(lqask\*(rq, indicating that \fImhn\fR should ask
556 There are two directories where contents may be cached: the profile entry
557 \fBnmh-cache\fR names a directory containing world-readable contents, and,
558 the profile entry \fBnmh-private-cache\fR names a directory containing
559 private contents. The former should be an absolute (rooted) directory
568 might be used if you didn't care that the cache got wiped after each
569 reboot of the system. The latter is interpreted relative to the user's
570 nmh directory, if not rooted,
575 nmh-private-cache: .cache
578 (which is the default value).
580 .Uh "Caching the Contents"
581 When you encounter a content of type message/external-body with access
582 type \*(lqmail-server\*(rq, \fImhn\fR will ask you if may send a message
583 to a mail-server requesting the content,
590 Retrieve content by asking mail-server@...
599 Regardless of your decision,
600 \fImhn\fR can't perform any other processing on the content.
602 However, if \fImhn\fR is allowed to request the content, then when it
603 arrives, there should be a top-level \*(lqContent-ID:\*(rq field which
604 corresponds to the value in the original message/external-body content.
605 You should now use the `-cache' switch to tell \fImhn\fR to enter the
606 arriving content into the content cache,
613 caching message 2 as file ...
617 You can then re-process the original message/external-body content, and
618 \*(lqthe right thing should happen\*(rq,
629 .Uh "User Environment"
630 Because the display environment in which \fImhn\fR operates may vary for
631 different machines, \fImhn\fR will look for the environment variable
632 \fB$MHN\fR. If present, this specifies the name of an additional
633 user profile which should be read. Hence, when a user logs in on a
634 particular display device, this environment variable should be set to
635 refer to a file containing definitions useful for the given display device.
636 Normally, only entries that deal with the methods to display different
637 content type and subtypes
640 mhn-show-<type>/<subtype>
645 need be present in this additional profile.
647 \fImhn\fR will attempt to consult one other additional user profile,
652 %etcdir%/mhn.defaults
655 which is created automatically during nmh installation.
657 ^$HOME/\&.mh\(ruprofile~^The user profile
658 ^$MHN~^Additional profile entries
659 ^%etcdir%/mhn.defaults~^System default MIME profile entries
660 ^%etcdir%/mhl.headers~^The headers template
662 ^Path:~^To determine the user's nmh directory
664 ^Current\-Folder:~^To find the default current folder
666 ^mhlproc:~^Default program to display message headers
668 ^nmh-access-ftp:~^Program to retrieve contents via FTP
670 ^nmh-cache~^Public directory to store cached external contents
672 ^nmh-private-cache~^Personal directory to store cached external contents
674 ^mhn-charset-<charset>~^Template for environment to render character sets
676 ^mhn-show-<type>*~^Template for displaying contents
678 ^nmh-storage~^Directory to store contents
680 ^mhn-store-<type>*~^Template for storing contents
682 ^moreproc:~^Default program to display text/plain content
684 mhbuild(1), mhl(1), sendfiles(1)
688 \fIProposed Standard for Message Encapsulation\fR,
692 \fIMultipurpose Internet Mail Extensions (MIME) Part One:
694 Format of Internet Message Bodies\fR,
698 \fIMultipurpose Internet Mail Extensions (MIME) Part Two:
704 \fIMultipurpose Internet Mail Extensions (MIME) Part Three:
706 Message Header Extensions for Non-ASCII Text\fR,
710 \fIMultipurpose Internet Mail Extensions (MIME) Part Four:
712 Registration Procedures\fR,
716 \fIMultipurpose Internet Mail Extensions (MIME) Part Five:
718 Conformance Criteria and Examples\fR.
720 `+folder' defaults to the current folder
722 `msgs' defaults to cur
748 If a folder is given, it will become the current folder. The last
749 message selected will become the current message.
751 Partial messages contained within a multipart content are not reassembled
752 with the `\-store' switch.
projects / mmh / blob