1MHSTORE(1)                         [nmh-1.3]                        MHSTORE(1)
2
3
4

NAME

6       mhstore - store contents of MIME messages into files
7

SYNOPSIS

9       mhstore [+folder] [msgs] [-file file] [-part number] ...  [-type con‐
10            tent] ...  [-auto | -noauto] [-verbose | -noverbose] [-rcache pol‐
11            icy] [-wcache policy] [-check | -nocheck] [-version] [-help]
12

DESCRIPTION

14       The mhstore command allows you to store the contents of a collection of
15       MIME (multi-media) messages into files or other messages.
16
17       mhstore manipulates multi-media messages as specified in RFC-2045  thru
18       RFC-2049.
19
20       By  default,  mhstore  will  store all the parts of each message.  Each
21       part will be store in a separate file.  The header fields of  the  mes‐
22       sage  are  not  stored.  By using the -part and -type switches, you may
23       limit the scope of mhstore to particular subparts (of a multipart  con‐
24       tent) and/or particular content types.
25
26       The  option -file file directs mhstore to use the specified file as the
27       source message, rather than a message from a folder.   If  you  specify
28       this  file  as  “-”, then mhstore will accept the source message on the
29       standard input.  Note that the  file,  or  input  from  standard  input
30       should be a validly formatted message, just like any other nmh message.
31       It should NOT be in mail drop format (to convert a file  in  mail  drop
32       format to a folder of nmh messages, see inc(1)).
33
34       A part specification consists of a series of numbers separated by dots.
35       For example, in a multipart content containing three parts, these would
36       be  named as 1, 2, and 3, respectively.  If part 2 was also a multipart
37       content containing two parts, these would be  named  as  2.1  and  2.2,
38       respectively.   Note  that  the -part switch is effective for only mes‐
39       sages containing a multipart content.  If a message has some other kind
40       of  content,  or  if  the part is itself another multipart content, the
41       -part switch will not prevent the content from being acted upon.
42
43       A content specification consists of a content type and a subtype.   The
44       initial  list  of “standard” content types and subtypes can be found in
45       RFC-2046.
46
47       A list of commonly used contents is briefly reproduced here:
48
49            Type         Subtypes
50            ----         --------
51            text         plain, enriched
52            multipart    mixed, alternative, digest, parallel
53            message      rfc822, partial, external-body
54            application  octet-stream, postscript
55            image        jpeg, gif, png
56            audio        basic
57            video        mpeg
58
59       A legal MIME message must contain a subtype specification.
60
61       To specify a content, regardless of its subtype, just use the  name  of
62       the  content,  e.g.,  “audio”.  To specify a specific subtype, separate
63       the two with a slash, e.g., “audio/basic”.  Note that regardless of the
64       values  given  to the -type switch, a multipart content (of any subtype
65       listed above) is always acted upon.  Further note  that  if  the  -type
66       switch  is  used, and it is desirable to act on a message/external-body
67       content, then the -type switch  must  be  used  twice:  once  for  mes‐
68       sage/external-body and once for the content externally referenced.
69
70   Checking the Contents
71       The  -check switch tells mhstore to check each content for an integrity
72       checksum.  If a content has such a checksum (specified as a Content-MD5
73       header field), then mhstore will attempt to verify the integrity of the
74       content.
75
76   Storing the Contents
77       The mhstore will store the contents of the named messages  in  “native”
78       (decoded)  format.   Two  things  must  be determined: the directory to
79       store the content, and the filenames.  Files are written in the  direc‐
80       tory given by the “nmh-storage” profile entry, e.g.,
81
82            nmh-storage: /tmp
83
84       If this entry isn't present, the current working directory is used.
85
86       If  the  -auto  switch is given, then mhstore will check if the message
87       contains information indicating the filename that  should  be  used  to
88       store  the  content.   This  information  should  be  specified  as the
89       attribute “name=filename” in the “Content-Type” header for the  content
90       you  are  storing.  For security reasons, this filename will be ignored
91       if it begins with the character '/', '.', '|', or this  switch  is  not
92       the default, and it is recommended that you do NOT put the -auto switch
93       in your .mh_profile file.
94
95       If the -auto switch is not given (or is being ignored for security rea‐
96       sons)  then  mhstore  will look in the user's profile for a “formatting
97       string” to determine how  the  different  contents  should  be  stored.
98       First, mhstore will look for an entry of the form:
99
100            mhstore-store-<type>/<subtype>
101
102       to  determine the formatting string.  If this isn't found, mhstore will
103       look for an entry of the form:
104
105            mhstore-store-<type>
106
107       to determine the formatting string.
108
109       If the formatting string starts with a “+” character, then  content  is
110       stored in the named folder.  A formatting string consisting solely of a
111       “+” character is interpreted to be the current folder.
112
113       If the formatting string consists solely of a “-” character,  then  the
114       content is sent to the standard output.
115
116       If  the  formatting  string  starts with a '|', then the display string
117       will represent a command for mhstore to execute which should ultimately
118       store the content.  The content will be passed to the standard input of
119       the command.  Before the command is executed, mhstore  will  change  to
120       the appropriate directory, and any escapes (given below) in the display
121       string will be expanded.
122
123       Otherwise the formatting string will represent a pathname in  which  to
124       store  the  content.   If the formatting string starts with a '/', then
125       the content will be stored in the full path given, else the  file  name
126       will  be  relative to the value of “nmh-storage” or the current working
127       directory.  Any escapes (given below) will be expanded, except for  the
128       a-escape.
129
130       A  command  or  pathname  formatting  string  may contain the following
131       escapes.  If the content isn't part of  a  multipart  (of  any  subtype
132       listed above) content, the p-escapes are ignored.
133
134            %a  Parameters from Content-type  (only valid with command)
135            %m  Insert message number
136            %P  Insert part number with leading dot
137            %p  Insert part number without leading dot
138            %t  Insert content type
139            %s  Insert content subtype
140            %%  Insert character %
141
142       If no formatting string is found, mhstore will check to see if the con‐
143       tent is application/octet-stream with  parameter  “type=tar”.   If  so,
144       mhstore  will  choose  an  appropriate filename.  If the content is not
145       application/octet-stream, then mhstore will check to see if the content
146       is  a  message.   If  so,  mhstore  will  use the value “+”.  As a last
147       resort, mhstore will use the value “%m%P.%s”.
148
149       Example profile entries might be:
150
151            mhstore-store-text: %m%P.txt
152            mhstore-store-text: +inbox
153            mhstore-store-message/partial: +
154            mhstore-store-audio/basic: | raw2audio -e ulaw -s 8000 -c 1 > %m%P.au
155            mhstore-store-image/jpeg: %m%P.jpg
156            mhstore-store-application/PostScript: %m%P.ps
157
158   Reassembling Messages of Type message/partial
159       mhstore is also able to reassemble messages that have been  split  into
160       multiple messages of type “message/partial”.
161
162       When  asked  to  store  a content containing a partial message, mhstore
163       will try to locate all of the portions and  combine  them  accordingly.
164       The default is to store the combined parts as a new message in the cur‐
165       rent folder, although this can be changed using formatting  strings  as
166       discussed  above.   Thus,  if someone has sent you a message in several
167       parts (such as the output from sendfiles), you  can  easily  reassemble
168       them all into a single message in the following fashion:
169
170            % mhlist 5-8
171             msg part  type/subtype             size description
172               5       message/partial           47K part 1 of 4
173               6       message/partial           47K part 2 of 4
174               7       message/partial           47K part 3 of 4
175               8       message/partial           18K part 4 of 4
176            % mhstore 5-8
177            reassembling partials 5,6,7,8 to folder inbox as message 9
178            % mhlist -verbose 9
179             msg part  type/subtype             size description
180               9       application/octet-stream 118K
181                         (extract with uncompress | tar xvpf -)
182                         type=tar
183                         conversions=compress
184
185       This  will  store exactly one message, containing the sum of the parts.
186       It doesn't matter whether the partials are specified  in  order,  since
187       mhstore  will  sort the partials, so that they are combined in the cor‐
188       rect order.  But if mhstore can not locate every partial  necessary  to
189       reassemble the message, it will not store anything.
190
191   External Access
192       For  contents  of  type  message/external-body,  mhstore supports these
193       access-types:
194
195       ·   afs
196
197       ·   anon-ftp
198
199       ·   ftp
200
201       ·   local-file
202
203       ·   mail-server
204
205       For the “anon-ftp” and “ftp” access types, mhstore will  look  for  the
206       “nmh-access-ftp” profile entry, e.g.,
207
208            nmh-access-ftp: myftp.sh
209
210       to  determine  the  pathname of a program to perform the FTP retrieval.
211       This program is invoked with these arguments:
212
213            domain name of FTP-site
214            username
215            password
216            remote directory
217            remote filename
218            local filename
219            “ascii” or “binary”
220
221       The program should terminate  with  an  exit  status  of  zero  if  the
222       retrieval is successful, and a non-zero exit status otherwise.
223
224       If  this entry is not provided, then mhstore will use a simple built-in
225       FTP client to perform the retrieval.
226
227   The Content Cache
228       When mhstore encounters an external content containing a  “Content-ID:”
229       field, and if the content allows caching, then depending on the caching
230       behavior of mhstore, the content might be read from  or  written  to  a
231       cache.
232
233       The  caching  behavior  of  mhstore  is controlled with the -rcache and
234       -wcache switches, which define the policy for reading from, and writing
235       to,  the  cache,  respectively.  One of four policies may be specified:
236       “public”, indicating that mhstore should  make  use  of  a  publically-
237       accessible  content  cache;  “private”,  indicating that mhstore should
238       make use of the user's private content cache; “never”, indicating  that
239       mhstore  should  never make use of caching; and, “ask”, indicating that
240       mhstore should ask the user.
241
242       There are two directories where contents may  be  cached:  the  profile
243       entry “nmh-cache” names a directory containing world-readable contents,
244       and, the profile entry “nmh-private-cache” names a directory containing
245       private  contents.  The former should be an absolute (rooted) directory
246       name.
247
248       For example,
249
250            nmh-cache: /tmp
251
252       might be used if you didn't care that the cache got  wiped  after  each
253       reboot of the system.  The latter is interpreted relative to the user's
254       nmh directory, if not rooted, e.g.,
255
256            nmh-private-cache: .cache
257
258       (which is the default value).
259
260   User Environment
261       Because the display environment in which mhstore operates may vary  for
262       different  machines,  mhstore will look for the environment variable If
263       present, this specifies the name of an additional  user  profile  which
264       should  be  read.   Hence, when a user logs in on a particular machine,
265       this environment variable should be set to refer to a  file  containing
266       definitions  useful for that machine.  Finally, mhstore will attempt to
267       consult one other additional user profile, e.g.,
268
269            /etc/nmh/mhn.defaults
270
271       which is created automatically during nmh installation.
272
273

FILES

275       $HOME/.mh_profile          The user profile
276       $MHSTORE                   Additional profile entries
277       /etc/nmh/mhn.defaults      System default MIME profile entries
278
279

PROFILE COMPONENTS

281       Path:                To determine the user's nmh directory
282       Current-Folder:      To find the default current folder
283       nmh-access-ftp:      Program to retrieve contents via FTP
284       nmh-cache            Public directory to store cached external contents
285       nmh-private-cache    Personal directory to store cached external contents
286       nmh-storage          Directory to store contents
287       mhstore-store-<type>*Template for storing contents
288
289

SEE ALSO

291       mhbuild(1), mhlist(1), mhshow(1), sendfiles(1)
292
293

DEFAULTS

295       `+folder' defaults to the current folder
296       `msgs' defaults to cur
297       `-noauto'
298       `-nocheck'
299       `-rcacheask'
300       `-wcacheask'
301       `-noverbose'
302
303

CONTEXT

305       If a folder is given, it will become the current folder.  The last mes‐
306       sage selected will become the current message.
307
308

BUGS

310       Partial  messages contained within a multipart content are not reassem‐
311       bled.
312
313
314
315MH.6.8                            1 June 2008                       MHSTORE(1)
Impressum