.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Mail::Box::Locker 3pm"
.TH Mail::Box::Locker 3pm "2014-08-24" "perl v5.20.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Mail::Box::Locker \- manage the locking of mail folders
.SH "INHERITANCE"
.IX Header "INHERITANCE"
.Vb 2
\& Mail::Box::Locker
\&   is a Mail::Reporter
\&
\& Mail::Box::Locker is extended by
\&   Mail::Box::Locker::DotLock
\&   Mail::Box::Locker::FcntlLock
\&   Mail::Box::Locker::Flock
\&   Mail::Box::Locker::Multi
\&   Mail::Box::Locker::Mutt
\&   Mail::Box::Locker::NFS
\&   Mail::Box::Locker::POSIX
.Ve
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& use Mail::Box::Locker;
\& my $locker = new Mail::Box::Locker(folder => $folder);
\&
\& $locker\->lock;
\& $locker\->isLocked;
\& $locker\->hasLock;
\& $locker\->unlock;
\&
\& use Mail::Box;
\& my $folder = Mail::Box\->new(lock_method => \*(AqDOTLOCK\*(Aq);
\& print $folder\->locker\->type;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Each Mail::Box will create its own \f(CW\*(C`Mail::Box::Locker\*(C'\fR object which
will handle the locking for it.  You can access of the object directly
from the folder, as shown in the examples below.
.PP
Extends \*(L"\s-1DESCRIPTION\*(R"\s0 in Mail::Reporter.
.SH "METHODS"
.IX Header "METHODS"
Extends \*(L"\s-1METHODS\*(R"\s0 in Mail::Reporter.
.SS "Constructors"
.IX Subsection "Constructors"
Extends \*(L"Constructors\*(R" in Mail::Reporter.
.IP "Mail::Box::Locker\->\fBnew\fR(%options)" 4
.IX Item "Mail::Box::Locker->new(%options)"
Create a new lock. You may do this directly. However, in most cases the
lock will not be separately instantiated but will be the second class in
a multiple inheritance construction with a Mail::Box.
.Sp
Generally the client program specifies the locking behavior through
options given to the folder class.
.Sp
.Vb 8
\& \-Option \-\-Defined in     \-\-Default
\&  expires                   1 hour
\&  file                      undef
\&  folder                    <undef>
\&  log      Mail::Reporter   \*(AqWARNINGS\*(Aq
\&  method                    \*(AqDOTLOCK\*(Aq
\&  timeout                   10 seconds
\&  trace    Mail::Reporter   \*(AqWARNINGS\*(Aq
.Ve
.RS 4
.IP "expires => \s-1SECONDS\s0" 2
.IX Item "expires => SECONDS"
How long can a lock exist?  If a different e\-mail program leaves a stale
lock, then this lock will be removed automatically after the specified
number of seconds.
.IP "file => \s-1FILENAME\s0" 2
.IX Item "file => FILENAME"
Name of the file to lock.  By default, the name of the folder is taken.
.IP "folder => \s-1FOLDER\s0" 2
.IX Item "folder => FOLDER"
Which \s-1FOLDER\s0 is to be locked, a Mail::Box object.
.IP "log => \s-1LEVEL\s0" 2
.IX Item "log => LEVEL"
.PD 0
.IP "method => STRING|CLASS|ARRAY" 2
.IX Item "method => STRING|CLASS|ARRAY"
.PD
Which kind of locking, specified as one of the following names as \s-1STRING.\s0
You may also specify a \s-1CLASS\s0 name, or an \s-1ARRAY\s0 of names.  In case of an
\&\s-1ARRAY,\s0 a 'multi' locker is started with all thee 
full \s-1CLASS\s0 name.
.Sp
Supported locking names are
.RS 2
.IP "'\s-1DOTLOCK\s0' | 'dotlock'" 4
.IX Item "'DOTLOCK' | 'dotlock'"
The folder handler creates a file which signals that it is in use.  This
is a bit problematic, because not all mail-handling software agree on
the name of the file to be created.
.Sp
On various folder types, the lockfile differs.  See the documentation for
each folder, which describes the locking strategy as well as special
options to change the default behavior.
.IP "'\s-1FLOCK\s0' | 'flock'" 4
.IX Item "'FLOCK' | 'flock'"
For some folder handlers, locking is based on a file locking mechanism
provided by the operating system.  However, this does not work on all
systems, such as network filesystems, and such. This also doesn't work on
folders based on directories (Mail::Box::Dir and derived).
.IP "'\s-1FCNTLLOCK\s0' | 'fcntllock'" 4
.IX Item "'FCNTLLOCK' | 'fcntllock'"
\&\s-1POSIX\s0 locking via File::FcntlLock, which works on more platforms.
However, that module requires a C compiler to install.
.IP "'\s-1POSIX\s0' | 'posix'" 4
.IX Item "'POSIX' | 'posix'"
Use the \s-1POSIX\s0 standard fcntl locking.
.IP "'\s-1MULTI\s0' | 'multi'" 4
.IX Item "'MULTI' | 'multi'"
Use \s-1ALL\s0 available locking methods at the same time, to have a bigger
chance that the folder will not be modified by some other application
which uses an unspecified locking method.  When one of the locking
methods disallows access, the locking fails.
.IP "'\s-1MUTT\s0'| 'mutt'" 4
.IX Item "'MUTT'| 'mutt'"
Use the external program 'mutt_dotlock' to lock and unlock.
.IP "'\s-1NFS\s0' | 'nfs'" 4
.IX Item "'NFS' | 'nfs'"
A kind of \f(CW\*(C`dotlock\*(C'\fR file-locking mechanism, but adapted to work over
\&\s-1NFS. \s0 Extra precaution is needed because an \f(CW\*(C`open O_EXCL\*(C'\fR on \s-1NFS\s0 is
not an atomic action.
.IP "'\s-1NONE\s0' | 'none'" 4
.IX Item "'NONE' | 'none'"
Do not use locking.
.RE
.RS 2
.Sp
The other option is to produce your own \f(CW\*(C`Mail::Box::Locker\*(C'\fR derived class,
which implements the desired locking method. (Please consider offering it
for inclusion in the public Mail::Box module!) Create an instance of that
class with this parameter:
.Sp
.Vb 2
\& my $locker = Mail::Box::Locker::MyOwn\->new;
\& $folder\->open(locker => $locker);
.Ve
.RE
.IP "timeout => SECONDS|'\s-1NOTIMEOUT\s0'" 2
.IX Item "timeout => SECONDS|'NOTIMEOUT'"
How long to wait while trying to acquire the lock. The lock request will
fail when the specified number of seconds is reached.  If \f(CW\*(AqNOTIMEOUT\*(Aq\fR is
specified, the module will wait until the lock can be taken.
.Sp
Whether it is possible to limit the wait time is platform\- and
locking-method-specific.  For instance, the `dotlock' method on Windows
will always wait until the lock has been received.
.IP "trace => \s-1LEVEL\s0" 2
.IX Item "trace => LEVEL"
.RE
.RS 4
.RE
.SS "The Locker"
.IX Subsection "The Locker"
.PD 0
.ie n .IP "$obj\->\fBfilename\fR( [$filename] )" 4
.el .IP "\f(CW$obj\fR\->\fBfilename\fR( [$filename] )" 4
.IX Item "$obj->filename( [$filename] )"
.PD
Returns the filename which is used to lock the folder, optionally after
setting it to the specified \f(CW$filename\fR.
.Sp
example:
.Sp
.Vb 1
\& print $locker\->filename;
.Ve
.ie n .IP "$obj\->\fBfolder\fR( [$folder] )" 4
.el .IP "\f(CW$obj\fR\->\fBfolder\fR( [$folder] )" 4
.IX Item "$obj->folder( [$folder] )"
Returns the folder object which is locker.
.ie n .IP "$obj\->\fBname\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBname\fR()" 4
.IX Item "$obj->name()"
Returns the method used to lock the folder. See the new(method) for
details on how to specify the lock method.  The name of the method is
returned in upper-case.
.Sp
example:
.Sp
.Vb 1
\& if($locker\->name eq \*(AqFLOCK\*(Aq) ...
.Ve
.SS "Locking"
.IX Subsection "Locking"
.ie n .IP "$obj\->\fBhasLock\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBhasLock\fR()" 4
.IX Item "$obj->hasLock()"
Check whether the folder has the lock.
.Sp
example:
.Sp
.Vb 2
\& if($locker\->hasLock) {...}
\& if($folder\->locker\->hasLock) {...}
.Ve
.ie n .IP "$obj\->\fBisLocked\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBisLocked\fR()" 4
.IX Item "$obj->isLocked()"
Test if the folder is locked by this or a different application.
.Sp
example:
.Sp
.Vb 2
\& if($locker\->isLocked) {...}
\& if($folder\->locker\->isLocked) {...}
.Ve
.ie n .IP "$obj\->\fBlock\fR($folder)" 4
.el .IP "\f(CW$obj\fR\->\fBlock\fR($folder)" 4
.IX Item "$obj->lock($folder)"
Get a lock on a folder.  This will return false if the lock fails.
.Sp
example:
.Sp
.Vb 2
\& die unless $locker\->lock;
\& if($folder\->locker\->lock) {...}
.Ve
.ie n .IP "$obj\->\fBunlock\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBunlock\fR()" 4
.IX Item "$obj->unlock()"
Undo the lock on a folder.
.Sp
example:
.Sp
.Vb 2
\& $locker\->unlock;
\& $folder\->locker\->unlock;
.Ve
.SS "Error handling"
.IX Subsection "Error handling"
Extends \*(L"Error handling\*(R" in Mail::Reporter.
.ie n .IP "$obj\->\fB\s-1AUTOLOAD\s0\fR()" 4
.el .IP "\f(CW$obj\fR\->\fB\s-1AUTOLOAD\s0\fR()" 4
.IX Item "$obj->AUTOLOAD()"
Inherited, see \*(L"Error handling\*(R" in Mail::Reporter
.ie n .IP "$obj\->\fBaddReport\fR($object)" 4
.el .IP "\f(CW$obj\fR\->\fBaddReport\fR($object)" 4
.IX Item "$obj->addReport($object)"
Inherited, see \*(L"Error handling\*(R" in Mail::Reporter
.ie n .IP "$obj\->\fBdefaultTrace\fR( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )" 4
.el .IP "\f(CW$obj\fR\->\fBdefaultTrace\fR( [$level]|[$loglevel, \f(CW$tracelevel\fR]|[$level, \f(CW$callback\fR] )" 4
.IX Item "$obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )"
.PD 0
.ie n .IP "Mail::Box::Locker\->\fBdefaultTrace\fR( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )" 4
.el .IP "Mail::Box::Locker\->\fBdefaultTrace\fR( [$level]|[$loglevel, \f(CW$tracelevel\fR]|[$level, \f(CW$callback\fR] )" 4
.IX Item "Mail::Box::Locker->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )"
.PD
Inherited, see \*(L"Error handling\*(R" in Mail::Reporter
.ie n .IP "$obj\->\fBerrors\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBerrors\fR()" 4
.IX Item "$obj->errors()"
Inherited, see \*(L"Error handling\*(R" in Mail::Reporter
.ie n .IP "$obj\->\fBlog\fR( [$level, [$strings]] )" 4
.el .IP "\f(CW$obj\fR\->\fBlog\fR( [$level, [$strings]] )" 4
.IX Item "$obj->log( [$level, [$strings]] )"
.PD 0
.IP "Mail::Box::Locker\->\fBlog\fR( [$level, [$strings]] )" 4
.IX Item "Mail::Box::Locker->log( [$level, [$strings]] )"
.PD
Inherited, see \*(L"Error handling\*(R" in Mail::Reporter
.ie n .IP "$obj\->\fBlogPriority\fR($level)" 4
.el .IP "\f(CW$obj\fR\->\fBlogPriority\fR($level)" 4
.IX Item "$obj->logPriority($level)"
.PD 0
.IP "Mail::Box::Locker\->\fBlogPriority\fR($level)" 4
.IX Item "Mail::Box::Locker->logPriority($level)"
.PD
Inherited, see \*(L"Error handling\*(R" in Mail::Reporter
.ie n .IP "$obj\->\fBlogSettings\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBlogSettings\fR()" 4
.IX Item "$obj->logSettings()"
Inherited, see \*(L"Error handling\*(R" in Mail::Reporter
.ie n .IP "$obj\->\fBnotImplemented\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBnotImplemented\fR()" 4
.IX Item "$obj->notImplemented()"
Inherited, see \*(L"Error handling\*(R" in Mail::Reporter
.ie n .IP "$obj\->\fBreport\fR( [$level] )" 4
.el .IP "\f(CW$obj\fR\->\fBreport\fR( [$level] )" 4
.IX Item "$obj->report( [$level] )"
Inherited, see \*(L"Error handling\*(R" in Mail::Reporter
.ie n .IP "$obj\->\fBreportAll\fR( [$level] )" 4
.el .IP "\f(CW$obj\fR\->\fBreportAll\fR( [$level] )" 4
.IX Item "$obj->reportAll( [$level] )"
Inherited, see \*(L"Error handling\*(R" in Mail::Reporter
.ie n .IP "$obj\->\fBtrace\fR( [$level] )" 4
.el .IP "\f(CW$obj\fR\->\fBtrace\fR( [$level] )" 4
.IX Item "$obj->trace( [$level] )"
Inherited, see \*(L"Error handling\*(R" in Mail::Reporter
.ie n .IP "$obj\->\fBwarnings\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBwarnings\fR()" 4
.IX Item "$obj->warnings()"
Inherited, see \*(L"Error handling\*(R" in Mail::Reporter
.SS "Cleanup"
.IX Subsection "Cleanup"
Extends \*(L"Cleanup\*(R" in Mail::Reporter.
.ie n .IP "$obj\->\fB\s-1DESTROY\s0\fR()" 4
.el .IP "\f(CW$obj\fR\->\fB\s-1DESTROY\s0\fR()" 4
.IX Item "$obj->DESTROY()"
When the locker is destroyed, for instance when the folder is closed
or the program ends, the lock will be automatically removed.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
.ie n .IP "Error: Package $package does not implement $method." 4
.el .IP "Error: Package \f(CW$package\fR does not implement \f(CW$method\fR." 4
.IX Item "Error: Package $package does not implement $method."
Fatal error: the specific package (or one of its superclasses) does not
implement this method where it should. This message means that some other
related classes do implement this method however the class at hand does
not.  Probably you should investigate this and probably inform the author
of the package.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
This module is part of Mail-Box distribution version 2.117,
built on August 24, 2014. Website: \fIhttp://perl.overmeer.net/mailbox/\fR
.SH "LICENSE"
.IX Header "LICENSE"
Copyrights 2001\-2014 by [Mark Overmeer]. For other contributors see ChangeLog.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See \fIhttp://www.perl.com/perl/misc/Artistic.html\fR