1MHSTORE(1) General Commands Manual MHSTORE(1)
2
6 mhstore - store contents of nmh MIME messages into files
7
9 mhstore [-help] [-version] [+folder] [msgs] [-file file] [-outfile out‐
10 file] [-part number] ... [-type content] ... [-prefer content]
11 ... [-noprefer] [-auto | -noauto] [-clobber always | auto | suf‐
12 fix | ask | never] [-rcache policy] [-wcache policy] [-check |
13 -nocheck] [-verbose | -noverbose]
14
16 The mhstore command allows you to store the contents of a collection of
17 MIME (multi-media) messages into files or other messages.
18 mhstore manipulates multi-media messages as specified in RFC 2045 to
20 RFC 2049.
21 By default, mhstore will store all the parts of each message. Each
23 part will be stored in a separate file. The header fields of the mes‐
24 sage are not stored. By using the -part, -type, and -prefer switches,
25 you may limit and reorder the set of parts to be stored, based on part
26 number and/or content type.
27 The -file file switch directs mhstore to use the specified file as the
29 source message, rather than a message from a folder. If you specify
30 this file as “-”, then mhstore will accept the source message on the
31 standard input. Note that the file, or input from standard input,
32 should be a validly formatted message, just like any other nmh message.
33 It should not be in mail drop format (to convert a file in mail drop
34 format to a folder of nmh messages, see inc(1)).
35 A part specification consists of a series of numbers separated by dots.
37 For example, in a multipart content containing three parts, these would
38 be named as 1, 2, and 3, respectively. If part 2 was also a multipart
39 content containing two parts, these would be named as 2.1 and 2.2,
40 respectively. Note that the -part switch is effective only for mes‐
41 sages containing a multipart content. If a message has some other kind
42 of content, or if the part is itself another multipart content, the
43 -part switch will not prevent the content from being acted upon.
44 The -type switch can also be used to restrict (or, when used in con‐
46 junction with -part, to further restrict) the selection of parts
47 according to content type. One or more -type switches part will only
48 select the first match from a multipart/alternative, even if there is
49 more than one subpart that matches (one of) the given content type(s).
50 Using either -part or -type switches alone will cause either to select
52 the part(s) they match. Using them together will select only the
53 part(s) matched by both (sets of) switches. In other words, the result
54 is the intersection, and not the union, of their separate match
55 results.
56 A content specification consists of a content type and a subtype. The
58 initial list of “standard” content types and subtypes can be found in
59 RFC 2046.
60 A list of commonly used contents is briefly reproduced here:
62 Type Subtypes
64 ---- --------
65 text plain, enriched
66 multipart mixed, alternative, digest, parallel
67 message rfc822, partial, external-body
68 application octet-stream, postscript
69 image jpeg, gif, png
70 audio basic
71 video mpeg
72 A legal MIME message must contain a subtype specification.
74 To specify a content, regardless of its subtype, just use the name of
76 the content, e.g., “audio”. To specify a specific subtype, separate
77 the two with a slash, e.g., “audio/basic”. Note that regardless of the
78 values given to the -type switch, a multipart content (of any subtype
79 listed above) is always acted upon. Further note that if the -type
80 switch is used, and it is desirable to act on a message/external-body
81 content, then the -type switch must be used twice: once for mes‐
82 sage/external-body and once for the content externally referenced.
83 The -prefer switch will alter the part-ordering of multipart/alterna‐
85 tive MIME sections in order to override the sender-imposed default
86 ordering. The -prefer switch is functionally most important for
87 mhshow, but is also implemented in mhlist and mhstore to make common
88 part-numbering possible across all three programs. The last of multi‐
89 ple -prefer switches will have the highest priority. This allows the
90 command line switches to override profile entries. See mhlist(1) and
91 mhshow(1) for more information on -prefer.
92 The -noprefer switch will cancel any previous -prefer switches.
94 Checking the Contents
96 The -check switch tells mhstore to check each content for an integrity
97 checksum. If a content has such a checksum (specified as a Content-MD5
98 header field), then mhstore will attempt to verify the integrity of the
99 content.
100 Storing the Contents
102 mhstore will store the contents of the named messages in “native”
103 (decoded) format. Two things must be determined: the directory in
104 which to store the content, and the filenames. Files are written in
105 the directory given by the “nmh-storage” profile entry, e.g.,
106 nmh-storage: /tmp
108 If this entry isn't present, the current working directory is used.
110 If the -outfile switch is given, its argument is used for the filename
112 to store all of the content, with “-” indicating standard output. If
113 the -auto switch is given, then mhstore will check if the message con‐
114 tains information indicating the filename that should be used to store
115 the content. This information should be specified as the “filename”
116 attribute in the “Content-Disposition” header or as the “name”
117 attribute in the “Content-Type” header for the content you are storing.
118 For security reasons, this filename will be ignored if it begins with
119 the character '/', '.', '|', or '!', or if it contains the character
120 '%'. We also recommend using a “nmh-storage” profile entry or a -clob‐
121 ber switch setting other than the default of “always” to avoid over‐
122 writing existing files.
123 If the -auto switch is not given (or is being ignored for security rea‐
125 sons) then mhstore will look in the user's profile for a “formatting
126 string” to determine how the different contents should be stored.
127 First, mhstore will look for an entry of the form:
128 mhstore-store-<type>/<subtype>
130 to determine the formatting string. If this isn't found, mhstore will
132 look for an entry of the form:
133 mhstore-store-<type>
135 to determine the formatting string.
137 If the formatting string starts with a “+” character, then content is
139 stored in the named folder. A formatting string consisting solely of a
140 “+” character is interpreted to be the current folder.
141 If the formatting string consists solely of a “-” character, then the
143 content is sent to the standard output.
144 If the formatting string starts with a '|', then it represents a com‐
146 mand for mhstore to execute which should ultimately store the content.
147 The content will be passed to the standard input of the command.
148 Before the command is executed, mhstore will change to the appropriate
149 directory, and any escapes (given below) in the formatting string will
150 be expanded. The use of the “%a” sequence is not recommended because
151 the user has no control over the Content-Type parameter data.
152 Otherwise, the formatting string will represent a pathname in which to
154 store the content. If the formatting string starts with a '/', then
155 the content will be stored in the full path given, else the file name
156 will be relative to the value of “nmh-storage” or the current working
157 directory. Any escapes (given below) will be expanded, except for the
158 a-escape. Note that if “nmh-storage” is not an absolute path, it will
159 be relative to the folder that contains the message(s).
160 A command or pathname formatting string may contain the following
162 escapes. If the content isn't part of a multipart (of any subtype
163 listed above) content, the p-escapes are ignored.
164 %a Parameters from Content-Type (only valid with command)
166 %m Insert message number
167 %P Insert part number with leading dot
168 %p Insert part number without leading dot
169 %t Insert content type
170 %s Insert content subtype
171 %% Insert character %
172 If no formatting string is found, mhstore will check to see if the con‐
174 tent is application/octet-stream with parameter “type=tar”. If so,
175 mhstore will choose an appropriate filename. If the content is not
176 application/octet-stream, then mhstore will check to see if the content
177 is a message. If so, mhstore will use the value “+”. As a last
178 resort, mhstore will use the value “%m%P.%s”.
179 Example profile entries might be:
181 mhstore-store-text: %m%P.txt
183 mhstore-store-text: +inbox
184 mhstore-store-message/partial: +
185 mhstore-store-audio/basic: | raw2audio -e ulaw -s 8000 -c 1 > %m%P.au
186 mhstore-store-image/jpeg: %m%P.jpg
187 mhstore-store-application/PostScript: %m%P.ps
188 The -verbose switch directs mhstore to print out the names of files
190 that it stores. For backward compatibility, it is the default. The
191 -noverbose switch suppresses these printouts.
192 Overwriting Existing Files
194 The -clobber switch controls whether mhstore should overwrite existing
195 files. The allowed values for this switch and corresponding behavior
196 when mhstore encounters an existing file are:
197 always Overwrite existing file (default)
199 auto Create new file of form name-n.extension
200 suffix Create new file of form name.extension.n
201 ask Prompt the user to specify whether or not to overwrite
202 the existing file
203 never Do not overwrite existing file
204 With auto and suffix, n is the lowest unused number, starting from one,
206 in the same form. If a filename does not have an extension (following
207 a '.'), then auto and suffix create a new file of the form name-n and
208 name.n, respectively. With never and ask, the exit status of mhstore
209 will be the number of files that were requested but not stored.
210 With ask, if standard input is connected to a terminal, the user is
212 prompted to respond yes, no, or rename, to whether the file should be
213 overwritten. The responses can be abbreviated. If the user responds
214 with rename, then mhstore prompts the user for the name of the new file
215 to be created. If it is a relative path name (does not begin with
216 '/'), then it is relative to the current directory. If it is an abso‐
217 lute or relative path to a directory that does not exist, the user will
218 be prompted whether to create the directory. If standard input is not
219 connected to a terminal, ask behaves the same as always.
220 Reassembling Messages of Type message/partial
222 mhstore is also able to reassemble messages that have been split into
223 multiple messages of type “message/partial”.
224 When asked to store a content containing a partial message, mhstore
226 will try to locate all of the portions and combine them accordingly.
227 The default is to store the combined parts as a new message in the cur‐
228 rent folder, although this can be changed using formatting strings as
229 discussed above. Thus, if someone has sent you a message in several
230 parts (such as the output from sendfiles), you can easily reassemble
231 them into a single message in the following fashion:
232 % mhlist 5-8
234 msg part type/subtype size description
235 5 message/partial 47K part 1 of 4
236 6 message/partial 47K part 2 of 4
237 7 message/partial 47K part 3 of 4
238 8 message/partial 18K part 4 of 4
239 % mhstore 5-8
240 reassembling partials 5,6,7,8 to folder inbox as message 9
241 % mhlist -verbose 9
242 msg part type/subtype size description
243 9 application/octet-stream 118K
244 (extract with uncompress | tar xvpf -)
245 type=tar
246 conversions=compress
247 This will store exactly one message, containing the sum of the parts.
249 It doesn't matter whether the partials are specified in order, since
250 mhstore will sort the partials, so that they are combined in the cor‐
251 rect order. But if mhstore can not locate every partial necessary to
252 reassemble the message, it will not store anything.
253 External Access
255 For contents of type message/external-body, mhstore supports these
256 access-types:
257 · afs
259 · anon-ftp
261 · ftp
263 · local-file
265 · mail-server
267 · url
269 For the “anon-ftp” and “ftp” access types, mhstore will look for the
271 “nmh-access-ftp” profile entry, e.g.,
272 nmh-access-ftp: myftp.sh
274 to determine the pathname of a program to perform the FTP retrieval.
276 This program is invoked with these arguments:
277 domain name of FTP-site
279 username
280 password
281 remote directory
282 remote filename
283 local filename
284 “ascii” or “binary”
285 The program should terminate with an exit status of zero if the
287 retrieval is successful, and a non-zero exit status otherwise.
288 For the “url” access types, mhstore will look for the “nmh-access-url”
290 profile entry, e.g.,
291 nmh-access-url: curl -L
293 to determine the program to use to perform the HTTP retrieval. This
295 program is invoked with one argument: the URL of the content to
296 retrieve. The program should write the content to standard out, and
297 should terminate with a status of zero if the retrieval is successful
298 and a non-zero exit status otherwise.
299 The Content Cache
301 When mhstore encounters an external content containing a “Content-ID:”
302 field, and if the content allows caching, then depending on the caching
303 behavior of mhstore, the content might be read from or written to a
304 cache.
305 The caching behavior of mhstore is controlled with the -rcache and
307 -wcache switches, which define the policy for reading from, and writing
308 to, the cache, respectively. One of four policies may be specified:
309 “public”, indicating that mhstore should make use of a publicly-acces‐
310 sible content cache; “private”, indicating that mhstore should make use
311 of the user's private content cache; “never”, indicating that mhstore
312 should never make use of caching; and, “ask”, indicating that mhstore
313 should ask the user.
314 There are two directories where contents may be cached: the profile
316 entry “nmh-cache” names a directory containing world-readable contents,
317 and, the profile entry “nmh-private-cache” names a directory containing
318 private contents. The former should be an absolute (rooted) directory
319 name.
320 For example,
322 nmh-cache: /tmp
324 might be used if you didn't care that the cache got wiped after each
326 reboot of the system. The latter is interpreted relative to the user's
327 nmh directory, if not rooted, e.g.,
328 nmh-private-cache: .cache
330 (which is the default value).
332 User Environment
334 Because the environment in which mhstore operates may vary for differ‐
335 ent machines, mhstore will look for the environment variable MHSTORE .
336 If present, this specifies the name of an additional user profile which
337 should be read. Hence, when a user logs in on a particular machine,
338 this environment variable should be set to refer to a file containing
339 definitions useful for that machine. Finally, mhstore will attempt to
340 consult
341 /etc/nmh/mhn.defaults
343 which is created automatically during nmh installation.
345 See "Profile Lookup" in mh-profile(5) for the profile search order, and
347 for how duplicate entries are treated.
348
350 Decoding RFC 2047-encoded file names
351 The improper RFC 2047 encoding of file name parameters can be replaced
352 with correct RFC 2231 encoding using mhfixmsg, either permanently or
353 ephemerally, e.g.,
354 mhfixmsg -outfile - | mhstore -auto -clobber ask -file -
356 The -clobberask is not necessary, though recommended to avoid silently
358 overwriting an existing file.
359
361 mhstore looks for additional profile files in multiple locations: abso‐
362 lute pathnames are accessed directly, tilde expansion is done on user‐
363 names, and files are searched for in the user's Mail directory as spec‐
364 ified in their profile. If not found there, the directory “/etc/nmh”
365 is checked.
366 $HOME/.mh_profile The user profile
368 $MHSTORE Additional profile entries
369 /etc/nmh/mhn.defaults System default MIME profile entries
370
372 Path: To determine the user's nmh directory
373 Current-Folder: To find the default current folder
374 nmh-access-ftp: Program to retrieve contents via FTP
375 nmh-access-url: Program to retrieve contents via HTTP
376 nmh-cache Public directory to store cached external contents
377 nmh-private-cache Personal directory to store cached external contents
378 nmh-storage Directory to store contents
379 mhstore-store-<type>*Template for storing contents
380
382 mhbuild(1), mhfixmsg(1), mhlist(1), mhshow(1), sendfiles(1)
383
385 `+folder' defaults to the current folder
386 `msgs' defaults to cur
387 `-noauto'
388 `-clobber always'
389 `-nocheck'
390 `-rcache ask'
391 `-wcache ask'
392 `-verbose'
393
395 If a folder is given, it will become the current folder. The last mes‐
396 sage selected will become the current message.
397
399 Partial messages contained within a multipart content are not reassem‐
400 bled.
401nmh-1.7.1 2015-02-06 MHSTORE(1)