{
    "mode": "perldoc",
    "parameter": "Mail::Box::Locker",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/Mail%3A%3ABox%3A%3ALocker/json",
    "generated": "2026-06-09T20:30:44Z",
    "synopsis": "use Mail::Box::Locker;\nmy $locker = new Mail::Box::Locker(folder => $folder);\n$locker->lock;\n$locker->isLocked;\n$locker->hasLock;\n$locker->unlock;\nuse Mail::Box;\nmy $folder = Mail::Box->new(lockmethod => 'DOTLOCK');\nprint $folder->locker->type;",
    "sections": {
        "NAME": {
            "content": "Mail::Box::Locker - manage the locking of mail folders\n",
            "subsections": []
        },
        "INHERITANCE": {
            "content": "Mail::Box::Locker\nis a Mail::Reporter\n\nMail::Box::Locker is extended by\nMail::Box::Locker::DotLock\nMail::Box::Locker::FcntlLock\nMail::Box::Locker::Flock\nMail::Box::Locker::Multi\nMail::Box::Locker::Mutt\nMail::Box::Locker::NFS\nMail::Box::Locker::POSIX\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "use Mail::Box::Locker;\nmy $locker = new Mail::Box::Locker(folder => $folder);\n\n$locker->lock;\n$locker->isLocked;\n$locker->hasLock;\n$locker->unlock;\n\nuse Mail::Box;\nmy $folder = Mail::Box->new(lockmethod => 'DOTLOCK');\nprint $folder->locker->type;\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "Each Mail::Box will create its own \"Mail::Box::Locker\" object which will handle the locking for\nit. You can access of the object directly from the folder, as shown in the examples below.\n\nExtends \"DESCRIPTION\" in Mail::Reporter.\n",
            "subsections": []
        },
        "METHODS": {
            "content": "Extends \"METHODS\" in Mail::Reporter.\n",
            "subsections": [
                {
                    "name": "Constructors",
                    "content": "Extends \"Constructors\" in Mail::Reporter.\n\nMail::Box::Locker->new(%options)\nCreate a new lock. You may do this directly. However, in most cases the lock will not be\nseparately instantiated but will be the second class in a multiple inheritance construction\nwith a Mail::Box.\n\nGenerally the client program specifies the locking behavior through options given to the\nfolder class.\n\n-Option --Defined in     --Default\nexpires                   1 hour\nfile                      undef\nfolder                    <undef>\nlog      Mail::Reporter   'WARNINGS'\nmethod                    'DOTLOCK'\ntimeout                   10\ntrace    Mail::Reporter   'WARNINGS'\n\nexpires => SECONDS\nHow long can a lock exist? If a different e-mail program leaves a stale lock, then this\nlock will be removed automatically after the specified number of seconds.\n\nfile => FILENAME\nName of the file to lock. By default, the name of the folder is taken.\n\nfolder => FOLDER\nWhich FOLDER is to be locked, a Mail::Box object.\n\nlog => LEVEL\nmethod => STRING|CLASS|ARRAY\nWhich kind of locking, specified as one of the following names as STRING. You may also\nspecify a CLASS name, or an ARRAY of names. In case of an ARRAY, a 'multi' locker is\nstarted with all thee full CLASS name.\n\nSupported locking names are\n\n'DOTLOCK' | 'dotlock'\nThe folder handler creates a file which signals that it is in use. This is a bit\nproblematic, because not all mail-handling software agree on the name of the file to\nbe created.\n\nOn various folder types, the lockfile differs. See the documentation for each folder,\nwhich describes the locking strategy as well as special options to change the default\nbehavior.\n\n'FLOCK' | 'flock'\nFor some folder handlers, locking is based on a file locking mechanism provided by the\noperating system. However, this does not work on all systems, such as network\nfilesystems, and such. This also doesn't work on folders based on directories\n(Mail::Box::Dir and derived).\n\n'FCNTLLOCK' | 'fcntllock'\nPOSIX locking via File::FcntlLock, which works on more platforms. However, that module\nrequires a C compiler to install.\n\n'POSIX' | 'posix'\nUse the POSIX standard fcntl locking.\n\n'MULTI' | 'multi'\nUse ALL available locking methods at the same time, to have a bigger chance that the\nfolder will not be modified by some other application which uses an unspecified\nlocking method. When one of the locking methods disallows access, the locking fails.\n\n'MUTT'| 'mutt'\nUse the external program 'muttdotlock' to lock and unlock.\n\n'NFS' | 'nfs'\nA kind of \"dotlock\" file-locking mechanism, but adapted to work over NFS. Extra\nprecaution is needed because an \"open OEXCL\" on NFS is not an atomic action.\n\n'NONE' | 'none'\nDo not use locking.\n\nThe other option is to produce your own \"Mail::Box::Locker\" derived class, which\nimplements the desired locking method. (Please consider offering it for inclusion in the\npublic Mail::Box module!) Create an instance of that class with this parameter:\n\nmy $locker = Mail::Box::Locker::MyOwn->new;\n$folder->open(locker => $locker);\n\ntimeout => SECONDS|'NOTIMEOUT'\nHow long to wait while trying to acquire the lock. The lock request will fail when the\nspecified number of seconds is reached. If 'NOTIMEOUT' is specified, the module will wait\nuntil the lock can be taken.\n\nWhether it is possible to limit the wait time is platform- and locking-method-specific.\nFor instance, the `dotlock' method on Windows will always wait until the lock has been\nreceived.\n\ntrace => LEVEL\n"
                },
                {
                    "name": "Attributes",
                    "content": "$obj->expires( [SECONDS] )\nGet/Set the expiration time. Not available for all lockers.\n\n$obj->timeout( [SECONDS] )\nGet/Set the timeout. Not available for all lockers.\n"
                },
                {
                    "name": "The Locker",
                    "content": "$obj->filename( [$filename] )\nReturns the filename which is used to lock the folder, optionally after setting it to the\nspecified $filename.\n\nexample:\n\nprint $locker->filename;\n\n$obj->folder( [$folder] )\nReturns the folder object which is locker.\n\n$obj->name()\nReturns the method used to lock the folder. See the new(method) for details on how to\nspecify the lock method. The name of the method is returned in upper-case.\n\nexample:\n\nif($locker->name eq 'FLOCK') ...\n"
                },
                {
                    "name": "Locking",
                    "content": "$obj->hasLock()\nCheck whether the folder has the lock.\n\nexample:\n\nif($locker->hasLock) {...}\nif($folder->locker->hasLock) {...}\n\n$obj->isLocked()\nTest if the folder is locked by this or a different application.\n\nexample:\n\nif($locker->isLocked) {...}\nif($folder->locker->isLocked) {...}\n\n$obj->lock($folder)\nGet a lock on a folder. This will return false if the lock fails.\n\nexample:\n\ndie unless $locker->lock;\nif($folder->locker->lock) {...}\n\n$obj->unlock()\nUndo the lock on a folder.\n\nexample:\n\n$locker->unlock;\n$folder->locker->unlock;\n"
                },
                {
                    "name": "Error handling",
                    "content": "Extends \"Error handling\" in Mail::Reporter.\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::Locker->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::Locker->log( [$level, [$strings]] )\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->logPriority($level)\nMail::Box::Locker->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::Reporter.\n\n$obj->DESTROY()\nWhen the locker is destroyed, for instance when the folder is closed or the program ends,\nthe lock will be automatically removed.\n"
                }
            ]
        },
        "DIAGNOSTICS": {
            "content": "Error: 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",
            "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::Locker - manage the locking of mail folders",
    "flags": [],
    "examples": [],
    "see_also": []
}