{
    "content": [
        {
            "type": "text",
            "text": "# mhstore(1mh) (man)\n\n**Summary:** mhstore - store contents of nmh MIME messages into files\n\n**Synopsis:** mhstore [-help] [-version] [+folder] [msgs] [-file file] [-outfile outfile] [-part number]\n...  [-type content] ...  [-prefer content] ...  [-noprefer] [-auto | -noauto] [-clobber\nalways | auto | suffix | ask | never] [-rcache policy] [-wcache policy] [-check |\n-nocheck] [-verbose | -noverbose]\n\n## Examples\n\n- `The  improper RFC 2047 encoding of file name parameters can be replaced with correct RFC 2231`\n- `encoding using mhfixmsg, either permanently or ephemerally, e.g.,`\n- `mhfixmsg -outfile - | mhstore -auto -clobber ask -file -`\n- `The -clobberask is not necessary, though recommended to avoid silently overwriting an  exist‐`\n- `ing file.`\n\n## See Also\n\n- mhbuild(1)\n- mhfixmsg(1)\n- mhlist(1)\n- mhshow(1)\n- sendfiles(1)\n\n## Section Outline\n\n- **NAME** (2 lines)\n- **SYNOPSIS** (5 lines)\n- **DESCRIPTION** (67 lines) — 7 subsections\n  - Checking the Contents (4 lines)\n  - Storing the Contents (81 lines)\n  - Overwriting Existing Files (24 lines)\n  - Reassembling Messages of Type message/partial (30 lines)\n  - External Access (42 lines)\n  - The Content Cache (27 lines)\n  - User Environment (13 lines)\n- **EXAMPLES** (1 lines) — 1 subsections\n  - Decoding RFC 2047-encoded file names (8 lines)\n- **FILES** (9 lines)\n- **PROFILE COMPONENTS** (9 lines)\n- **SEE ALSO** (2 lines)\n- **DEFAULTS** (9 lines)\n- **CONTEXT** (3 lines)\n- **BUGS** (5 lines)\n\n## Full Content\n\n### NAME\n\nmhstore - store contents of nmh MIME messages into files\n\n### SYNOPSIS\n\nmhstore [-help] [-version] [+folder] [msgs] [-file file] [-outfile outfile] [-part number]\n...  [-type content] ...  [-prefer content] ...  [-noprefer] [-auto | -noauto] [-clobber\nalways | auto | suffix | ask | never] [-rcache policy] [-wcache policy] [-check |\n-nocheck] [-verbose | -noverbose]\n\n### DESCRIPTION\n\nThe mhstore command allows you to store the contents of a collection  of  MIME  (multi-media)\nmessages into files or other messages.\n\nmhstore manipulates multi-media messages as specified in RFC 2045 to RFC 2049.\n\nBy  default, mhstore will store all the parts of each message.  Each part will be stored in a\nseparate file.  The header fields of the message are not stored.  By using the -part,  -type,\nand  -prefer switches, you may limit and reorder the set of parts to be stored, based on part\nnumber and/or content type.\n\nThe -file file switch directs mhstore to use the specified file as the source message, rather\nthan  a message from a folder.  If you specify this file as “-”, then mhstore will accept the\nsource message on the standard input.  Note that the file,  or  input  from  standard  input,\nshould  be a validly formatted message, just like any other nmh message.  It should not be in\nmail drop format (to convert a file in mail drop format to a  folder  of  nmh  messages,  see\ninc(1)).\n\nA  part  specification  consists of a series of numbers separated by dots.  For example, in a\nmultipart content containing three parts, these would be named as 1, 2, and 3,  respectively.\nIf  part 2 was also a multipart content containing two parts, these would be named as 2.1 and\n2.2, respectively.  Note that the -part switch is effective only for  messages  containing  a\nmultipart content.  If a message has some other kind of content, or if the part is itself an‐\nother multipart content, the -part switch will not prevent the content from being acted upon.\n\nThe -type switch can also be used to restrict (or, when used in conjunction  with  -part,  to\nfurther  restrict)  the  selection  of  parts  according  to content type.  One or more -type\nswitches part will only select the first match from a multipart/alternative, even if there is\nmore than one subpart that matches (one of) the given content type(s).\n\nUsing  either  -part  or  -type  switches  alone will cause either to select the part(s) they\nmatch.  Using them together will select only the part(s) matched by both (sets of)  switches.\nIn  other  words,  the result is the intersection, and not the union, of their separate match\nresults.\n\nA content specification consists of a content type and a subtype.  The initial list of “stan‐\ndard” content types and subtypes can be found in RFC 2046.\n\nA list of commonly used contents is briefly reproduced here:\n\nType         Subtypes\n----         --------\ntext         plain, enriched\nmultipart    mixed, alternative, digest, parallel\nmessage      rfc822, partial, external-body\napplication  octet-stream, postscript\nimage        jpeg, gif, png\naudio        basic\nvideo        mpeg\n\nA legal MIME message must contain a subtype specification.\n\nTo specify a content, regardless of its subtype, just use the name of the content, e.g., “au‐\ndio”.  To specify a specific subtype, separate the two with  a  slash,  e.g.,  “audio/basic”.\nNote  that  regardless  of  the values given to the -type switch, a multipart content (of any\nsubtype listed above) is always acted upon.  Further note that if the -type switch  is  used,\nand  it is desirable to act on a message/external-body content, then the -type switch must be\nused twice: once for message/external-body and once for the content externally referenced.\n\nThe -prefer switch will alter the part-ordering of multipart/alternative MIME sections in or‐\nder to override the sender-imposed default ordering.  The -prefer switch is functionally most\nimportant for mhshow, but is also implemented in mhlist and mhstore to make common  part-num‐\nbering  possible  across all three programs.  The last of multiple -prefer switches will have\nthe highest priority.  This allows the command line switches  to  override  profile  entries.\nSee mhlist(1) and mhshow(1) for more information on -prefer.\n\nThe -noprefer switch will cancel any previous -prefer switches.\n\n#### Checking the Contents\n\nThe  -check  switch tells mhstore to check each content for an integrity checksum.  If a con‐\ntent has such a checksum (specified as a Content-MD5 header field), then mhstore will attempt\nto verify the integrity of the content.\n\n#### Storing the Contents\n\nmhstore  will  store  the  contents  of the named messages in “native” (decoded) format.  Two\nthings must be determined: the directory in which to store the content,  and  the  filenames.\nFiles are written in the directory given by the “nmh-storage” profile entry, e.g.,\n\nnmh-storage: /tmp\n\nIf this entry isn't present, the current working directory is used.\n\nIf  the  -outfile  switch is given, its argument is used for the filename to store all of the\ncontent, with “-” indicating standard output.  If the -auto switch  is  given,  then  mhstore\nwill check if the message contains information indicating the filename that should be used to\nstore the content.  This information should be specified as the “filename” attribute  in  the\n“Content-Disposition”  header or as the “name” attribute in the “Content-Type” header for the\ncontent you are storing.  For security reasons, this filename will be ignored  if  it  begins\nwith  the character '/', '.', '|', or '!', or if it contains the character '%'.  We also rec‐\nommend using a “nmh-storage” profile entry or a -clobber switch setting other  than  the  de‐\nfault of “always” to avoid overwriting existing files.\n\nIf the -auto switch is not given (or is being ignored for security reasons) then mhstore will\nlook in the user's profile for a “formatting string” to determine how the different  contents\nshould be stored.  First, mhstore will look for an entry of the form:\n\nmhstore-store-<type>/<subtype>\n\nto  determine  the formatting string.  If this isn't found, mhstore will look for an entry of\nthe form:\n\nmhstore-store-<type>\n\nto determine the formatting string.\n\nIf the formatting string starts with a “+” character, then content is  stored  in  the  named\nfolder.   A  formatting  string consisting solely of a “+” character is interpreted to be the\ncurrent folder.\n\nIf the formatting string consists solely of a “-” character, then the content is sent to  the\nstandard output.\n\nIf  the formatting string starts with a '|', then it represents a command for mhstore to exe‐\ncute which should ultimately store the content.  The content will be passed to  the  standard\ninput of the command.  Before the command is executed, mhstore will change to the appropriate\ndirectory, and any escapes (given below) in the formatting string will be expanded.  The  use\nof the “%a” sequence is not recommended because the user has no control over the Content-Type\nparameter data.\n\nOtherwise, the formatting string will represent a pathname in which to store the content.  If\nthe  formatting  string  starts  with a '/', then the content will be stored in the full path\ngiven, else the file name will be relative to the value of “nmh-storage” or the current work‐\ning  directory.   Any  escapes (given below) will be expanded, except for the a-escape.  Note\nthat if “nmh-storage” is not an absolute path, it will be relative to the  folder  that  con‐\ntains the message(s).\n\nA  command  or  pathname formatting string may contain the following escapes.  If the content\nisn't part of a multipart (of any subtype listed above) content, the p-escapes are ignored.\n\n%a  Parameters from Content-Type  (only valid with command)\n%m  Insert message number\n%P  Insert part number with leading dot\n%p  Insert part number without leading dot\n%t  Insert content type\n%s  Insert content subtype\n%%  Insert character %\n\nIf no formatting string is found, mhstore will check  to  see  if  the  content  is  applica‐\ntion/octet-stream with parameter “type=tar”.  If so, mhstore will choose an appropriate file‐\nname.  If the content is not application/octet-stream, then mhstore will check to see if  the\ncontent is a message.  If so, mhstore will use the value “+”.  As a last resort, mhstore will\nuse the value “%m%P.%s”.\n\nExample profile entries might be:\n\nmhstore-store-text: %m%P.txt\nmhstore-store-text: +inbox\nmhstore-store-message/partial: +\nmhstore-store-audio/basic: | raw2audio -e ulaw -s 8000 -c 1 > %m%P.au\nmhstore-store-image/jpeg: %m%P.jpg\nmhstore-store-application/PostScript: %m%P.ps\n\nThe -verbose switch directs mhstore to print out the names of  files  that  it  stores.   For\nbackward compatibility, it is the default.  The -noverbose switch suppresses these printouts.\n\n#### Overwriting Existing Files\n\nThe  -clobber  switch  controls whether mhstore should overwrite existing files.  The allowed\nvalues for this switch and corresponding behavior when mhstore encounters  an  existing  file\nare:\n\nalways    Overwrite existing file (default)\nauto      Create new file of form name-n.extension\nsuffix    Create new file of form name.extension.n\nask       Prompt the user to specify whether or not to overwrite\nthe existing file\nnever     Do not overwrite existing file\n\nWith auto and suffix, n is the lowest unused number, starting from one, in the same form.  If\na filename does not have an extension (following a '.'), then auto and suffix  create  a  new\nfile of the form name-n and name.n, respectively.  With never and ask, the exit status of mh‐‐\nstore will be the number of files that were requested but not stored.\n\nWith ask, if standard input is connected to a terminal, the user is prompted to respond  yes,\nno,  or rename, to whether the file should be overwritten.  The responses can be abbreviated.\nIf the user responds with rename, then mhstore prompts the user for the name of the new  file\nto  be created.  If it is a relative path name (does not begin with '/'), then it is relative\nto the current directory.  If it is an absolute or relative path to a directory that does not\nexist,  the  user will be prompted whether to create the directory.  If standard input is not\nconnected to a terminal, ask behaves the same as always.\n\n#### Reassembling Messages of Type message/partial\n\nmhstore is also able to reassemble messages that have been split into  multiple  messages  of\ntype “message/partial”.\n\nWhen asked to store a content containing a partial message, mhstore will try to locate all of\nthe portions and combine them accordingly.  The default is to store the combined parts  as  a\nnew  message  in the current folder, although this can be changed using formatting strings as\ndiscussed above.  Thus, if someone has sent you a message in several parts (such as the  out‐\nput  from  sendfiles),  you can easily reassemble them into a single message in the following\nfashion:\n\n% mhlist 5-8\nmsg part  type/subtype             size description\n5       message/partial           47K part 1 of 4\n6       message/partial           47K part 2 of 4\n7       message/partial           47K part 3 of 4\n8       message/partial           18K part 4 of 4\n% mhstore 5-8\nreassembling partials 5,6,7,8 to folder inbox as message 9\n% mhlist -verbose 9\nmsg part  type/subtype             size description\n9       application/octet-stream 118K\n(extract with uncompress | tar xvpf -)\ntype=tar\nconversions=compress\n\nThis will store exactly one message, containing the sum of  the  parts.   It  doesn't  matter\nwhether  the  partials  are specified in order, since mhstore will sort the partials, so that\nthey are combined in the correct order.  But if mhstore can not locate every  partial  neces‐\nsary to reassemble the message, it will not store anything.\n\n#### External Access\n\nFor contents of type message/external-body, mhstore supports these access-types:\n\n•   afs\n\n•   anon-ftp\n\n•   ftp\n\n•   local-file\n\n•   mail-server\n\n•   url\n\nFor the “anon-ftp” and “ftp” access types, mhstore will look for the “nmh-access-ftp” profile\nentry, e.g.,\n\nnmh-access-ftp: myftp.sh\n\nto determine the pathname of a program to perform the FTP retrieval.  This program is invoked\nwith these arguments:\n\ndomain name of FTP-site\nusername\npassword\nremote directory\nremote filename\nlocal filename\n“ascii” or “binary”\n\nThe  program should terminate with an exit status of zero if the retrieval is successful, and\na non-zero exit status otherwise.\n\nFor the “url” access types, mhstore will look for the “nmh-access-url” profile entry, e.g.,\n\nnmh-access-url: curl -L\n\nto determine the program to use to perform the HTTP retrieval.  This program is invoked  with\none  argument:  the  URL of the content to retrieve.  The program should write the content to\nstandard out, and should terminate with a status of zero if the retrieval is successful and a\nnon-zero exit status otherwise.\n\n#### The Content Cache\n\nWhen mhstore encounters an external content containing a “Content-ID:” field, and if the con‐\ntent allows caching, then depending on the caching behavior of mhstore, the content might  be\nread from or written to a cache.\n\nThe  caching  behavior  of mhstore is controlled with the -rcache and -wcache switches, which\ndefine the policy for reading from, and writing to, the cache,  respectively.   One  of  four\npolicies  may  be specified: “public”, indicating that mhstore should make use of a publicly-\naccessible content cache; “private”, indicating that mhstore should make use  of  the  user's\nprivate  content  cache;  “never”,  indicating that mhstore should never make use of caching;\nand, “ask”, indicating that mhstore should ask the user.\n\nThere are two directories where contents may be cached: the profile entry “nmh-cache” names a\ndirectory  containing  world-readable  contents,  and,  the profile entry “nmh-private-cache”\nnames a directory containing private contents.  The former should be an absolute (rooted) di‐\nrectory name.\n\nFor example,\n\nnmh-cache: /tmp\n\nmight  be  used  if you didn't care that the cache got wiped after each reboot of the system.\nThe latter is interpreted relative to the user's nmh directory, if not rooted, e.g.,\n\nnmh-private-cache: .cache\n\n(which is the default value).\n\n#### User Environment\n\nBecause the environment in which mhstore operates may vary for  different  machines,  mhstore\nwill  look  for the environment variable MHSTORE .  If present, this specifies the name of an\nadditional user profile which should be read.  Hence, when a user logs in on a particular ma‐\nchine, this environment variable should be set to refer to a file containing definitions use‐\nful for that machine.  Finally, mhstore will attempt to consult\n\n/etc/nmh/mhn.defaults\n\nwhich is created automatically during nmh installation.\n\nSee \"Profile Lookup\" in mh-profile(5) for the profile search order, and for how duplicate en‐\ntries are treated.\n\n### EXAMPLES\n\n#### Decoding RFC 2047-encoded file names\n\nThe  improper RFC 2047 encoding of file name parameters can be replaced with correct RFC 2231\nencoding using mhfixmsg, either permanently or ephemerally, e.g.,\n\nmhfixmsg -outfile - | mhstore -auto -clobber ask -file -\n\nThe -clobberask is not necessary, though recommended to avoid silently overwriting an  exist‐\ning file.\n\n### FILES\n\nmhstore  looks for additional profile files in multiple locations: absolute pathnames are ac‐\ncessed directly, tilde expansion is done on usernames, and files  are  searched  for  in  the\nuser's  Mail  directory  as  specified  in  their profile.  If not found there, the directory\n“/etc/nmh” is checked.\n\n$HOME/.mhprofile          The user profile\n$MHSTORE                   Additional profile entries\n/etc/nmh/mhn.defaults      System default MIME profile entries\n\n### PROFILE COMPONENTS\n\nPath:                To determine the user's nmh directory\nCurrent-Folder:      To find the default current folder\nnmh-access-ftp:      Program to retrieve contents via FTP\nnmh-access-url:      Program to retrieve contents via HTTP\nnmh-cache            Public directory to store cached external contents\nnmh-private-cache    Personal directory to store cached external contents\nnmh-storage          Directory to store contents\nmhstore-store-<type>*Template for storing contents\n\n### SEE ALSO\n\nmhbuild(1), mhfixmsg(1), mhlist(1), mhshow(1), sendfiles(1)\n\n### DEFAULTS\n\n`+folder' defaults to the current folder\n`msgs' defaults to cur\n`-noauto'\n`-clobber always'\n`-nocheck'\n`-rcache ask'\n`-wcache ask'\n`-verbose'\n\n### CONTEXT\n\nIf a folder is given, it will become the current folder.  The last message selected will  be‐\ncome the current message.\n\n### BUGS\n\nPartial messages contained within a multipart content are not reassembled.\n\n\n\nnmh-1.7.1                                    2015-02-06                                 MHSTORE(1mh)\n\n"
        }
    ],
    "structuredContent": {
        "command": "mhstore",
        "section": "1mh",
        "mode": "man",
        "summary": "mhstore - store contents of nmh MIME messages into files",
        "synopsis": "mhstore [-help] [-version] [+folder] [msgs] [-file file] [-outfile outfile] [-part number]\n...  [-type content] ...  [-prefer content] ...  [-noprefer] [-auto | -noauto] [-clobber\nalways | auto | suffix | ask | never] [-rcache policy] [-wcache policy] [-check |\n-nocheck] [-verbose | -noverbose]",
        "flags": [],
        "examples": [
            "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  exist‐",
            "ing file."
        ],
        "see_also": [
            {
                "name": "mhbuild",
                "section": "1",
                "url": "https://www.chedong.com/phpMan.php/man/mhbuild/1/json"
            },
            {
                "name": "mhfixmsg",
                "section": "1",
                "url": "https://www.chedong.com/phpMan.php/man/mhfixmsg/1/json"
            },
            {
                "name": "mhlist",
                "section": "1",
                "url": "https://www.chedong.com/phpMan.php/man/mhlist/1/json"
            },
            {
                "name": "mhshow",
                "section": "1",
                "url": "https://www.chedong.com/phpMan.php/man/mhshow/1/json"
            },
            {
                "name": "sendfiles",
                "section": "1",
                "url": "https://www.chedong.com/phpMan.php/man/sendfiles/1/json"
            }
        ],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 5,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 67,
                "subsections": [
                    {
                        "name": "Checking the Contents",
                        "lines": 4
                    },
                    {
                        "name": "Storing the Contents",
                        "lines": 81
                    },
                    {
                        "name": "Overwriting Existing Files",
                        "lines": 24
                    },
                    {
                        "name": "Reassembling Messages of Type message/partial",
                        "lines": 30
                    },
                    {
                        "name": "External Access",
                        "lines": 42
                    },
                    {
                        "name": "The Content Cache",
                        "lines": 27
                    },
                    {
                        "name": "User Environment",
                        "lines": 13
                    }
                ]
            },
            {
                "name": "EXAMPLES",
                "lines": 1,
                "subsections": [
                    {
                        "name": "Decoding RFC 2047-encoded file names",
                        "lines": 8
                    }
                ]
            },
            {
                "name": "FILES",
                "lines": 9,
                "subsections": []
            },
            {
                "name": "PROFILE COMPONENTS",
                "lines": 9,
                "subsections": []
            },
            {
                "name": "SEE ALSO",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "DEFAULTS",
                "lines": 9,
                "subsections": []
            },
            {
                "name": "CONTEXT",
                "lines": 3,
                "subsections": []
            },
            {
                "name": "BUGS",
                "lines": 5,
                "subsections": []
            }
        ]
    }
}