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

FreeBSD Manual Pages

  
 
  

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

NAME
       mhstore - store contents	of MIME	messages into files

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

DESCRIPTION
       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 store in a separate file.	 The header fields of the mes-
       sage are	not stored.  By	using the -part	and -type  switches,  you  may
       limit  the scope	of mhstore to particular subparts (of a	multipart con-
       tent) and/or particular content types.

       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 for	only  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.

       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.

   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
       content.

   Storing the Contents
       The  mhstore  will store	the contents of	the named messages in "native"
       (decoded) format.  Two things must  be  determined:  the	 directory  to
       store  the content, and the filenames.  Files are written in the	direc-
       tory 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:

	    mhstore-store-<type>/<subtype>

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

	    mhstore-store-<type>

       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	> %m%P.au
	    mhstore-store-image/jpeg: %m%P.jpg
	    mhstore-store-application/PostScript: %m%P.ps

       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 all	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 -)
			 type=tar
			 conversions=compress

       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-
       cess-types:

       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.,

	    nmh-access-ftp: myftp.sh

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

	    domain name	of FTP-site
	    username
	    password
	    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
       cache.

       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	publically-ac-
       cessible	content	cache; "private", indicating that mhstore should  make
       use  of	the user's private content cache; "never", indicating that mh-
       store should never make use of caching; and, "ask", indicating that mh-
       store 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
       name.

       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
       consult

	    /usr/local/etc/nmh/mhn.defaults

       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.

FILES
       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

PROFILE	COMPONENTS
       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

SEE ALSO
       mhbuild(1), mhlist(1), mhshow(1), sendfiles(1)

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

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

BUGS
       Partial	messages contained within a multipart content are not reassem-
       bled.

nmh-1.6				 March 2, 2014			    MHSTORE(1)

NAME | SYNOPSIS | DESCRIPTION | FILES | PROFILE COMPONENTS | SEE ALSO | DEFAULTS | CONTEXT | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=mhstore&sektion=1&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help