indentation fix in uip/pick.c
[mmh] / man / mhstore.man1
1 .\"
2 .\" %nmhwarning%
3 .\"
4 .TH MHSTORE %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
5 .SH NAME
6 mhstore \- store contents of MIME messages into files
7 .SH SYNOPSIS
8 .HP 5
9 .na
10 .B mhstore
11 .RI [ +folder ]
12 .RI [ msgs ]
13 .RB [ \-file
14 .IR file ]
15 .RB [ \-part
16 .IR number ]
17 \&...
18 .RB [ \-type
19 .IR content ]
20 \&...
21 .RB [ \-auto " | " \-noauto ]
22 .RB [ \-Version ]
23 .RB [ \-help ]
24 .ad
25 .SH DESCRIPTION
26 The
27 .B mhstore
28 command allows you to store the contents of a
29 collection of MIME (multi-media) messages into files or other
30 messages.
31 .PP
32 .B mhstore
33 manipulates multi-media messages as specified in
34 RFC\-2045 thru RFC\-2049.
35 .PP
36 By default,
37 .B mhstore
38 will store all the parts of each message.
39 Each part will be store in a separate file.  The header fields of
40 the message are not stored.  By using the
41 .B \-part
42 and
43 .B \-type
44 switches, you may limit the scope of
45 .B mhstore
46 to particular
47 subparts (of a multipart content) and/or particular content types.
48 .PP
49 The option
50 .B \-file
51 .I file
52 directs
53 .B mhstore
54 to use the specified
55 file as the source message, rather than a message from a folder.
56 If you specify this file as `-', then
57 .B mhstore
58 will
59 accept the source message on the standard input.  Note that the
60 file, or input from standard input should be a validly formatted
61 message, just like any other
62 .B mh
63 message.  It should
64 .B NOT
65 be in mail drop format (to convert a file in mail drop format to
66 a folder of
67 .B mh
68 messages, see
69 .BR inc (1)).
70 .PP
71 A part specification consists of a series of numbers separated by
72 dots.  For example, in a multipart content containing three parts,
73 these would be named as 1, 2, and 3, respectively.  If part 2 was
74 also a multipart content containing two parts, these would be named
75 as 2.1 and 2.2, respectively.  Note that the
76 .B \-part
77 switch is
78 effective for only messages containing a multipart content.  If a
79 message has some other kind of content, or if the part is itself
80 another multipart content, the
81 .B \-part
82 switch will not prevent
83 the content from being acted upon.
84 .PP
85 A content specification consists of a content type and a subtype.
86 The initial list of `standard' content types and subtypes
87 can be found in RFC\-2046.
88 .PP
89 A list of commonly used contents is briefly reproduced here:
90 .PP
91 .RS 5
92 .nf
93 .ta \w'application  'u
94 Type    Subtypes
95 ----    --------
96 text    plain, enriched
97 multipart       mixed, alternative, digest, parallel
98 message rfc822, partial, external-body
99 application     octet-stream, postscript
100 image   jpeg, gif, png
101 audio   basic
102 video   mpeg
103 .fi
104 .RE
105 .PP
106 A legal MIME message must contain a subtype specification.
107 .PP
108 To specify a content, regardless of its subtype, just use the name
109 of the content, e.g., `audio'.  To specify a specific
110 subtype, separate the two with a slash, e.g., `audio/basic'.
111 Note that regardless of the values given to the
112 .B \-type
113 switch,
114 a multipart content (of any subtype listed above) is always acted
115 upon.
116 .SS "Storing the Contents"
117 The
118 .B mhstore
119 will store the contents of the named messages in
120 `native' (decoded) format.  Two things must be determined:
121 the directory to store the content, and the filenames.
122 .PP
123 By default (or if the
124 .B \-auto
125 switch is given),
126 .B mhstore
127 uses filename information, contained in the message, if available.
128 (This information should be specified
129 as the attribute `name=filename' in the `Content-Type' header
130 for the content you are storing.)
131 Only the basename of this filename is considered.
132 If it begins with the character '.', '|', or '!',
133 or if it contains the character '%', automatic naming won't happen for
134 security reasons. (See below for the fall-back.)
135 .PP
136 Files are
137 written in the directory given by the `nmh-storage' profile
138 entry, e.g.,
139 .PP
140 .RS 5
141 nmh-storage: /tmp
142 .RE
143 .PP
144 (Note that `nmh-storage' is relative to the folder that contains
145 the message.)
146 If this entry isn't present,
147 the current working directory is used.
148 Attachments will get stored in either the `nmh-storage' or the current working
149 directory \(en in no case elsewhere.
150 Existing files get silently overwritten.
151 .PP
152 If the
153 .B \-noauto
154 switch is given (or a filename is being ignored for security reasons) then
155 .B mhstore
156 will look in the user's profile for a
157 `formatting string' to determine how the different contents
158 should be stored.  First,
159 .B mhstore
160 will look for an entry of
161 the form:
162 .PP
163 .RS 5
164 mhstore-store-<type>/<subtype>
165 .RE
166 .PP
167 to determine the formatting string.  If this isn't found,
168 .B mhstore
169 will look for an entry of the form:
170 .PP
171 .RS 5
172 mhstore-store-<type>
173 .RE
174 .PP
175 to determine the formatting string.
176 .PP
177 If the formatting string starts with a `+' character, then
178 content is stored in the named folder.  A formatting string consisting
179 solely of a `+' character is interpreted to be the current
180 folder.
181 .PP
182 If the formatting string consists solely of a `\-' character,
183 then the content is sent to the standard output.
184 .PP
185 If the formatting string starts with a '|', then the display string
186 will represent a command for
187 .B mhstore
188 to execute which should
189 ultimately store the content.  The content will be passed to the
190 standard input of the command.  Before the command is executed,
191 .B mhstore
192 will change to the appropriate directory, and any
193 escapes (given below) in the display string will be expanded.
194 .PP
195 Otherwise the formatting string will represent a pathname in which
196 to store the content.  If the formatting string starts with a '/',
197 then the content will be stored in the full path given, else the
198 file name will be relative to either the value of `nmh-storage',
199 if set, or the current working directory.
200 Existing files get silently overwritten.
201 .PP
202 A command or pathname formatting string may contain the following
203 escapes.  If the content isn't part of a multipart (of any subtype
204 listed above) content, the p-escapes are ignored.
205 .PP
206 .RS 5
207 .nf
208 .ta \w'%P  'u
209 %a      Parameters from Content-type  (only valid with command)
210 %m      Insert message number
211 %P      Insert part number with leading dot
212 %p      Insert part number without leading dot
213 %t      Insert content type
214 %s      Insert content subtype
215 %%      Insert character %
216 .fi
217 .RE
218 .PP
219 If no formatting string is found,
220 .B mhstore
221 will check to see if the content is a message.  If
222 so,
223 .B mhstore
224 will use the value `+'.  As a last resort,
225 .B mhstore
226 will use the value `%m%P.%s'.
227 .PP
228 Example profile entries might be:
229 .PP
230 .RS 5
231 .nf
232 mhstore-store-text: %m%P.txt
233 mhstore-store-text: +inbox
234 mhstore-store-message/partial: +
235 mhstore-store-audio/basic: | raw2audio \-e ulaw \-s 8000 \-c 1 > %m%P.au
236 mhstore-store-image/jpeg: %m%P.jpg
237 mhstore-store-application/PostScript: %m%P.ps
238 .fi
239 .RE
240 .PP
241 .SS "Reassembling Messages of Type message/partial"
242 .B mhstore
243 is also able to reassemble messages that have been
244 split into multiple messages of type `message/partial'.
245 .PP
246 When asked to store a content containing a partial message,
247 .B mhstore
248 will try to locate all of the portions and combine
249 them accordingly.  The default is to store the combined parts as
250 a new message in the current folder, although this can be changed
251 using formatting strings as discussed above.  Thus, if someone has
252 sent you a message in several parts (such as the output from
253 .BR sendfiles ),
254 you can easily reassemble them all into a single
255 message in the following fashion:
256 .PP
257 .RS 5
258 .nf
259 % mhlist 5-8
260  msg part  type/subtype             size description
261    5       message/partial           47K part 1 of 4
262    6       message/partial           47K part 2 of 4
263    7       message/partial           47K part 3 of 4
264    8       message/partial           18K part 4 of 4
265 % mhstore 5-8
266 reassembling partials 5,6,7,8 to folder inbox as message 9
267 % mhlist 9
268  msg part  type/subtype             size description
269    9       application/octet-stream 118K
270              (extract with uncompress | tar xvpf -)
271              type=tar
272              conversions=compress
273 .fi
274 .RE
275 .PP
276 This will store exactly one message, containing the sum of the
277 parts.  It doesn't matter whether the partials are specified in
278 order, since
279 .B mhstore
280 will sort the partials, so that they
281 are combined in the correct order.  But if
282 .B mhstore
283 can not
284 locate every partial necessary to reassemble the message, it will
285 not store anything.
286 .RE
287 .SS "External Access"
288 .B Mhstore
289 does not automatically retrieve message/external-body parts (anymore),
290 but prints the relevant information to enable the user to retrieve
291 the files manually.
292 .SS "User Environment"
293 Because the display environment in which
294 .B mhstore
295 operates may vary for
296 different machines,
297 .B mhstore
298 will look for the environment variable
299 .BR $MHSTORE .
300 If present, this specifies the name of an additional
301 user profile which should be read.  Hence, when a user logs in on a
302 particular machine, this environment variable should be set to
303 refer to a file containing definitions useful for that machine.
304 Finally,
305 .B mhstore
306 will attempt to consult one other additional
307 user profile, e.g.,
308 .PP
309 .RS 5
310 %etcdir%/mhn.defaults
311 .RE
312 .PP
313 which is created automatically during
314 .B mmh
315 installation.
316
317 .SH FILES
318 .fc ^ ~
319 .nf
320 .ta \w'%etcdir%/ExtraBigFileName  'u
321 ^$HOME/.mmh/profile~^The user profile
322 ^$MHSTORE~^Additional profile entries
323 ^%etcdir%/mhn.defaults~^System default MIME profile entries
324 .fi
325
326 .SH "PROFILE COMPONENTS"
327 .fc ^ ~
328 .nf
329 .ta 2.4i
330 .ta \w'ExtraBigProfileName  'u
331 ^Path:~^To determine the user's mail storage
332 ^Current\-Folder:~^To find the default current folder
333 ^nmh-storage~^Directory to store contents
334 ^mhstore-store-<type>*~^Template for storing contents
335 .fi
336
337 .SH "SEE ALSO"
338 mhbuild(1), mhlist(1), show(1), sendfiles(1)
339
340 .SH DEFAULTS
341 .nf
342 .RB ` +folder "' defaults to the current folder"
343 .RB ` msgs "' defaults to the current message"
344 .RB ` \-auto '
345
346 .SH CONTEXT
347 If a folder is given, it will become the current folder.  The last
348 message selected will become the current message.
349
350 .SH BUGS
351 Partial messages contained within a multipart content are not reassembled.
352 .PP
353 Existing files get silently overwritten.