Provided by: nmh_1.3-1build1_i386 bug

NAME

       mhstore - store contents of MIME messages into files

SYNOPSIS

       mhstore [+folder] [msgs] [-file file] [-part number] ...  [-type
            content] ...  [-auto | -noauto] [-verbose | -noverbose] [-rcache
            policy] [-wcache policy] [-check | -nocheck] [-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  thru
       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
       message are not stored.  By using the -part and -type switches, you may
       limit the scope of mhstore  to  particular  subparts  (of  a  multipart
       content) and/or particular content types.

       The  option -file file 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,
       respectively.   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/external-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
       directory 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  -auto  switch is given, then mhstore will check if the message
       contains information indicating the filename that  should  be  used  to
       store  the  content.   This  information  should  be  specified  as the
       attribute "name=filename" 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 this  switch  is  not
       the default, and it is recommended that you do NOT put the -auto switch
       in your .mh_profile file.

       If the -auto switch is not given (or  is  being  ignored  for  security
       reasons) 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 the display string
       will represent a command for mhstore to execute which should ultimately
       store the content.  The content will be passed to the standard input of
       the command.  Before the command is executed, mhstore  will  change  to
       the appropriate directory, and any escapes (given below) in the display
       string will be expanded.

       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.

       A  command  or  pathname  formatting  string  may contain the following
       escapes.  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
       content is application/octet-stream with parameter "type=tar".  If  so,
       mhstore  will  choose  an  appropriate filename.  If the content is not
       application/octet-stream, then mhstore will check to see if the content
       is  a  message.   If  so,  mhstore  will  use the value "+".  As a last
       resort, 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

   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
       current 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
       correct 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
       access-types:

       o   afs

       o   anon-ftp

       o   ftp

       o   local-file

       o   mail-server

       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
       retrieval is successful, and a non-zero exit status otherwise.

       If  this entry is not provided, then mhstore will use a simple built-in
       FTP client to perform the retrieval.

   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-
       accessible  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
       entry "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 display environment in which mhstore operates may vary  for
       different  machines,  mhstore will look for the environment variable 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 one other additional user profile, e.g.,

            /etc/nmh/mhn.defaults

       which is created automatically during nmh installation.

FILES

       $HOME/.mh_profile          The user profile
       $MHSTORE                   Additional profile entries
       /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-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'
       `-nocheck'
       `-rcacheask'
       `-wcacheask'
       `-noverbose'

CONTEXT

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

BUGS

       Partial   messages   contained  within  a  multipart  content  are  not
       reassembled.