{
    "mode": "perldoc",
    "parameter": "Mail::Box::Mbox",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/Mail%3A%3ABox%3A%3AMbox/json",
    "generated": "2026-06-13T06:54:46Z",
    "synopsis": "use Mail::Box::Mbox;\nmy $folder = Mail::Box::Mbox->new(folder => $ENV{MAIL}, ...);",
    "sections": {
        "NAME": {
            "content": "Mail::Box::Mbox - handle folders in Mbox format\n",
            "subsections": []
        },
        "INHERITANCE": {
            "content": "Mail::Box::Mbox\nis a Mail::Box::File\nis a Mail::Box\nis a Mail::Reporter\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "use Mail::Box::Mbox;\nmy $folder = Mail::Box::Mbox->new(folder => $ENV{MAIL}, ...);\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "This documentation describes how Mbox mailboxes work, and also describes what you can do with\nthe Mbox folder object Mail::Box::Mbox.\n\nExtends \"DESCRIPTION\" in Mail::Box::File.\n",
            "subsections": []
        },
        "OVERLOADED": {
            "content": "Extends \"OVERLOADED\" in Mail::Box::File.\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::File.\n",
            "subsections": [
                {
                    "name": "Constructors",
                    "content": "Extends \"Constructors\" in Mail::Box::File.\n\nMail::Box::Mbox->new(%options)\n-Option             --Defined in     --Default\naccess               Mail::Box        'r'\nbodydelayedtype    Mail::Box        Mail::Message::Body::Delayed\nbodytype            Mail::Box::File  <see description>\ncoerceoptions       Mail::Box        []\ncreate               Mail::Box        <false>\nextract              Mail::Box        10240\nfieldtype           Mail::Box        undef\nfixheaders          Mail::Box        <false>\nfolder               Mail::Box        $ENV{MAIL}\nfolderdir            Mail::Box        $ENV{HOME}.'/Mail'\nheaddelayedtype    Mail::Box        Mail::Message::Head::Delayed\nheadtype            Mail::Box        Mail::Message::Head::Complete\nkeepdups            Mail::Box        <false>\nlockextension       Mail::Box::File  '.lock'\nlockfile            Mail::Box        <foldername><lock-extension>\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        Mail::Box::Mbox::Message\nmultiparttype       Mail::Box        Mail::Message::Body::Multipart\nremovewhenempty    Mail::Box        <true>\nsaveonexit         Mail::Box        <true>\nsubfolderextension                   '.d'\ntrace                Mail::Reporter   'WARNINGS'\ntrusted              Mail::Box        <depends on folder location>\nwritepolicy         Mail::Box::File  undef\n\naccess => MODE\nbodydelayedtype => CLASS\nbodytype => CLASS|CODE\ncoerceoptions => ARRAY\ncreate => BOOLEAN\nextract => INTEGER | CODE | METHOD | 'LAZY'|'ALWAYS'\nfieldtype => CLASS\nfixheaders => BOOLEAN\nfolder => FOLDERNAME\nfolderdir => DIRECTORY\nheaddelayedtype => CLASS\nheadtype => CLASS\nkeepdups => BOOLEAN\nlockextension => FILENAME|STRING\nlockfile => FILENAME\nlocktimeout => SECONDS\nlocktype => CLASS|STRING|ARRAY\nlockwait => SECONDS\nlocker => OBJECT\nlog => LEVEL\nmanager => MANAGER\nmessagetype => CLASS\nmultiparttype => CLASS\nremovewhenempty => BOOLEAN\nsaveonexit => BOOLEAN\nsubfolderextension => STRING\nMbox folders do not support sub-folders. However, this module can simulate sub-directories\nif the user wants it to. When a subfolder of folder \"xyz\" is created, we create a\ndirectory which is called \"xyz.d\" to contain them. This extension \".d\" can be changed\nusing this option.\n\ntrace => LEVEL\ntrusted => BOOLEAN\nwritepolicy => 'REPLACE'|'INPLACE'|undef\n"
                },
                {
                    "name": "The folder",
                    "content": "Extends \"The folder\" in Mail::Box::File.\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::Mbox->appendMessages(%options)\nInherited, see \"METHODS\" in Mail::Box::File\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->filename()\nInherited, see \"The folder\" in Mail::Box::File\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::File.\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::File.\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::File.\n\n$obj->listSubFolders(%options)\nMail::Box::Mbox->listSubFolders(%options)\n-Option             --Defined in     --Default\ncheck                Mail::Box        <false>\nfolder               Mail::Box        <from calling object>\nfolderdir            Mail::Box        <from folder>\nskipempty           Mail::Box        <false>\nsubfolderextension                   <from object>\n\ncheck => BOOLEAN\nfolder => FOLDERNAME\nfolderdir => DIRECTORY\nskipempty => BOOL\nsubfolderextension => STRING\nWhen the method is called on an open folder, the extension defined by it is used to detect\nsub-folders by default. Otherwise, '.d' is taken.\n\n$obj->nameOfSubFolder( $subname, [$parentname] )\nMail::Box::Mbox->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::Mbox->topFolderWithMessages()\nInherited, see \"Sub-folders\" in Mail::Box\n"
                },
                {
                    "name": "Internals",
                    "content": "Extends \"Internals\" in Mail::Box::File.\n\n$obj->coerce($message, %options)\nInherited, see \"Internals\" in Mail::Box\n\n$obj->create($foldername, %options)\nMail::Box::Mbox->create($foldername, %options)\n-Option             --Defined in     --Default\nfolderdir            Mail::Box        undef\nsubfolderextension                   undef\n\nfolderdir => DIRECTORY\nsubfolderextension => STRING\nIf a directory is found on the location of the folder to be created, this STRING is used\nto extend that directory name with. This will cause the directory to be seen as sub-folder\nfor the created folder. This argument is passed to folderToFilename().\n\n$obj->determineBodyType($message, $head)\nInherited, see \"Internals\" in Mail::Box\n\n$obj->folderToFilename( $foldername, $folderdir, [$extension] )\nMail::Box::Mbox->folderToFilename( $foldername, $folderdir, [$extension] )\nTranslate a folder name into a filename, using the $folderdir value to replace a leading\n\"=\". If no $extension is specified and this method is called as instance method,\nnew(subfolderextension) is used. Otherwise, the extension default to '.d'.\n\nMail::Box::Mbox->foundIn( [$foldername], %options )\nIf no $foldername is specified, then the value of the \"folder\" option is taken. A mbox\nfolder is a file which starts with a separator line: a line with 'From ' as first\ncharacters. Blank lines which start the file are ignored, which is not for all MUA's\nacceptable.\n\n-Option             --Defined in     --Default\nfolder                                undef\nfolderdir            Mail::Box        undef\nsubfolderextension                   <from object>\n\nfolder => FOLDERNAME\nfolderdir => DIRECTORY\nsubfolderextension => STRING\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->messageCreateOptions( [$type, $config] )\nInherited, see \"Internals\" in Mail::Box::File\n\n$obj->moveAwaySubFolder($directory, $extension)\nInherited, see \"Internals\" in Mail::Box::File\n\n$obj->parser()\nInherited, see \"Internals\" in Mail::Box::File\n\n$obj->read(%options)\nInherited, see \"Internals\" in Mail::Box\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::File\n\n$obj->write(%options)\nInherited, see \"Internals\" in Mail::Box::File\n\n$obj->writeMessages(%options)\nInherited, see \"Internals\" in Mail::Box\n"
                },
                {
                    "name": "Other methods",
                    "content": "Extends \"Other methods\" in Mail::Box::File.\n\n$obj->timespan2seconds($time)\nMail::Box::Mbox->timespan2seconds($time)\nInherited, see \"Other methods\" in Mail::Box\n"
                },
                {
                    "name": "Error handling",
                    "content": "Extends \"Error handling\" in Mail::Box::File.\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::Mbox->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::Mbox->log( [$level, [$strings]] )\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->logPriority($level)\nMail::Box::Mbox->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::File.\n\n$obj->DESTROY()\nInherited, see \"Cleanup\" in Mail::Box\n\nDETAILS\nExtends \"DETAILS\" in Mail::Box::File.\n"
                }
            ]
        },
        "DETAILS": {
            "content": "Extends \"DETAILS\" in Mail::Box::File.\n",
            "subsections": [
                {
                    "name": "Different kinds of folders",
                    "content": "Extends \"Different kinds of folders\" in Mail::Box::File.\n"
                },
                {
                    "name": "Available folder types",
                    "content": "Extends \"Available folder types\" in Mail::Box::File.\n"
                },
                {
                    "name": "Folder class implementation",
                    "content": "Extends \"Folder class implementation\" in Mail::Box::File.\n"
                },
                {
                    "name": "How MBOX folders work",
                    "content": "MBOX folders store many messages in one file. Each message begins with a line which starts with\nthe string \"From \". Lines inside a message which accidentally start with \"From\" are, in the\nfile, preceded by `>'. This character is stripped when the message is read.\n\nIn this respect must be noted that the format of the MBOX files is not strictly defined. The\nexact content of the separator lines differ between Mail User Agents (MUA's). Besides, some MUAs\n(like mutt) forget to encode the \"From \" lines within message bodies, breaking other parsers....\n"
                },
                {
                    "name": "Simulation of sub-folders",
                    "content": "MBOX folders do not have a sub-folder concept as directory based folders do, but this MBOX\nmodule tries to simulate them. In this implementation a directory like\n\nMail/subject1/\n\nis taken as an empty folder \"Mail/subject1\", with the folders in that directory as sub-folders\nfor it. You may also use\n\nMail/subject1\nMail/subject1.d/\n\nwhere \"Mail/subject1\" is the folder, and the folders in the \"Mail/subject1.d\" directory are used\nas sub-folders. If your situation is similar to the first example and you want to put messages\nin that empty folder, the directory is automatically (and transparently) renamed, so that the\nsecond situation is reached.\n"
                }
            ]
        },
        "DIAGNOSTICS": {
            "content": "Error: Cannot append messages to folder file $filename: $!\nAppending messages to a not-opened file-organized folder may fail when the operating system\ndoes not allow write access to the file at hand.\n\nError: Cannot move away sub-folder $dir\nWarning: Cannot remove folder $name file $filename: $!\nWriting an empty folder will usually cause that folder to be removed, which fails for the\nindicated reason. new(removewhenempty)\n\nWarning: Cannot remove folder $name file $filename: $!\nWriting an empty folder will usually cause that folder to be removed, which fails for the\nindicated reason. new(removewhenempty) controls whether the empty folder will removed;\nsetting it to false (0) may be needed to avoid this message.\n\nError: Cannot replace $filename by $tempname, to update folder $name: $!\nThe replace policy wrote a new folder file to update the existing, but was unable to give\nthe final touch: replacing the old version of the folder file for the indicated reason.\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: File too short to get write message $nr ($size, $need)\nMail::Box is lazy: it tries to leave messages in the folders until they are used, which\nsaves time and memory usage. When this message appears, something is terribly wrong: some\nlazy message are needed for updating the folder, but they cannot be retrieved from the\noriginal file anymore. In this case, messages can be lost.\n\nThis message does appear regularly on Windows systems when using the 'replace' write policy.\nPlease help to find the cause, probably something to do with Windows incorrectly handling\nmultiple filehandles open in the same file.\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 update folder $self.\nWhen a folder is to be written, both replace and inplace write policies are tried, If both\nfail, the whole update fails. You may see other, related, error messages to indicate the\nreal problem.\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::Mbox - handle folders in Mbox format",
    "flags": [],
    "examples": [],
    "see_also": []
}