{
    "mode": "perldoc",
    "parameter": "Mail::Box::File",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/Mail%3A%3ABox%3A%3AFile/json",
    "generated": "2026-06-11T14:27:42Z",
    "synopsis": "",
    "sections": {
        "NAME": {
            "content": "Mail::Box::File - handle file-based folders\n",
            "subsections": []
        },
        "INHERITANCE": {
            "content": "Mail::Box::File\nis a Mail::Box\nis a Mail::Reporter\n\nMail::Box::File is extended by\nMail::Box::Dbx\nMail::Box::Mbox\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "\"Mail::Box::File\" is the base-class for all file-based folders: folders which bundle multiple\nmessages into one single file. Usually, these messages are separated by a special line which\nindicates the start of the next one.\n\nExtends \"DESCRIPTION\" in Mail::Box.\n",
            "subsections": []
        },
        "OVERLOADED": {
            "content": "Extends \"OVERLOADED\" in Mail::Box.\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.\n",
            "subsections": [
                {
                    "name": "Constructors",
                    "content": "Extends \"Constructors\" in Mail::Box.\n\nMail::Box::File->new(%options)\n-Option           --Defined in     --Default\naccess             Mail::Box        'r'\nbodydelayedtype  Mail::Box        Mail::Message::Body::Delayed\nbodytype                           <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                      '.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::File::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>\nwritepolicy                        undef\n\naccess => MODE\nbodydelayedtype => CLASS\nbodytype => CLASS|CODE\nThe default \"bodytype\" option for \"File\" folders, which will cause messages larger than\n10kB to be stored in files and smaller files in memory, is implemented like this:\n\nsub determinebodytype($$)\n{   my $head = shift;\nmy $size = shift || 0;\n'Mail::Message::Body::'\n. ($size > 10000 ? 'File' : 'Lines');\n}\n\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\nWhen the dotlock locking mechanism is used, the lock is created with a hardlink to the\nfolder file. For \"Mail::Box::File\" type of folders, this file is by default named as the\nfolder-file itself followed by \".lock\". For example: the \"Mail/inbox\" folder file will\nhave a hardlink made as \"Mail/inbox.lock\".\n\nYou may specify an absolute filename, a relative (to the folder's directory) filename, or\nan extension (preceded by a dot). So valid examples are:\n\n.lock        # appended to the folder's filename\nmyownlockfile.test   # full filename, same dir\n/etc/passwd            # somewhere else\n\nWhen the program runs with less privileges (as normal user), often the default inbox\nfolder can not be locked with the lockfile name which is produced by default.\n\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\nwritepolicy => 'REPLACE'|'INPLACE'|undef\nSets the default write policy, as default for a later call to write(policy). With \"undef\",\nthe best policy is autodetected.\n"
                },
                {
                    "name": "The folder",
                    "content": "Extends \"The folder\" in Mail::Box.\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::File->appendMessages(%options)\nAppending messages to a file based folder which is not opened is a little risky. In\npractice, this is often done without locking the folder. So, another application may write\nto the folder at the same time... :( Hopefully, all goes fast enough that the chance on\ncollision is small.\n\nAll %options of Mail::Box::Mbox::new() can be supplied.\n\n-Option   --Defined in     --Default\nfolder     Mail::Box        <required>\nlocktype                   NONE\nmessage    Mail::Box        undef\nmessages   Mail::Box        undef\nshare      Mail::Box        <false>\n\nfolder => FOLDERNAME\nlocktype => ...\nSee Mail::Box::new(locktype) for possible values.\n\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->filename()\nReturns the filename for this folder, which may be an absolute or relative path to the file.\n\nexample:\n\nprint $folder->filename;\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.\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.\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.\n\n$obj->listSubFolders(%options)\nMail::Box::File->listSubFolders(%options)\nInherited, see \"Sub-folders\" in Mail::Box\n\n$obj->nameOfSubFolder( $subname, [$parentname] )\nMail::Box::File->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::File->topFolderWithMessages()\nInherited, see \"Sub-folders\" in Mail::Box\n"
                },
                {
                    "name": "Internals",
                    "content": "Extends \"Internals\" in Mail::Box.\n\n$obj->coerce($message, %options)\nInherited, see \"Internals\" in Mail::Box\n\n$obj->create($foldername, %options)\nMail::Box::File->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->folderToFilename( $foldername, $folderdir, [$subext] )\nMail::Box::File->folderToFilename( $foldername, $folderdir, [$subext] )\nTranslate a folder name into a filename, using the $folderdir value to replace a leading\n\"=\". $subext is only used for MBOX folders.\n\nMail::Box::File->foundIn( [$foldername], %options )\nInherited, see \"Internals\" in Mail::Box\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] )\nReturns a key-value list of options to be used each time a new message is read from a file.\nThe list is preceded by the $type of message which has to be created.\n\nThis data is used by readMessages() and updateMessages(). With $type and $config, a new\nconfiguration is set.\n\n$obj->moveAwaySubFolder($directory, $extension)\nThe $directory is renamed by appending the $extension, which defaults to \".d\", to make place\nfor a folder file on that specific location. \"false\" is returned if this failed.\n\n$obj->parser()\nCreate a parser for this mailbox. The parser stays alive as long as the folder is open.\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)\nFor file based folders, the file handle stays open until the folder is closed. Update is\ntherefore rather simple: move to the end of the last known message, and continue reading...\n\n$obj->write(%options)\n-Option      --Defined in     --Default\nforce         Mail::Box        <false>\npolicy                         undef\nsavedeleted  Mail::Box        <false>\n\nforce => BOOLEAN\npolicy => 'REPLACE'|'INPLACE'|undef\nIn what way will the mail folder be updated. If not specified during the write, the value\nof the new(writepolicy) at folder creation is taken.\n\nValid values:\n\n*   \"REPLACE\"\n\nFirst a new folder is written in the same directory as the folder which has to be\nupdated, and then a call to move will throw away the old immediately replacing it by\nthe new.\n\nWriting in \"REPLACE\" module is slightly optimized: messages which are not modified are\ncopied from file to file, byte by byte. This is much faster than printing the data\nwhich is will be done for modified messages.\n\n*   \"INPLACE\"\n\nThe original folder file will be opened read/write. All message which where not\nchanged will be left untouched, until the first deleted or modified message is\ndetected. All further messages are printed again.\n\n*   \"undef\"\n\nAs default, or when \"undef\" is explicitly specified, first \"REPLACE\" mode is tried.\nOnly when that fails, an \"INPLACE\" update is performed.\n\n\"INPLACE\" will be much faster than \"REPLACE\" when applied on large folders, however\nrequires the \"truncate\" function to be implemented on your operating system (at least\navailable for recent versions of Linux, Solaris, Tru64, HPUX). It is also dangerous: when\nthe program is interrupted during the update process, the folder is corrupted. Data may be\nlost.\n\nHowever, in some cases it is not possible to write the folder with \"REPLACE\". For\ninstance, the usual incoming mail folder on UNIX is stored in a directory where a user can\nnot write. Of course, the \"root\" and \"mail\" users can, but if you want to use this Perl\nmodule with permission of a normal user, you can only get it to work in \"INPLACE\" mode. Be\nwarned that in this case folder locking via a lockfile is not possible as well.\n\nsavedeleted => BOOLEAN\n\n$obj->writeMessages(%options)\nInherited, see \"Internals\" in Mail::Box\n"
                },
                {
                    "name": "Other methods",
                    "content": "Extends \"Other methods\" in Mail::Box.\n\n$obj->timespan2seconds($time)\nMail::Box::File->timespan2seconds($time)\nInherited, see \"Other methods\" in Mail::Box\n"
                },
                {
                    "name": "Error handling",
                    "content": "Extends \"Error handling\" in Mail::Box.\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::File->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::File->log( [$level, [$strings]] )\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->logPriority($level)\nMail::Box::File->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.\n\n$obj->DESTROY()\nInherited, see \"Cleanup\" in Mail::Box\n\nDETAILS\nFile based folders\nFile based folders maintain a folder (a set of messages) in one single file. The advantage is\nthat your folder has only one single name, which speeds-up access to all messages at once.\n\nThe disadvantage over directory based folder (see Mail::Box::Dir) is that you have to construct\nsome means to keep all message apart, for instance by adding a message separator, and this will\ncause problems. Where access to all messages at once is faster in file based folders, access to\na single message is (much) slower, because the whole folder must be read.\n"
                }
            ]
        },
        "DETAILS": {
            "content": "Extends \"DETAILS\" in Mail::Box.\n",
            "subsections": []
        },
        "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 create directory $dir for folder $name.\nWhile creating a file-organized folder, at most one level of directories is created above\nit. Apparently, more levels of directories are needed, or the operating system does not\nallow you to create the directory.\n\nError: Cannot create folder file $name: $!\nThe file-organized folder file cannot be created for the indicated reason. In common cases,\nthe operating system does not grant you write access to the directory where the folder file\nshould be stored.\n\nError: Cannot get a lock on $type folder $self.\nA lock is required to get access to the folder. If no locking is needed, specify the NONE\nlock type.\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\nWarning: Folder $name file $filename is write-protected.\nThe folder is opened writable or for appending via new(access), but the operating system\ndoes not permit writing to the file. The folder will be opened read-only.\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::File - handle file-based folders",
    "flags": [],
    "examples": [],
    "see_also": []
}