5 .\" include the -mh macro file
8 .TH MHSTORE %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
10 mhstore \- store contents of MIME messages into files
14 mhstore \%[+folder] \%[msgs] \%[\-file file]
16 \%[\-part number]... \%[\-type content]...
18 \%[\-auto] \%[\-noauto]
19 \%[\-check] \%[\-nocheck]
21 \%[\-rcache policy] \%[\-wcache policy]
23 \%[\-verbose] \%[\-noverbose]
29 The \fImhstore\fR command allows you to store the contents of a
30 collection of MIME (multi-media) messages into files or other
33 \fImhstore\fR manipulates multi-media messages as specified in
34 RFC\-2045 thru RFC\-2049.
36 By default, \fImhstore\fR will store all the parts of each message.
37 Each part will be store in a separate file. The header fields of
38 the message are not stored. By using the `\-part' and `\-type'
39 switches, you may limit the scope of \fImhstore\fR to particular
40 subparts (of a multipart content) and/or particular content types.
42 The option `\-file\ file' directs \fImhstore\fR to use the specified
43 file as the source message, rather than a message from a folder.
44 If you specify this file as \*(lq-\*(rq, then \fImhstore\fR will
45 accept the source message on the standard input. Note that the
46 file, or input from standard input should be a validly formatted
47 message, just like any other \fInmh\fR message. It should \fBNOT\fR
48 be in mail drop format (to convert a file in mail drop format to
49 a folder of \fInmh\fR messages, see \fIinc\fR\0(1)).
51 A part specification consists of a series of numbers separated by
52 dots. For example, in a multipart content containing three parts,
53 these would be named as 1, 2, and 3, respectively. If part 2 was
54 also a multipart content containing two parts, these would be named
55 as 2.1 and 2.2, respectively. Note that the `\-part' switch is
56 effective for only messages containing a multipart content. If a
57 message has some other kind of content, or if the part is itself
58 another multipart content, the `\-part' switch will not prevent
59 the content from being acted upon.
61 A content specification consists of a content type and a subtype.
62 The initial list of \*(lqstandard\*(rq content types and subtypes
63 can be found in RFC\-2046.
65 A list of commonly used contents is briefly reproduced here:
73 multipart mixed, alternative, digest, parallel
74 message rfc822, partial, external-body
75 application octet-stream, postscript
83 A legal MIME message must contain a subtype specification.
85 To specify a content, regardless of its subtype, just use the name
86 of the content, e.g., \*(lqaudio\*(rq. To specify a specific
87 subtype, separate the two with a slash, e.g., \*(lqaudio/basic\*(rq.
88 Note that regardless of the values given to the `\-type' switch,
89 a multipart content (of any subtype listed above) is always acted
90 upon. Further note that if the `\-type' switch is used, and it is
91 desirable to act on a message/external-body content, then the
92 `\-type' switch must be used twice: once for message/external-body
93 and once for the content externally referenced.
95 .Uh "Checking the Contents"
96 The `\-check' switch tells \fImhstore\fR to check each content for
97 an integrity checksum. If a content has such a checksum (specified
98 as a Content-MD5 header field), then \fImhstore\fR will attempt to
99 verify the integrity of the content.
101 .Uh "Storing the Contents"
102 The \fImhstore\fR will store the contents of the named messages in
103 \*(lqnative\*(rq (decoded) format. Two things must be determined:
104 the directory to store the content, and the filenames. Files are
105 written in the directory given by the \fBnmh-storage\fR profile
114 If this entry isn't present,
115 the current working directory is used.
117 If the `\-auto' switch is given, then \fImhstore\fR will check if
118 the message contains information indicating the filename that should
119 be used to store the content. This information should be specified
120 as the attribute \*(lqname=filename\*(rq in the Content-Type header
121 for the content you are storing. For security reasons, this filename
122 will be ignored if it begins with the character '/', '.', '|', or
123 '!', or if it contains the character '%'. For the sake of security,
124 this switch is not the default, and it is recommended that you do
125 NOT put the `\-auto' switch in your \&.mh\(ruprofile file.
127 If the `\-auto' switch is not given (or is being ignored for security
128 reasons) then \fImhstore\fR will look in the user's profile for a
129 \*(lqformatting string\*(rq to determine how the different contents
130 should be stored. First, \fImhstore\fR will look for an entry of
134 mhstore-store-<type>/<subtype>
137 to determine the formatting string. If this isn't found, \fImhstore\fR
138 will look for an entry of the form:
144 to determine the formatting string.
146 If the formatting string starts with a \*(lq+\*(rq character, then
147 content is stored in the named folder. A formatting string consisting
148 solely of a \*(lq+\*(rq character is interpreted to be the current
151 If the formatting string consists solely of a \*(lq-\*(rq character,
152 then the content is sent to the standard output.
154 If the formatting string starts with a '|', then the display string
155 will represent a command for \fImhstore\fR to execute which should
156 ultimately store the content. The content will be passed to the
157 standard input of the command. Before the command is executed,
158 \fImhstore\fR will change to the appropriate directory, and any
159 escapes (given below) in the display string will be expanded.
161 Otherwise the formatting string will represent a pathname in which
162 to store the content. If the formatting string starts with a '/',
163 then the content will be stored in the full path given, else the
164 file name will be relative to the value of \fBnmh-storage\fR or
165 the current working directory. Any escapes (given below) will be
166 expanded, except for the a-escape.
168 A command or pathname formatting string may contain the following
169 escapes. If the content isn't part of a multipart (of any subtype
170 listed above) content, the p-escapes are ignored.
175 %a Parameters from Content-type (only valid with command)
176 %m Insert message number
177 %P Insert part number with leading dot
178 %p Insert part number without leading dot
179 %t Insert content type
180 %s Insert content subtype
181 %% Insert character %
186 If no formatting string is found, \fImhstore\fR will check to see
187 if the content is application/octet-stream with parameter
188 \*(lqtype=tar\*(rq. If so, \fImhstore\fR will choose an appropriate
189 filename. If the content is not application/octet-stream, then
190 \fImhstore\fR will check to see if the content is a message. If
191 so, \fImhstore\fR will use the value \*(lq+\*(rq. As a last resort,
192 \fImhstore\fR will use the value \*(lq%m%P.%s\*(rq.
195 Example profile entries might be:
199 mhstore-store-text: %m%P.txt
200 mhstore-store-text: +inbox
201 mhstore-store-message/partial: +
202 mhstore-store-audio/basic: | raw2audio -e ulaw -s 8000 -c 1 > %m%P.au
203 mhstore-store-image/jpeg: %m%P.jpg
204 mhstore-store-application/PostScript: %m%P.ps
208 .Uh "Reassembling Messages of Type message/partial"
209 \fImhstore\fR is also able to reassemble messages that have been
210 split into multiple messages of type \*(lqmessage/partial\*(rq.
212 When asked to store a content containing a partial message,
213 \fImhstore\fR will try to locate all of the portions and combine
214 them accordingly. The default is to store the combined parts as
215 a new message in the current folder, although this can be changed
216 using formatting strings as discussed above. Thus, if someone has
217 sent you a message in several parts (such as the output from
218 \fIsendfiles\fR), you can easily reassemble them all into a single
219 message in the following fashion:
224 msg part type/subtype size description
225 5 message/partial 47K part 1 of 4
226 6 message/partial 47K part 2 of 4
227 7 message/partial 47K part 3 of 4
228 8 message/partial 18K part 4 of 4
230 reassembling partials 5,6,7,8 to folder inbox as message 9
232 msg part type/subtype size description
233 9 application/octet-stream 118K
234 (extract with uncompress | tar xvpf -)
240 This will store exactly one message, containing the sum of the
241 parts. It doesn't matter whether the partials are specified in
242 order, since \fImhstore\fR will sort the partials, so that they
243 are combined in the correct order. But if \fImhstore\fR can not
244 locate every partial necessary to reassemble the message, it will
247 .Uh "External Access"
248 For contents of type message/external-body,
250 \fImhstore\fR supports these access-types:
262 For the \*(lqanon-ftp\*(rq and \*(lqftp\*(rq access types,
263 \fImhstore\fR will look for the \fBnmh-access-ftp\fR
269 nmh-access-ftp: myftp.sh
272 to determine the pathname of a program to perform the FTP retrieval.
274 This program is invoked with these arguments:
278 domain name of FTP-site
284 \*(lqascii\*(rq or \*(lqbinary\*(rq
288 The program should terminate with an exit status of zero if the
289 retrieval is successful, and a non-zero exit status otherwise.
291 If this entry is not provided, then \fImhstore\fR will use a simple
292 built-in FTP client to perform the retrieval.
294 .Uh "The Content Cache"
295 When \fImhstore\fR encounters an external content containing a
296 \*(lqContent-ID:\*(rq field, and if the content allows caching, then
297 depending on the caching behavior of \fImhstore\fR, the content might be
298 read from or written to a cache.
300 The caching behavior of \fImhstore\fR is controlled with the `\-rcache'
301 and `\-wcache' switches, which define the policy for reading from,
302 and writing to, the cache, respectively. One of four policies may be
303 specified: \*(lqpublic\*(rq, indicating that \fImhstore\fR should make use
304 of a publically-accessible content cache; \*(lqprivate\*(rq, indicating
305 that \fImhstore\fR should make use of the user's private content cache;
306 \*(lqnever\*(rq, indicating that \fImhstore\fR should never make use of
307 caching; and, \*(lqask\*(rq, indicating that \fImhstore\fR should ask
310 There are two directories where contents may be cached: the profile entry
311 \fBnmh-cache\fR names a directory containing world-readable contents, and,
312 the profile entry \fBnmh-private-cache\fR names a directory containing
313 private contents. The former should be an absolute (rooted) directory
322 might be used if you didn't care that the cache got wiped after each
323 reboot of the system. The latter is interpreted relative to the user's
324 nmh directory, if not rooted,
329 nmh-private-cache: .cache
332 (which is the default value).
334 .Uh "User Environment"
335 Because the environment in which \fImhstore\fR operates may vary
336 for different machines, \fImhstore\fR will look for the environment
337 variable \fB$MHSTORE\fR. If present, this specifies the name of
338 an additional user profile which should be read. Hence, when a
339 user logs in on a machine, this environment variable should be set
340 to refer to a file containing definitions useful for that machine.
341 Finally, \fImhstore\fR will attempt to consult one other additional
347 %etcdir%/mhn.defaults
350 which is created automatically during nmh installation.
352 ^$HOME/\&.mh\(ruprofile~^The user profile
353 ^$MHSTORE~^Additional profile entries
354 ^%etcdir%/mhn.defaults~^System default MIME profile entries
356 ^Path:~^To determine the user's nmh directory
358 ^Current\-Folder:~^To find the default current folder
360 ^nmh-access-ftp:~^Program to retrieve contents via FTP
362 ^nmh-cache~^Public directory to store cached external contents
364 ^nmh-private-cache~^Personal directory to store cached external contents
366 ^nmh-storage~^Directory to store contents
368 ^mhstore-store-<type>*~^Template for storing contents
370 mhbuild(1), mhlist(1), mhshow(1), sendfiles(1)
374 \fIMultipurpose Internet Mail Extensions (MIME) Part One:
376 Format of Internet Message Bodies\fR,
380 \fIMultipurpose Internet Mail Extensions (MIME) Part Two:
386 \fIMultipurpose Internet Mail Extensions (MIME) Part Three:
388 Message Header Extensions for Non-ASCII Text\fR,
392 \fIMultipurpose Internet Mail Extensions (MIME) Part Four:
394 Registration Procedures\fR,
398 \fIMultipurpose Internet Mail Extensions (MIME) Part Five:
400 Conformance Criteria and Examples\fR.
402 `+folder' defaults to the current folder
404 `msgs' defaults to cur
416 If a folder is given, it will become the current folder. The last
417 message selected will become the current message.
419 Partial messages contained within a multipart content are not reassembled.