1 .TH MHSTORE %manext1% "March 2, 2014" "%nmhversion%"
6 mhstore \- store contents of MIME messages into files
23 .RB [ \-auto " | " \-noauto ]
25 .IR always " | " auto " | " suffix " | " ask " | " never ]
30 .RB [ \-check " | " \-nocheck ]
31 .RB [ \-verbose " | " \-noverbose ]
38 command allows you to store the contents of a
39 collection of MIME (multi-media) messages into files or other
43 manipulates multi-media messages as specified in
48 will store all the parts of each message.
49 Each part will be store in a separate file. The header fields of
50 the message are not stored. By using the
54 switches, you may limit the scope of
57 subparts (of a multipart content) and/or particular content types.
65 file as the source message, rather than a message from a folder.
66 If you specify this file as \*(lq-\*(rq, then
69 accept the source message on the standard input. Note that the
70 file, or input from standard input should be a validly formatted
71 message, just like any other
75 be in mail drop format (to convert a file in mail drop format to
81 A part specification consists of a series of numbers separated by
82 dots. For example, in a multipart content containing three parts,
83 these would be named as 1, 2, and 3, respectively. If part 2 was
84 also a multipart content containing two parts, these would be named
85 as 2.1 and 2.2, respectively. Note that the
88 effective for only messages containing a multipart content. If a
89 message has some other kind of content, or if the part is itself
90 another multipart content, the
92 switch will not prevent
93 the content from being acted upon.
95 A content specification consists of a content type and a subtype.
96 The initial list of \*(lqstandard\*(rq content types and subtypes
97 can be found in RFC 2046.
99 A list of commonly used contents is briefly reproduced here:
103 .ta \w'application 'u
107 multipart mixed, alternative, digest, parallel
108 message rfc822, partial, external-body
109 application octet-stream, postscript
116 A legal MIME message must contain a subtype specification.
118 To specify a content, regardless of its subtype, just use the name
119 of the content, e.g., \*(lqaudio\*(rq. To specify a specific
120 subtype, separate the two with a slash, e.g., \*(lqaudio/basic\*(rq.
121 Note that regardless of the values given to the
124 a multipart content (of any subtype listed above) is always acted
125 upon. Further note that if the
127 switch is used, and it is
128 desirable to act on a message/external-body content, then the
130 switch must be used twice: once for message/external-body
131 and once for the content externally referenced.
132 .SS "Checking the Contents"
137 to check each content for
138 an integrity checksum. If a content has such a checksum (specified
139 as a Content-MD5 header field), then
142 verify the integrity of the content.
143 .SS "Storing the Contents"
145 will store the contents of the named messages in
146 \*(lqnative\*(rq (decoded) format. Two things must be determined:
147 the directory to store the content, and the filenames. Files are
148 written in the directory given by the \*(lqnmh-storage\*(rq profile
155 If this entry isn't present,
156 the current working directory is used.
160 switch is given, its argument is used for the filename to store all
161 of the content, with \*(lq-\*(rq indicating standard output. If the
163 switch is given, then
165 will check if the message contains information indicating the filename
166 that should be used to store the content. This information should be
167 specified as the \*(lqfilename\*(rq attribute in the
168 \*(lqContent-Disposition\*(rq header or as the \*(lqname\*(rq
169 attribute in the \*(lqContent-Type\*(rq header for the content you are
170 storing. For security reasons, this filename will be ignored if it
171 begins with the character '/', '.', '|', or '!', or if it contains the
172 character '%'. We also recommend using a \*(lqnmh-storage\*(rq profile
175 switch setting other than the default of \*(lqalways\*(rq to avoid
176 overwriting existing files.
180 switch is not given (or is being ignored for security
183 will look in the user's profile for a
184 \*(lqformatting string\*(rq to determine how the different contents
185 should be stored. First,
187 will look for an entry of
191 mhstore-store-<type>/<subtype>
194 to determine the formatting string. If this isn't found,
196 will look for an entry of the form:
202 to determine the formatting string.
204 If the formatting string starts with a \*(lq+\*(rq character, then
205 content is stored in the named folder. A formatting string consisting
206 solely of a \*(lq+\*(rq character is interpreted to be the current
209 If the formatting string consists solely of a \*(lq-\*(rq character,
210 then the content is sent to the standard output.
212 If the formatting string starts with a '|', then it represents
215 to execute which should
216 ultimately store the content. The content will be passed to the
217 standard input of the command. Before the command is executed,
219 will change to the appropriate directory, and any
220 escapes (given below) in the formatting string will be expanded.
221 The use of the \*(lq%a\*(rq sequence is not recommended because
222 the user has no control over the Content-Type parameter data.
224 Otherwise the formatting string will represent a pathname in which
225 to store the content. If the formatting string starts with a '/',
226 then the content will be stored in the full path given, else the
227 file name will be relative to the value of \*(lqnmh-storage\*(rq or
228 the current working directory. Any escapes (given below) will be
229 expanded, except for the a-escape. Note that if \*(lqnmh-storage\*(rq
230 is not an absolute path, it will be relative to the folder that
231 contains the message(s).
233 A command or pathname formatting string may contain the following
234 escapes. If the content isn't part of a multipart (of any subtype
235 listed above) content, the p-escapes are ignored.
240 %a Parameters from Content-Type (only valid with command)
241 %m Insert message number
242 %P Insert part number with leading dot
243 %p Insert part number without leading dot
244 %t Insert content type
245 %s Insert content subtype
246 %% Insert character %
250 If no formatting string is found,
253 if the content is application/octet-stream with parameter
254 \*(lqtype=tar\*(rq. If so,
256 will choose an appropriate
257 filename. If the content is not application/octet-stream, then
259 will check to see if the content is a message. If
262 will use the value \*(lq+\*(rq. As a last resort,
264 will use the value \*(lq%m%P.%s\*(rq.
266 Example profile entries might be:
270 mhstore-store-text: %m%P.txt
271 mhstore-store-text: +inbox
272 mhstore-store-message/partial: +
273 mhstore-store-audio/basic: | raw2audio -e ulaw -s 8000 -c 1 > %m%P.au
274 mhstore-store-image/jpeg: %m%P.jpg
275 mhstore-store-application/PostScript: %m%P.ps
283 to print out the names of files that it stores. For backward
284 compatibility, it is the default. The
286 switch suppresses these printouts.
288 .SS "Overwriting Existing Files"
291 switch controls whether
293 should overwrite existing files. The allowed values for this switch
294 and corresponding behavior when
296 encounters an existing file are:
301 always Overwrite existing file (default)
302 auto Create new file of form name-n.extension
303 suffix Create new file of form name.extension.n
304 ask Prompt the user to specify whether or not to overwrite
306 never Do not overwrite existing file
315 is the lowest unused number, starting from one, in the same form. If
316 a filename does not have an extension (following a '.'), then
320 create a new file of the form
330 will be the number of files that were requested but not stored.
334 if standard input is connected to a terminal,
335 the user is prompted to respond
340 to whether the file should be overwritten. The responses
341 can be abbreviated. If the user responds with
345 prompts the user for the name of the new file to be created. If it is
346 a relative path name (does not begin with '/'), then it is relative to
347 the current directory. If it is an absolute or relative path to a
348 directory that does not exist, the user will be prompted whether to
349 create the directory. If standard input is not connected to a
354 .SS "Reassembling Messages of Type message/partial"
356 is also able to reassemble messages that have been
357 split into multiple messages of type \*(lqmessage/partial\*(rq.
359 When asked to store a content containing a partial message,
361 will try to locate all of the portions and combine
362 them accordingly. The default is to store the combined parts as
363 a new message in the current folder, although this can be changed
364 using formatting strings as discussed above. Thus, if someone has
365 sent you a message in several parts (such as the output from
367 you can easily reassemble them all into a single
368 message in the following fashion:
373 msg part type/subtype size description
374 5 message/partial 47K part 1 of 4
375 6 message/partial 47K part 2 of 4
376 7 message/partial 47K part 3 of 4
377 8 message/partial 18K part 4 of 4
379 reassembling partials 5,6,7,8 to folder inbox as message 9
381 msg part type/subtype size description
382 9 application/octet-stream 118K
383 (extract with uncompress | tar xvpf -)
389 This will store exactly one message, containing the sum of the
390 parts. It doesn't matter whether the partials are specified in
393 will sort the partials, so that they
394 are combined in the correct order. But if
397 locate every partial necessary to reassemble the message, it will
399 .SS "External Access"
400 For contents of type message/external-body,
401 \fImhstore\fR supports these access-types:
416 For the \*(lqanon-ftp\*(rq and \*(lqftp\*(rq access types,
418 will look for the \*(lqnmh-access-ftp\*(rq
422 nmh-access-ftp: myftp.sh
425 to determine the pathname of a program to perform the FTP retrieval.
426 This program is invoked with these arguments:
430 domain name of FTP-site
436 \*(lqascii\*(rq or \*(lqbinary\*(rq
440 The program should terminate with an exit status of zero if the
441 retrieval is successful, and a non-zero exit status otherwise.
443 For the \*(lqurl\*(rq access types,
445 will look for the \*(lqnmh-access-url\*(rq profile entry, e.g.,
448 nmh-access-url: curl -L
451 to determine the program to use to perform the HTTP retrieval. This program
452 is invoked with one argument: the URL of the content to retrieve. The program
453 should write the content to standard out, and should terminate with a status of zero if the retrieval is successful and a non\-zero exit status otherwise.
455 .SS "The Content Cache"
458 encounters an external content containing a
459 \*(lqContent-ID:\*(rq field, and if the content allows caching, then
460 depending on the caching behavior of
462 the content might be read from or written to a cache.
464 The caching behavior of
466 is controlled with the
470 switches, which define the policy for reading from,
471 and writing to, the cache, respectively. One of four policies may be
472 specified: \*(lqpublic\*(rq, indicating that
475 of a publically-accessible content cache; \*(lqprivate\*(rq, indicating
478 should make use of the user's private content cache;
479 \*(lqnever\*(rq, indicating that
481 should never make use of
482 caching; and, \*(lqask\*(rq, indicating that
486 There are two directories where contents may be cached: the profile entry
487 \*(lqnmh-cache\*(rq names a directory containing world-readable contents, and,
488 the profile entry \*(lqnmh-private-cache\*(rq names a directory containing
489 private contents. The former should be an absolute (rooted) directory
498 might be used if you didn't care that the cache got wiped after each
499 reboot of the system. The latter is interpreted relative to the user's
500 nmh directory, if not rooted, e.g.,
503 nmh-private-cache: .cache
506 (which is the default value).
507 .SS "User Environment"
508 Because the environment in which
510 operates may vary for
513 will look for the environment variable
515 If present, this specifies the name of an additional
516 user profile which should be read. Hence, when a user logs in on a
517 particular machine, this environment variable should be set to
518 refer to a file containing definitions useful for that machine.
521 will attempt to consult
524 %nmhetcdir%/mhn.defaults
527 which is created automatically during
531 See "Profile Lookup" in
533 for the profile search order, and for how duplicate entries are treated.
536 looks for additional profile files in multiple locations: absolute
537 pathnames are accessed directly, tilde expansion is done on usernames,
538 and files are searched for in the user's
540 directory as specified in their profile. If not found there, the directory
541 .RI \*(lq %nmhetcdir% \*(rq
546 .ta \w'%nmhetcdir%/ExtraBigFileName 'u
547 ^$HOME/\&.mh\(ruprofile~^The user profile
548 ^$MHSTORE~^Additional profile entries
549 ^%nmhetcdir%/mhn.defaults~^System default MIME profile entries
551 .SH "PROFILE COMPONENTS"
555 .ta \w'ExtraBigProfileName 'u
556 ^Path:~^To determine the user's nmh directory
557 ^Current\-Folder:~^To find the default current folder
558 ^nmh-access-ftp:~^Program to retrieve contents via FTP
559 ^nmh-access-url:~^Program to retrieve contents via HTTP
560 ^nmh-cache~^Public directory to store cached external contents
561 ^nmh-private-cache~^Personal directory to store cached external contents
562 ^nmh-storage~^Directory to store contents
563 ^mhstore-store-<type>*~^Template for storing contents
572 .RB ` +folder "' defaults to the current folder"
573 .RB ` msgs "' defaults to cur"
575 .RB ` \-clobber\ always '
577 .RB ` \-rcache\ ask '
578 .RB ` \-wcache\ ask '
581 If a folder is given, it will become the current folder. The last
582 message selected will become the current message.
584 Partial messages contained within a multipart content are not reassembled.
projects / nmh / blob