mhstore



MHSTORE(1)                                                          MHSTORE(1)




NAME

       mhstore - store contents of MIME messages into files


SYNOPSIS

       mhstore [+folder] [msgs] [-file file]
            [-part number]... [-type content]...
            [-auto] [-noauto] [-check] [-nocheck]
            [-rcache policy] [-wcache policy]
            [-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  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  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
       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  spec-
       ify  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 mes-
       sages 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 mes-
       sage/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 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 `-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 con-
       tent  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 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
       access-types:

            afs
            anon-ftp
            ftp
            local-file
            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 writ-
       ing to, the cache, respectively.  One of four policies  may  be  speci-
       fied:  "public",  indicating  that  mhstore should make use of a publi-
       cally-accessible content  cache;  "private",  indicating  that  mhstore
       should  make use of the user's private content cache; "never", indicat-
       ing that mhstore should never make use of caching; and, "ask", indicat-
       ing 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 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 machine, this environ-
       ment  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)
       RFC-2045:
          Multipurpose Internet Mail Extensions (MIME) Part One:
          Format of Internet Message Bodies,
       RFC-2046:
          Multipurpose Internet Mail Extensions (MIME) Part Two:
          Media Types,
       RFC-2047:
          Multipurpose Internet Mail Extensions (MIME) Part Three:
          Message Header Extensions for Non-ASCII Text,
       RFC-2048:
          Multipurpose Internet Mail Extensions (MIME) Part Four:
          Registration Procedures,
       RFC-2049:
          Multipurpose Internet Mail Extensions (MIME) Part Five:
          Conformance Criteria and Examples.


DEFAULTS

       `+folder' defaults to the current folder
       `msgs' defaults to cur
       `-noauto'
       `-nocheck'
       `-rcache ask'
       `-wcache ask'
       `-noverbose'


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.0.4]                         MH.6.8                          MHSTORE(1)

Man(1) output converted with man2html