1MHSTORE(1)                  General Commands Manual                 MHSTORE(1)
2
3
4

NAME

6       mhstore - store contents of nmh MIME messages into files
7

SYNOPSIS

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

DESCRIPTION

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
19       mhstore manipulates multi-media messages as specified in  RFC  2045  to
20       RFC 2049.
21
22       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
28       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
36       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
45       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
51       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
57       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
61       A list of commonly used contents is briefly reproduced here:
62
63            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
73       A legal MIME message must contain a subtype specification.
74
75       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
84       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
93       The -noprefer switch will cancel any previous -prefer switches.
94
95   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
101   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
107            nmh-storage: /tmp
108
109       If this entry isn't present, the current working directory is used.
110
111       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
124       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
129            mhstore-store-<type>/<subtype>
130
131       to determine the formatting string.  If this isn't found, mhstore  will
132       look for an entry of the form:
133
134            mhstore-store-<type>
135
136       to determine the formatting string.
137
138       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
142       If  the  formatting string consists solely of a “-” character, then the
143       content is sent to the standard output.
144
145       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
153       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
161       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
165            %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
173       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
180       Example profile entries might be:
181
182            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
189       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
193   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
198            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
205       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
211       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
221   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
225       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
233            % 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
248       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
254   External Access
255       For contents of  type  message/external-body,  mhstore  supports  these
256       access-types:
257
258       ·   afs
259
260       ·   anon-ftp
261
262       ·   ftp
263
264       ·   local-file
265
266       ·   mail-server
267
268       ·   url
269
270       For  the  “anon-ftp”  and “ftp” access types, mhstore will look for the
271       “nmh-access-ftp” profile entry, e.g.,
272
273            nmh-access-ftp: myftp.sh
274
275       to determine the pathname of a program to perform  the  FTP  retrieval.
276       This program is invoked with these arguments:
277
278            domain name of FTP-site
279            username
280            password
281            remote directory
282            remote filename
283            local filename
284            “ascii” or “binary”
285
286       The  program  should  terminate  with  an  exit  status  of zero if the
287       retrieval is successful, and a non-zero exit status otherwise.
288
289       For the “url” access types, mhstore will look for the  “nmh-access-url”
290       profile entry, e.g.,
291
292            nmh-access-url: curl -L
293
294       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
300   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
306       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
315       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
321       For example,
322
323            nmh-cache: /tmp
324
325       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
329            nmh-private-cache: .cache
330
331       (which is the default value).
332
333   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
342            /etc/nmh/mhn.defaults
343
344       which is created automatically during nmh installation.
345
346       See "Profile Lookup" in mh-profile(5) for the profile search order, and
347       for how duplicate entries are treated.
348

EXAMPLES

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
355              mhfixmsg -outfile - | mhstore -auto -clobber ask -file -
356
357       The -clobberask is not necessary, though recommended to avoid  silently
358       overwriting an existing file.
359

FILES

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
367       $HOME/.mh_profile          The user profile
368       $MHSTORE                   Additional profile entries
369       /etc/nmh/mhn.defaults      System default MIME profile entries
370

PROFILE COMPONENTS

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

SEE ALSO

382       mhbuild(1), mhfixmsg(1), mhlist(1), mhshow(1), sendfiles(1)
383

DEFAULTS

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

CONTEXT

395       If a folder is given, it will become the current folder.  The last mes‐
396       sage selected will become the current message.
397

BUGS

399       Partial messages contained within a multipart content are not  reassem‐
400       bled.
401
402
403
404nmh-1.7.1                         2015-02-06                        MHSTORE(1)
Impressum