{
    "mode": "perldoc",
    "parameter": "Mail::Box::MH",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/Mail%3A%3ABox%3A%3AMH/json",
    "generated": "2026-06-13T12:31:07Z",
    "synopsis": "use Mail::Box::MH;\nmy $folder = new Mail::Box::MH folder => $ENV{MAIL}, ...;",
    "sections": {
        "NAME": {
            "content": "Mail::Box::MH - handle MH folders\n",
            "subsections": []
        },
        "INHERITANCE": {
            "content": "Mail::Box::MH\nis a Mail::Box::Dir\nis a Mail::Box\nis a Mail::Reporter\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "use Mail::Box::MH;\nmy $folder = new Mail::Box::MH folder => $ENV{MAIL}, ...;\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "This documentation describes how MH mailboxes work, and what you can do with the MH folder\nobject \"Mail::Box::MH\".\n\nExtends \"DESCRIPTION\" in Mail::Box::Dir.\n",
            "subsections": []
        },
        "OVERLOADED": {
            "content": "Extends \"OVERLOADED\" in Mail::Box::Dir.\n\noverload: \"\"\nInherited, see \"OVERLOADED\" in Mail::Box\n\noverload: @{}\nInherited, see \"OVERLOADED\" in Mail::Box\n\noverload: cmp\nInherited, see \"OVERLOADED\" in Mail::Box\n",
            "subsections": []
        },
        "METHODS": {
            "content": "Extends \"METHODS\" in Mail::Box::Dir.\n",
            "subsections": [
                {
                    "name": "Constructors",
                    "content": "Extends \"Constructors\" in Mail::Box::Dir.\n\nMail::Box::MH->new(%options)\n-Option           --Defined in     --Default\naccess             Mail::Box        'r'\nbodydelayedtype  Mail::Box        Mail::Message::Body::Delayed\nbodytype          Mail::Box        Mail::Message::Body::Lines\ncoerceoptions     Mail::Box        []\ncreate             Mail::Box        <false>\ndirectory          Mail::Box::Dir   <derived from folder name>\nextract            Mail::Box        10240\nfieldtype         Mail::Box        undef\nfixheaders        Mail::Box        <false>\nfolder             Mail::Box        $ENV{MAIL}\nfolderdir          Mail::Box        $ENV{HOME}/.mh\nheaddelayedtype  Mail::Box        Mail::Message::Head::Delayed\nheadtype          Mail::Box        Mail::Message::Head::Complete\nindex                               undef\nindexfilename                      <foldername>/.index\nindextype                          Mail::Box::MH::Index\nkeepdups          Mail::Box        <false>\nkeepindex                          0\nlabels                              undef\nlabelsfilename                     <foldername>/.mhsequence\nlabelstype                         Mail::Box::MH::Labels\nlockfile          Mail::Box        <indexfile>\nlocktimeout       Mail::Box        1 hour\nlocktype          Mail::Box        Mail::Box::Locker::DotLock\nlockwait          Mail::Box        10 seconds\nlocker             Mail::Box        undef\nlog                Mail::Reporter   'WARNINGS'\nmanager            Mail::Box        undef\nmessagetype       Mail::Box        <folder-class>::Message\nmultiparttype     Mail::Box        Mail::Message::Body::Multipart\nremovewhenempty  Mail::Box        <true>\nsaveonexit       Mail::Box        <true>\ntrace              Mail::Reporter   'WARNINGS'\ntrusted            Mail::Box        <depends on folder location>\n\naccess => MODE\nbodydelayedtype => CLASS\nbodytype => CLASS|CODE\ncoerceoptions => ARRAY\ncreate => BOOLEAN\ndirectory => DIRECTORY\nextract => INTEGER | CODE | METHOD | 'LAZY'|'ALWAYS'\nfieldtype => CLASS\nfixheaders => BOOLEAN\nfolder => FOLDERNAME\nfolderdir => DIRECTORY\nheaddelayedtype => CLASS\nheadtype => CLASS\nindex => OBJECT\nYou may specify an OBJECT of a type which extends Mail::Box::MH::Index (at least\nimplements a \"get()\" method), as alternative for an index file reader as created by\n\"Mail::Box::MH\".\n\nindexfilename => FILENAME\nThe FILENAME which is used in each directory to store the headers of all mails. The\nfilename shall not contain a directory path. (e.g. Do not use \"/usr/people/jan/.index\",\nnor \"subdir/.index\", but say \".index\".)\n\nindextype => CLASS\nkeepdups => BOOLEAN\nkeepindex => BOOLEAN\nKeep an index file of the specified mailbox, one file per directory. Using an index file\nwill speed up things considerably, because it avoids reading all the message files the\nmoment that you open the folder. When you open a folder, you can use the index file to\nretrieve information such as the subject of each message, instead of having to read\npossibly thousands of messages.\n\nlabels => OBJECT\nYou may specify an OBJECT of a type which extends Mail::Box::MH::Labels (at least\nimplements the \"get()\" method), as alternative for labels file reader as created by\n\"Mail::Box::MH\".\n\nlabelsfilename => FILENAME\nIn MH-folders, messages can be labeled, for instance based on the sender or whether it is\nread or not. This status is kept in a file which is usually called \".mhsequences\", but\nthat name can be overruled with this flag.\n\nlabelstype => CLASS\nlockfile => FILENAME\nlocktimeout => SECONDS\nlocktype => CLASS|STRING|ARRAY\nlockwait => SECONDS\nlocker => OBJECT\nlog => LEVEL\nmanager => MANAGER\nmessagetype => CLASS\nmultiparttype => CLASS\nremovewhenempty => BOOLEAN\nsaveonexit => BOOLEAN\ntrace => LEVEL\ntrusted => BOOLEAN\n"
                },
                {
                    "name": "The folder",
                    "content": "Extends \"The folder\" in Mail::Box::Dir.\n\n$obj->addMessage($message, %options)\nInherited, see \"The folder\" in Mail::Box\n\n$obj->addMessages(@messages)\nInherited, see \"The folder\" in Mail::Box\n\nMail::Box::MH->appendMessages(%options)\nAppend a message to a folder which is not open.\n\n-Option  --Defined in     --Default\nfolder    Mail::Box        <required>\nmessage   Mail::Box        undef\nmessages  Mail::Box        undef\nshare     Mail::Box        <false>\n\nfolder => FOLDERNAME\nmessage => MESSAGE\nmessages => ARRAY-OF-MESSAGES\nshare => BOOLEAN\n\n$obj->close(%options)\nInherited, see \"The folder\" in Mail::Box\n\n$obj->copyTo($folder, %options)\nInherited, see \"The folder\" in Mail::Box\n\n$obj->delete(%options)\nInherited, see \"The folder\" in Mail::Box\n\n$obj->directory()\nInherited, see \"The folder\" in Mail::Box::Dir\n\n$obj->folderdir( [$directory] )\nInherited, see \"The folder\" in Mail::Box\n\n$obj->name()\nInherited, see \"The folder\" in Mail::Box\n\n$obj->organization()\nInherited, see \"The folder\" in Mail::Box\n\n$obj->size()\nInherited, see \"The folder\" in Mail::Box\n\n$obj->type()\nInherited, see \"The folder\" in Mail::Box\n\n$obj->update(%options)\nInherited, see \"The folder\" in Mail::Box\n\n$obj->url()\nInherited, see \"The folder\" in Mail::Box\n"
                },
                {
                    "name": "Folder flags",
                    "content": "Extends \"Folder flags\" in Mail::Box::Dir.\n\n$obj->access()\nInherited, see \"Folder flags\" in Mail::Box\n\n$obj->isModified()\nInherited, see \"Folder flags\" in Mail::Box\n\n$obj->modified( [BOOLEAN] )\nInherited, see \"Folder flags\" in Mail::Box\n\n$obj->writable()\nInherited, see \"Folder flags\" in Mail::Box\n"
                },
                {
                    "name": "The messages",
                    "content": "Extends \"The messages\" in Mail::Box::Dir.\n\n$obj->current( [$number|$message|$messageid] )\nInherited, see \"The messages\" in Mail::Box\n\n$obj->find($messageid)\nInherited, see \"The messages\" in Mail::Box\n\n$obj->findFirstLabeled( $label, [BOOLEAN, [$msgs]] )\nInherited, see \"The messages\" in Mail::Box\n\n$obj->message( $index, [$message] )\nInherited, see \"The messages\" in Mail::Box\n\n$obj->messageId( $messageid, [$message] )\nInherited, see \"The messages\" in Mail::Box\n\n$obj->messageIds()\nInherited, see \"The messages\" in Mail::Box\n\n$obj->messages( <'ALL'|$range|'ACTIVE'|'DELETED'|$label| !$label|$filter> )\nInherited, see \"The messages\" in Mail::Box\n\n$obj->nrMessages(%options)\nInherited, see \"The messages\" in Mail::Box\n\n$obj->scanForMessages($message, $messageids, $timespan, $window)\nInherited, see \"The messages\" in Mail::Box\n"
                },
                {
                    "name": "Sub-folders",
                    "content": "Extends \"Sub-folders\" in Mail::Box::Dir.\n\n$obj->listSubFolders(%options)\nMail::Box::MH->listSubFolders(%options)\nInherited, see \"Sub-folders\" in Mail::Box\n\n$obj->nameOfSubFolder( $subname, [$parentname] )\nMail::Box::MH->nameOfSubFolder( $subname, [$parentname] )\nInherited, see \"Sub-folders\" in Mail::Box\n\n$obj->openRelatedFolder(%options)\nInherited, see \"Sub-folders\" in Mail::Box\n\n$obj->openSubFolder($subname, %options)\nInherited, see \"Sub-folders\" in Mail::Box\n\n$obj->topFolderWithMessages()\nMail::Box::MH->topFolderWithMessages()\nInherited, see \"Sub-folders\" in Mail::Box\n"
                },
                {
                    "name": "Internals",
                    "content": "Extends \"Internals\" in Mail::Box::Dir.\n\n$obj->coerce($message, %options)\nInherited, see \"Internals\" in Mail::Box\n\n$obj->create($foldername, %options)\nMail::Box::MH->create($foldername, %options)\n-Option   --Defined in--Default\nfolderdir  Mail::Box   undef\n\nfolderdir => DIRECTORY\n\n$obj->determineBodyType($message, $head)\nInherited, see \"Internals\" in Mail::Box\n\n$obj->folderToDirectory($foldername, $folderdir)\nInherited, see \"Internals\" in Mail::Box::Dir\n\nMail::Box::MH->foundIn( [$foldername], %options )\nInherited, see \"Internals\" in Mail::Box\n\n$obj->highestMessageNumber()\nReturns the highest number which is used in the folder to store a file. This method may be\ncalled when the folder is read (then this number can be derived without file-system access),\nbut also when the folder is not read (yet).\n\n$obj->index()\nCreate a index reader/writer object.\n\n$obj->labels()\nCreate a label reader/writer object.\n\n$obj->lineSeparator( [<STRING|'CR'|'LF'|'CRLF'>] )\nInherited, see \"Internals\" in Mail::Box\n\n$obj->locker()\nInherited, see \"Internals\" in Mail::Box\n\n$obj->messageInFile($filename)\nInherited, see \"Internals\" in Mail::Box::Dir\n\n$obj->read(%options)\nInherited, see \"Internals\" in Mail::Box\n\n$obj->readMessageFilenames($directory)\nInherited, see \"Internals\" in Mail::Box::Dir\n\n$obj->readMessages(%options)\nInherited, see \"Internals\" in Mail::Box\n\n$obj->storeMessage($message)\nInherited, see \"Internals\" in Mail::Box\n\n$obj->toBeThreaded($messages)\nInherited, see \"Internals\" in Mail::Box\n\n$obj->toBeUnthreaded($messages)\nInherited, see \"Internals\" in Mail::Box\n\n$obj->updateMessages(%options)\nInherited, see \"Internals\" in Mail::Box\n\n$obj->write(%options)\nInherited, see \"Internals\" in Mail::Box\n\n$obj->writeMessages(%options)\n-Option  --Defined in     --Default\nmessages  Mail::Box        <required>\nrenumber                   <true>\n\nmessages => ARRAY\nrenumber => BOOLEAN\nPermit renumbering of message. By default this is true, but for some unknown reason, you\nmay be thinking that messages should not be renumbered.\n"
                },
                {
                    "name": "Other methods",
                    "content": "Extends \"Other methods\" in Mail::Box::Dir.\n\n$obj->timespan2seconds($time)\nMail::Box::MH->timespan2seconds($time)\nInherited, see \"Other methods\" in Mail::Box\n"
                },
                {
                    "name": "Error handling",
                    "content": "Extends \"Error handling\" in Mail::Box::Dir.\n\n$obj->AUTOLOAD()\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->addReport($object)\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )\nMail::Box::MH->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->errors()\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->log( [$level, [$strings]] )\nMail::Box::MH->log( [$level, [$strings]] )\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->logPriority($level)\nMail::Box::MH->logPriority($level)\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->logSettings()\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->notImplemented()\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->report( [$level] )\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->reportAll( [$level] )\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->trace( [$level] )\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->warnings()\nInherited, see \"Error handling\" in Mail::Reporter\n"
                },
                {
                    "name": "Cleanup",
                    "content": "Extends \"Cleanup\" in Mail::Box::Dir.\n\n$obj->DESTROY()\nInherited, see \"Cleanup\" in Mail::Box\n"
                }
            ]
        },
        "DETAILS": {
            "content": "Extends \"DETAILS\" in Mail::Box::Dir.\n",
            "subsections": [
                {
                    "name": "Different kinds of folders",
                    "content": "Extends \"Different kinds of folders\" in Mail::Box::Dir.\n"
                },
                {
                    "name": "Available folder types",
                    "content": "Extends \"Available folder types\" in Mail::Box::Dir.\n"
                },
                {
                    "name": "Folder class implementation",
                    "content": "Extends \"Folder class implementation\" in Mail::Box::Dir.\n"
                },
                {
                    "name": "How MH folders work",
                    "content": "MH-type folders use a directory to store the messages of one folder. Each message is stored in a\nseparate file. This seems useful, because changes in a folder change only a few of these small\nfiles, in contrast with file-based folders where changes in a folder cause rewrites of huge\nfolder files.\n\nHowever, MH-based folders perform very bad if you need header information of all messages. For\ninstance, if you want to have full knowledge about all message-threads (see\nMail::Box::Thread::Manager) in the folder, it requires to read all header lines in all message\nfiles. And usually, reading your messages in threads is desired.\n\nSo, each message is written in a separate file. The filenames are numbers, which count from 1.\nNext to these message files, a directory may contain a file named \".mhsequences\", storing\nlabels which relate to the messages. Furthermore, a folder-directory may contain\nsub-directories, which are seen as sub-folders.\n"
                },
                {
                    "name": "This implementation",
                    "content": "This implementation supports the \".mh-sequences\" file and sub-folders. Next to this,\nconsiderable effort it made to avoid reading each message-file. This should boost performance of\nthe MailBox distribution over other Perl-modules which are able to read folders.\n\nFolder types which store their messages each in one file, together in one directory, are bad for\nperformance. Consider that you want to know the subjects of all messages, while browser through\na folder with your mail-reading client. This would cause all message-files to be read.\n\nMail::Box::MH has two ways to try improve performance. You can use an index-file, and use on\ndelay-loading. The combination performs even better. Both are explained in the next sections.\n"
                },
                {
                    "name": "An index-file",
                    "content": "If you specify new(keepindex), then all header-lines of all messages from the folder which have\nbeen read once, will also be written into one dedicated index-file (one file per folder). The\ndefault filename is \".index\"\n\nHowever, index-files are not supported by any other reader which supports MH (as far as I know).\nIf you read the folders with such I client, it will not cause unrecoverable conflicts with this\nindex-file, but at most be bad for performance.\n\nIf you do not (want to) use an index-file, then delay-loading may save your day.\n"
                }
            ]
        },
        "DIAGNOSTICS": {
            "content": "Error: Cannot append message without lock on $folder.\nIt is impossible to append one or more messages to the folder which is not opened, because\nlocking it fails. The folder may be in use by an other application, or you may need to\nspecify some lock related options (see new()).\n\nError: Cannot create MH folder $name: $!\nFor some reason, it is impossible to create the folder. Check the permissions and the name\nof the folder. Does the path to the directory to be created exist?\n\nError: Cannot write folder $name without lock.\nIt is impossible to get a lock on the folder, which means that the changes can not be made.\nYou may need to tune the lock related options which are available at folder creation.\n\nWarning: Changes not written to read-only folder $self.\nYou have opened the folder read-only --which is the default set by new(access)--, made\nmodifications, and now want to close it. Set close(force) if you want to overrule the access\nmode, or close the folder with close(write) set to \"NEVER\".\n\nError: Copying failed for one message.\nFor some reason, for instance disc full, removed by external process, or read-protection, it\nis impossible to copy one of the messages. Copying will proceed for the other messages.\n\nError: Destination folder $name is not writable.\nThe folder where the messages are copied to is not opened with write access (see\nnew(access)). This has no relation with write permission to the folder which is controlled\nby your operating system.\n\nWarning: Different messages with id $msgid\nThe message id is discovered more than once within the same folder, but the content of the\nmessage seems to be different. This should not be possible: each message must be unique.\n\nError: Folder $name is opened read-only\nYou can not write to this folder unless you have opened the folder to write or append with\nnew(access), or the \"force\" option is set true.\n\nError: Folder $name not deleted: not writable.\nThe folder must be opened with write access via new(access), otherwise removing it will be\nrefused. So, you may have write-access according to the operating system, but that will not\nautomatically mean that this \"delete\" method permits you to. The reverse remark is valid as\nwell.\n\nError: Invalid timespan '$timespan' specified.\nThe string does not follow the strict rules of the time span syntax which is permitted as\nparameter.\n\nWarning: Message-id '$msgid' does not contain a domain.\nAccording to the RFCs, message-ids need to contain a unique random part, then an \"@\", and\nthen a domain name. This is made to avoid the creation of two messages with the same id. The\nwarning emerges when the \"@\" is missing from the string.\n\nError: Package $package does not implement $method.\nFatal error: the specific package (or one of its superclasses) does not implement this\nmethod where it should. This message means that some other related classes do implement this\nmethod however the class at hand does not. Probably you should investigate this and probably\ninform the author of the package.\n\nError: Unable to create subfolder $name of $folder.\nThe copy includes the subfolders, but for some reason it was not possible to copy one of\nthese. Copying will proceed for all other sub-folders.\n\nError: Unable to write message for $folder to $filename: $!\nThe new message could not be written to its new file, for the specific reason.\n\nError: Writing folder $name failed\nFor some reason (you probably got more error messages about this problem) it is impossible\nto write the folder, although you should because there were changes made.\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "This module is part of Mail-Box distribution version 3.009, built on August 18, 2020. Website:\nhttp://perl.overmeer.net/CPAN/\n",
            "subsections": []
        },
        "LICENSE": {
            "content": "Copyrights 2001-2020 by [Mark Overmeer]. For other contributors see ChangeLog.\n\nThis program is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself. See http://dev.perl.org/licenses/\n",
            "subsections": []
        }
    },
    "summary": "Mail::Box::MH - handle MH folders",
    "flags": [],
    "examples": [],
    "see_also": []
}