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] [-verbose | -noverbose]
13
15 The mhstore command allows you to store the contents of a collection of
16 MIME (multi-media) messages into files or other messages.
17 mhstore manipulates multi-media messages as specified in RFC 2045 to
19 RFC 2049.
20 By default, mhstore will store all the parts of each message. Each
22 part will be stored in a separate file. The header fields of the mes‐
23 sage are not stored. By using the -part, -type, and -prefer switches,
24 you may limit and reorder the set of parts to be stored, based on part
25 number and/or content type.
26 The -file file switch directs mhstore to use the specified file as the
28 source message, rather than a message from a folder. If you specify
29 this file as “-”, then mhstore will accept the source message on the
30 standard input. Note that the file, or input from standard input,
31 should be a validly formatted message, just like any other nmh message.
32 It should not be in mail drop format (to convert a file in mail drop
33 format to a folder of nmh messages, see inc(1)).
34 A part specification consists of a series of numbers separated by dots.
36 For example, in a multipart content containing three parts, these would
37 be named as 1, 2, and 3, respectively. If part 2 was also a multipart
38 content containing two parts, these would be named as 2.1 and 2.2, re‐
39 spectively. Note that the -part switch is effective only for messages
40 containing a multipart content. If a message has some other kind of
41 content, or if the part is itself another multipart content, the -part
42 switch will not prevent the content from being acted upon.
43 The -type switch can also be used to restrict (or, when used in con‐
45 junction with -part, to further restrict) the selection of parts ac‐
46 cording to content type. One or more -type switches part will only se‐
47 lect the first match from a multipart/alternative, even if there is
48 more than one subpart that matches (one of) the given content type(s).
49 Using either -part or -type switches alone will cause either to select
51 the part(s) they match. Using them together will select only the
52 part(s) matched by both (sets of) switches. In other words, the result
53 is the intersection, and not the union, of their separate match re‐
54 sults.
55 A content specification consists of a content type and a subtype. The
57 initial list of “standard” content types and subtypes can be found in
58 RFC 2046.
59 A list of commonly used contents is briefly reproduced here:
61 Type Subtypes
63 ---- --------
64 text plain, enriched
65 multipart mixed, alternative, digest, parallel
66 message rfc822, external-body
67 application octet-stream, postscript
68 image jpeg, gif, png
69 audio basic
70 video mpeg
71 A legal MIME message must contain a subtype specification.
73 To specify a content, regardless of its subtype, just use the name of
75 the content, e.g., “audio”. To specify a specific subtype, separate
76 the two with a slash, e.g., “audio/basic”. Note that regardless of the
77 values given to the -type switch, a multipart content (of any subtype
78 listed above) is always acted upon. Further note that if the -type
79 switch is used, and it is desirable to act on a message/external-body
80 content, then the -type switch must be used twice: once for message/ex‐
81 ternal-body and once for the content externally referenced.
82 The -prefer switch will alter the part-ordering of multipart/alterna‐
84 tive MIME sections in order to override the sender-imposed default or‐
85 dering. The -prefer switch is functionally most important for mhshow,
86 but is also implemented in mhlist and mhstore to make common part-num‐
87 bering possible across all three programs. The last of multiple -pre‐
88 fer switches will have the highest priority. This allows the command
89 line switches to override profile entries. See mhlist(1) and mhshow(1)
90 for more information on -prefer.
91 The -noprefer switch will cancel any previous -prefer switches.
93 Storing the Contents
95 mhstore will store the contents of the named messages in “native” (de‐
96 coded) format. Two things must be determined: the directory in which
97 to store the content, and the filenames. Files are written in the di‐
98 rectory given by the “nmh-storage” profile entry, e.g.,
99 nmh-storage: /tmp
101 If this entry isn't present, the current working directory is used.
103 If the -outfile switch is given, its argument is used for the filename
105 to store all of the content, with “-” indicating standard output. If
106 the -auto switch is given, then mhstore will check if the message con‐
107 tains information indicating the filename that should be used to store
108 the content. This information should be specified as the “filename”
109 attribute in the “Content-Disposition” header or as the “name” attri‐
110 bute in the “Content-Type” header for the content you are storing. For
111 security reasons, this filename will be ignored if it begins with the
112 character `/', `.', `|', or `!', or if it contains the character `%'.
113 We also recommend using a “nmh-storage” profile entry or a -clobber
114 switch setting other than the default of “always” to avoid overwriting
115 existing files.
116 If the -auto switch is not given (or is being ignored for security rea‐
118 sons) then mhstore will look in the user's profile for a “formatting
119 string” to determine how the different contents should be stored.
120 First, mhstore will look for an entry of the form:
121 mhstore-store-<type>/<subtype>
123 to determine the formatting string. If this isn't found, mhstore will
125 look for an entry of the form:
126 mhstore-store-<type>
128 to determine the formatting string.
130 If the formatting string starts with a “+” character, then content is
132 stored in the named folder. A formatting string consisting solely of a
133 “+” character is interpreted to be the current folder.
134 If the formatting string consists solely of a “-” character, then the
136 content is sent to the standard output.
137 If the formatting string starts with a `|', then it represents a com‐
139 mand for mhstore to execute which should ultimately store the content.
140 The content will be passed to the standard input of the command. Be‐
141 fore the command is executed, mhstore will change to the appropriate
142 directory, and any escapes (given below) in the formatting string will
143 be expanded. The use of the “%a” sequence is not recommended because
144 the user has no control over the Content-Type parameter data.
145 Otherwise, the formatting string will represent a pathname in which to
147 store the content. If the formatting string starts with a `/', then
148 the content will be stored in the full path given, else the file name
149 will be relative to the value of “nmh-storage” or the current working
150 directory. Any escapes (given below) will be expanded, except for the
151 a-escape. Note that if “nmh-storage” is not an absolute path, it will
152 be relative to the folder that contains the message(s).
153 A command or pathname formatting string may contain the following es‐
155 capes. If the content isn't part of a multipart (of any subtype listed
156 above) content, the p-escapes are ignored.
157 %a Parameters from Content-Type (only valid with command)
159 %m Insert message number
160 %P Insert part number with leading dot
161 %p Insert part number without leading dot
162 %t Insert content type
163 %s Insert content subtype
164 %% Insert character %
165 If no formatting string is found, mhstore will check to see if the con‐
167 tent is application/octet-stream with parameter “type=tar”. If so, mh‐
168 store will choose an appropriate filename. If the content is not ap‐
169 plication/octet-stream, then mhstore will check to see if the content
170 is a message. If so, mhstore will use the value “+”. As a last re‐
171 sort, mhstore will use the value “%m%P.%s”.
172 Example profile entries might be:
174 mhstore-store-text: %m%P.txt
176 mhstore-store-text: +inbox
177 mhstore-store-audio/basic: | raw2audio -e ulaw -s 8000 -c 1 > %m%P.au
178 mhstore-store-image/jpeg: %m%P.jpg
179 mhstore-store-application/PostScript: %m%P.ps
180 The -verbose switch directs mhstore to print out the names of files
182 that it stores. For backward compatibility, it is the default. The
183 -noverbose switch suppresses these printouts.
184 Overwriting Existing Files
186 The -clobber switch controls whether mhstore should overwrite existing
187 files. The allowed values for this switch and corresponding behavior
188 when mhstore encounters an existing file are:
189 always Overwrite existing file (default)
191 auto Create new file of form name-n.extension
192 suffix Create new file of form name.extension.n
193 ask Prompt the user to specify whether or not to overwrite
194 the existing file
195 never Do not overwrite existing file
196 With auto and suffix, n is the lowest unused number, starting from one,
198 in the same form. If a filename does not have an extension (following
199 a `.'), then auto and suffix create a new file of the form name-n and
200 name.n, respectively. With never and ask, the exit status of mhstore
201 will be the number of files that were requested but not stored.
202 With ask, if standard input is connected to a terminal, the user is
204 prompted to respond yes, no, or rename, to whether the file should be
205 overwritten. The responses can be abbreviated. If the user responds
206 with rename, then mhstore prompts the user for the name of the new file
207 to be created. If it is a relative path name (does not begin with
208 `/'), then it is relative to the current directory. If it is an abso‐
209 lute or relative path to a directory that does not exist, the user will
210 be prompted whether to create the directory. If standard input is not
211 connected to a terminal, ask behaves the same as always.
212 External Access
214 For contents of type message/external-body, mhstore supports these ac‐
215 cess-types:
216 • afs
218 • anon-ftp
220 • ftp
222 • local-file
224 • mail-server
226 • url
228 For the “anon-ftp” and “ftp” access types, mhstore will look for the
230 “nmh-access-ftp” profile entry, e.g.,
231 nmh-access-ftp: myftp.sh
233 to determine the pathname of a program to perform the FTP retrieval.
235 This program is invoked with these arguments:
236 domain name of FTP-site
238 username
239 password
240 remote directory
241 remote filename
242 local filename
243 “ascii” or “binary”
244 The program should terminate with an exit status of zero if the re‐
246 trieval is successful, and a non-zero exit status otherwise.
247 For the “url” access types, mhstore will look for the “nmh-access-url”
249 profile entry, e.g.,
250 nmh-access-url: curl -L
252 to determine the program to use to perform the HTTP retrieval. This
254 program is invoked with one argument: the URL of the content to re‐
255 trieve. The program should write the content to standard out, and
256 should terminate with a status of zero if the retrieval is successful
257 and a non-zero exit status otherwise.
258 User Environment
260 Because the environment in which mhstore operates may vary for differ‐
261 ent machines, mhstore will look for the environment variable MHSTORE .
262 If present, this specifies the name of an additional user profile which
263 should be read. Hence, when a user logs in on a particular machine,
264 this environment variable should be set to refer to a file containing
265 definitions useful for that machine. Finally, mhstore will attempt to
266 consult
267 /etc/nmh/mhn.defaults
269 which is created automatically during nmh installation.
271 See "Profile Lookup" in mh-profile(5) for the profile search order, and
273 for how duplicate entries are treated.
274
276 Decoding RFC 2047-encoded file names
277 The improper RFC 2047 encoding of file name parameters can be replaced
278 with correct RFC 2231 encoding using mhfixmsg, either permanently or
279 ephemerally, e.g.,
280 mhfixmsg -outfile - | mhstore -auto -clobber ask -file -
282 The -clobberask is not necessary, though recommended to avoid silently
284 overwriting an existing file.
285
287 mhstore looks for additional profile files in multiple locations: abso‐
288 lute pathnames are accessed directly, tilde expansion is done on user‐
289 names, and files are searched for in the user's Mail directory as spec‐
290 ified in their profile. If not found there, the directory “/etc/nmh”
291 is checked.
292 $HOME/.mh_profile The user profile
294 $MHSTORE Additional profile entries
295 /etc/nmh/mhn.defaults System default MIME profile entries
296
298 Path: To determine the user's nmh directory
299 Current-Folder: To find the default current folder
300 nmh-access-ftp: Program to retrieve contents via FTP
301 nmh-access-url: Program to retrieve contents via HTTP
302 nmh-storage Directory to store contents
303 mhstore-store-<type>*Template for storing contents
304
306 mhbuild(1), mhfixmsg(1), mhlist(1), mhshow(1), sendfiles(1)
307
309 `+folder' defaults to the current folder
310 `msgs' defaults to cur
311 `-noauto'
312 `-clobber always'
313 `-verbose'
314
316 If a folder is given, it will become the current folder. The last mes‐
317 sage selected will become the current message.
318
320 Partial messages contained within a multipart content are not reassem‐
321 bled.
322nmh-1.8 2015-02-06 MHSTORE(1)