Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
MHSTORE(1)		    General Commands Manual		    MHSTORE(1)

       mhstore - store contents	of nmh MIME messages into files

       mhstore [-help] [-version] [+folder] [msgs] [-file file]	[-outfile out-
	    file] [-part number] ...  [-type content] ...  [-prefer content]
	    ...	 [-noprefer] [-auto | -noauto] [-clobber always	| auto | suf-
	    fix	| ask |	never] [-rcache	policy]	[-wcache policy] [-check |
	    -nocheck] [-verbose	| -noverbose]

       The mhstore command allows you to store the contents of a collection of
       MIME (multi-media) messages into	files or other messages.

       mhstore manipulates multi-media messages	as specified in	 RFC  2045  to
       RFC 2049.

       By  default,  mhstore  will  store all the parts	of each	message.  Each
       part will be stored in a	separate file.	The header fields of the  mes-
       sage  are not stored.  By using the -part, -type, and -prefer switches,
       you may limit and reorder the set of parts to be	stored,	based on  part
       number and/or content type.

       The  -file file switch directs mhstore to use the specified file	as the
       source message, rather than a message from a folder.   If  you  specify
       this  file  as  "-", then mhstore will accept the source	message	on the
       standard	input.	Note that the file,  or	 input	from  standard	input,
       should be a validly formatted message, just like	any other nmh message.
       It should not be	in mail	drop format (to	convert	a file	in  mail  drop
       format to a folder of nmh messages, see inc(1)).

       A part specification consists of	a series of numbers separated by dots.
       For example, in a multipart content containing three parts, these would
       be  named as 1, 2, and 3, respectively.	If part	2 was also a multipart
       content containing two parts, these would be named as 2.1 and 2.2,  re-
       spectively.   Note that the -part switch	is effective only for messages
       containing a multipart content.	If a message has some  other  kind  of
       content,	 or if the part	is itself another multipart content, the -part
       switch will not prevent the content from	being acted upon.

       The -type switch	can also be used to restrict (or, when	used  in  con-
       junction	 with  -part,  to further restrict) the	selection of parts ac-
       cording to content type.	 One or	more -type switches part will only se-
       lect  the  first	 match	from a multipart/alternative, even if there is
       more than one subpart that matches (one of) the given content type(s).

       Using either -part or -type switches alone will cause either to	select
       the  part(s)  they  match.   Using  them	 together will select only the
       part(s) matched by both (sets of) switches.  In other words, the	result
       is  the	intersection,  and  not	the union, of their separate match re-

       A content specification consists	of a content type and a	subtype.   The
       initial	list  of "standard" content types and subtypes can be found in
       RFC 2046.

       A list of commonly used contents	is briefly reproduced here:

	    Type	 Subtypes
	    ----	 --------
	    text	 plain,	enriched
	    multipart	 mixed,	alternative, digest, parallel
	    message	 rfc822, partial, external-body
	    application	 octet-stream, postscript
	    image	 jpeg, gif, png
	    audio	 basic
	    video	 mpeg

       A legal MIME message must contain a subtype specification.

       To specify a content, regardless	of its subtype,	just use the  name  of
       the  content,  e.g.,  "audio".  To specify a specific subtype, separate
       the two with a slash, e.g., "audio/basic".  Note	that regardless	of the
       values  given  to the -type switch, a multipart content (of any subtype
       listed above) is	always acted upon.  Further note  that	if  the	 -type
       switch  is  used, and it	is desirable to	act on a message/external-body
       content,	then the -type switch must be used twice: once for message/ex-
       ternal-body and once for	the content externally referenced.

       The  -prefer  switch will alter the part-ordering of multipart/alterna-
       tive MIME sections in order to override the sender-imposed default  or-
       dering.	 The -prefer switch is functionally most important for mhshow,
       but is also implemented in mhlist and mhstore to	make common  part-num-
       bering  possible	across all three programs.  The	last of	multiple -pre-
       fer switches will have the highest priority.  This allows  the  command
       line switches to	override profile entries.  See mhlist(1) and mhshow(1)
       for more	information on -prefer.

       The -noprefer switch will cancel	any previous -prefer switches.

   Checking the	Contents
       The -check switch tells mhstore to check	each content for an  integrity
       checksum.  If a content has such	a checksum (specified as a Content-MD5
       header field), then mhstore will	attempt	to verify the integrity	of the

   Storing the Contents
       mhstore	will store the contents	of the named messages in "native" (de-
       coded) format.  Two things must be determined: the directory  in	 which
       to  store the content, and the filenames.  Files	are written in the di-
       rectory given by	the "nmh-storage" profile entry, e.g.,

	    nmh-storage: /tmp

       If this entry isn't present, the	current	working	directory is used.

       If the -outfile switch is given,	its argument is	used for the  filename
       to  store  all of the content, with "-" indicating standard output.  If
       the -auto switch	is given, then mhstore will check if the message  con-
       tains  information indicating the filename that should be used to store
       the content.  This information should be	specified  as  the  "filename"
       attribute  in  the "Content-Disposition"	header or as the "name"	attri-
       bute in the "Content-Type" header for the content you are storing.  For
       security	 reasons,  this	filename will be ignored if it begins with the
       character '/', '.', '|',	or '!',	or if it contains the  character  '%'.
       We  also	 recommend  using  a "nmh-storage" profile entry or a -clobber
       switch setting other than the default of	"always" to avoid  overwriting
       existing	files.

       If the -auto switch is not given	(or is being ignored for security rea-
       sons) then mhstore will look in the user's profile  for	a  "formatting
       string"	to  determine  how  the	 different  contents should be stored.
       First, mhstore will look	for an entry of	the form:


       to determine the	formatting string.  If this isn't found, mhstore  will
       look for	an entry of the	form:


       to determine the	formatting string.

       If  the	formatting string starts with a	"+" character, then content is
       stored in the named folder.  A formatting string	consisting solely of a
       "+" character is	interpreted to be the current folder.

       If  the	formatting string consists solely of a "-" character, then the
       content is sent to the standard output.

       If the formatting string	starts with a '|', then	it represents  a  com-
       mand  for mhstore to execute which should ultimately store the content.
       The content will	be passed to the standard input	of the	command.   Be-
       fore  the  command  is executed,	mhstore	will change to the appropriate
       directory, and any escapes (given below)	in the formatting string  will
       be  expanded.   The use of the "%a" sequence is not recommended because
       the user	has no control over the	Content-Type parameter data.

       Otherwise, the formatting string	will represent a pathname in which  to
       store  the  content.   If the formatting	string starts with a '/', then
       the content will	be stored in the full path given, else the  file  name
       will  be	 relative to the value of "nmh-storage"	or the current working
       directory.  Any escapes (given below) will be expanded, except for  the
       a-escape.   Note	that if	"nmh-storage" is not an	absolute path, it will
       be relative to the folder that contains the message(s).

       A command or pathname formatting	string may contain the	following  es-
       capes.  If the content isn't part of a multipart	(of any	subtype	listed
       above) content, the p-escapes are ignored.

	    %a	Parameters from	Content-Type  (only valid with command)
	    %m	Insert message number
	    %P	Insert part number with	leading	dot
	    %p	Insert part number without leading dot
	    %t	Insert content type
	    %s	Insert content subtype
	    %%	Insert character %

       If no formatting	string is found, mhstore will check to see if the con-
       tent is application/octet-stream	with parameter "type=tar".  If so, mh-
       store will choose an appropriate	filename.  If the content is  not  ap-
       plication/octet-stream,	then  mhstore will check to see	if the content
       is a message.  If so, mhstore will use the value	"+".  As  a  last  re-
       sort, mhstore will use the value	"%m%P.%s".

       Example profile entries might be:

	    mhstore-store-text:	%m%P.txt
	    mhstore-store-text:	+inbox
	    mhstore-store-message/partial: +
	    mhstore-store-audio/basic: | raw2audio -e ulaw -s 8000 -c 1	>
	    mhstore-store-image/jpeg: %m%P.jpg

       The  -verbose  switch  directs  mhstore to print	out the	names of files
       that it stores.	For backward compatibility, it is  the	default.   The
       -noverbose switch suppresses these printouts.

   Overwriting Existing	Files
       The  -clobber switch controls whether mhstore should overwrite existing
       files.  The allowed values for this switch and  corresponding  behavior
       when mhstore encounters an existing file	are:

	    always    Overwrite	existing file (default)
	    auto      Create new file of form name-n.extension
	    suffix    Create new file of form name.extension.n
	    ask	      Prompt the user to specify whether or not	to overwrite
		      the existing file
	    never     Do not overwrite existing	file

       With auto and suffix, n is the lowest unused number, starting from one,
       in the same form.  If a filename	does not have an extension  (following
       a  '.'),	 then auto and suffix create a new file	of the form name-n and
       name.n, respectively.  With never and ask, the exit status  of  mhstore
       will be the number of files that	were requested but not stored.

       With  ask,  if  standard	 input is connected to a terminal, the user is
       prompted	to respond yes,	no, or rename, to whether the file  should  be
       overwritten.   The  responses can be abbreviated.  If the user responds
       with rename, then mhstore prompts the user for the name of the new file
       to  be  created.	  If  it  is a relative	path name (does	not begin with
       '/'), then it is	relative to the	current	directory.  If it is an	 abso-
       lute or relative	path to	a directory that does not exist, the user will
       be prompted whether to create the directory.  If	standard input is  not
       connected to a terminal,	ask behaves the	same as	always.

   Reassembling	Messages of Type message/partial
       mhstore	is  also able to reassemble messages that have been split into
       multiple	messages of type "message/partial".

       When asked to store a content containing	 a  partial  message,  mhstore
       will  try  to  locate all of the	portions and combine them accordingly.
       The default is to store the combined parts as a new message in the cur-
       rent  folder,  although this can	be changed using formatting strings as
       discussed above.	 Thus, if someone has sent you a  message  in  several
       parts  (such  as	 the output from sendfiles), you can easily reassemble
       them into a single message in the following fashion:

	    % mhlist 5-8
	     msg part  type/subtype		size description
	       5       message/partial		 47K part 1 of 4
	       6       message/partial		 47K part 2 of 4
	       7       message/partial		 47K part 3 of 4
	       8       message/partial		 18K part 4 of 4
	    % mhstore 5-8
	    reassembling partials 5,6,7,8 to folder inbox as message 9
	    % mhlist -verbose 9
	     msg part  type/subtype		size description
	       9       application/octet-stream	118K
			 (extract with uncompress | tar	xvpf -)

       This will store exactly one message, containing the sum of  the	parts.
       It  doesn't  matter  whether the	partials are specified in order, since
       mhstore will sort the partials, so that they are	combined in  the  cor-
       rect  order.   But if mhstore can not locate every partial necessary to
       reassemble the message, it will not store anything.

   External Access
       For contents of type message/external-body, mhstore supports these  ac-

       o   afs

       o   anon-ftp

       o   ftp

       o   local-file

       o   mail-server

       o   url

       For  the	 "anon-ftp"  and "ftp" access types, mhstore will look for the
       "nmh-access-ftp"	profile	entry, e.g.,


       to determine the	pathname of a program to perform  the  FTP  retrieval.
       This program is invoked with these arguments:

	    domain name	of FTP-site
	    remote directory
	    remote filename
	    local filename
	    "ascii" or "binary"

       The  program  should  terminate	with an	exit status of zero if the re-
       trieval is successful, and a non-zero exit status otherwise.

       For the "url" access types, mhstore will	look for the  "nmh-access-url"
       profile entry, e.g.,

	    nmh-access-url: curl -L

       to  determine  the  program to use to perform the HTTP retrieval.  This
       program is invoked with one argument: the URL of	 the  content  to  re-
       trieve.	 The  program  should  write  the content to standard out, and
       should terminate	with a status of zero if the retrieval	is  successful
       and a non-zero exit status otherwise.

   The Content Cache
       When  mhstore encounters	an external content containing a "Content-ID:"
       field, and if the content allows	caching, then depending	on the caching
       behavior	 of  mhstore,  the  content might be read from or written to a

       The caching behavior of mhstore is  controlled  with  the  -rcache  and
       -wcache switches, which define the policy for reading from, and writing
       to, the cache, respectively.  One of four policies  may	be  specified:
       "public",  indicating that mhstore should make use of a publicly-acces-
       sible content cache; "private", indicating that mhstore should make use
       of  the	user's private content cache; "never", indicating that mhstore
       should never make use of	caching; and, "ask", indicating	 that  mhstore
       should ask the user.

       There are two directories where contents	may be cached: the profile en-
       try "nmh-cache" names a directory containing  world-readable  contents,
       and, the	profile	entry "nmh-private-cache" names	a directory containing
       private contents.  The former should be an absolute (rooted)  directory

       For example,

	    nmh-cache: /tmp

       might  be  used	if you didn't care that	the cache got wiped after each
       reboot of the system.  The latter is interpreted	relative to the	user's
       nmh directory, if not rooted, e.g.,

	    nmh-private-cache: .cache

       (which is the default value).

   User	Environment
       Because	the environment	in which mhstore operates may vary for differ-
       ent machines, mhstore will look for the environment variable MHSTORE  .
       If present, this	specifies the name of an additional user profile which
       should be read.	Hence, when a user logs	in on  a  particular  machine,
       this  environment  variable should be set to refer to a file containing
       definitions useful for that machine.  Finally, mhstore will attempt  to


       which is	created	automatically during nmh installation.

       See "Profile Lookup" in mh-profile(5) for the profile search order, and
       for how duplicate entries are treated.

   Decoding RFC	2047-encoded file names
       The improper RFC	2047 encoding of file name parameters can be  replaced
       with  correct  RFC  2231	encoding using mhfixmsg, either	permanently or
       ephemerally, e.g.,

	      mhfixmsg -outfile	- | mhstore -auto -clobber ask -file -

       The -clobberask is not necessary, though	recommended to avoid  silently
       overwriting an existing file.

       mhstore looks for additional profile files in multiple locations: abso-
       lute pathnames are accessed directly, tilde expansion is	done on	 user-
       names, and files	are searched for in the	user's Mail directory as spec-
       ified in	their profile.	If not found there,  the  directory  "/usr/lo-
       cal/etc/nmh" is checked.

       $HOME/.mh_profile		    The	user profile
       $MHSTORE				    Additional profile entries
       /usr/local/etc/nmh/mhn.defaults	    System default MIME	profile	entries

       Path:		    To determine the user's nmh	directory
       Current-Folder:	    To find the	default	current	folder
       nmh-access-ftp:	    Program to retrieve	contents via FTP
       nmh-access-url:	    Program to retrieve	contents via HTTP
       nmh-cache	    Public directory to	store cached external contents
       nmh-private-cache    Personal directory to store	cached external	contents
       nmh-storage	    Directory to store contents
       mhstore-store-<type>*Template for storing contents

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

       `+folder' defaults to the current folder
       `msgs' defaults to cur
       `-clobber always'
       `-rcache	ask'
       `-wcache	ask'

       If a folder is given, it	will become the	current	folder.	 The last mes-
       sage selected will become the current message.

       Partial messages	contained within a multipart content are not  reassem-

nmh-1.7.1			  2015-02-06			    MHSTORE(1)


Want to link to this manual page? Use this URL:

home | help