.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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 >0, 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 "Sympa::LockedFile 3Sympa"
.TH Sympa::LockedFile 3Sympa "2020-12-30" "6.2.58" "sympa 6.2.58"
.\" 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"
Sympa::LockedFile \- Filehandle with locking
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Sympa::LockedFile;
\&  
\&  # Create filehandle acquiring lock.
\&  my $fh = Sympa::LockedFile\->new(\*(Aq/path/to/file\*(Aq, 20, \*(Aq+<\*(Aq) or die;
\&  # or,
\&  my $fh = Sympa::LockedFile\->new();
\&  $fh\->open(\*(Aq/path/to/file\*(Aq, 20, \*(Aq+<\*(Aq) or die;
\&  
\&  # Operations...
\&  while (<$fh>) { ... }
\&  seek $fh, 0, 0;
\&  truncate $fh, 0;
\&  print $fh "blah blah\en";
\&  # et cetera.
\& 
\&  # Close filehandle releasing lock.
\&  $fh\->close;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class implements a filehandle with locking.
.SS "Class Methods"
.IX Subsection "Class Methods"
.ie n .IP "new ( [ $file, [ $blocking_timeout, [ $mode ] ] ] )" 4
.el .IP "new ( [ \f(CW$file\fR, [ \f(CW$blocking_timeout\fR, [ \f(CW$mode\fR ] ] ] )" 4
.IX Item "new ( [ $file, [ $blocking_timeout, [ $mode ] ] ] )"
Creates new object.
If any of optional parameters are specified, opens a file acquiring lock.
.Sp
Parameters:
.Sp
See \fBopen()\fR.
.Sp
Returns:
.Sp
New object or, if something went wrong, false value.
.IP "last_error ( )" 4
.IX Item "last_error ( )"
Get a string describing the most recent error.
.Sp
Parameters:
.Sp
None.
.Sp
Returns:
.Sp
String or, if recent operation was success, \f(CW\*(C`undef\*(C'\fR.
.SS "Instance Methods"
.IX Subsection "Instance Methods"
Instances of Sympa::LockedFile support the methods provided by IO::File.
.ie n .IP "open ( $file, [ $blocking_timeout, [ $mode ] ] )" 4
.el .IP "open ( \f(CW$file\fR, [ \f(CW$blocking_timeout\fR, [ \f(CW$mode\fR ] ] )" 4
.IX Item "open ( $file, [ $blocking_timeout, [ $mode ] ] )"
Opens a file specified by \f(CW$file\fR acquiring lock.
.Sp
Parameters:
.RS 4
.ie n .IP "$file" 4
.el .IP "\f(CW$file\fR" 4
.IX Item "$file"
Path of file to be locked and opened.
.ie n .IP "$blocking_timeout" 4
.el .IP "\f(CW$blocking_timeout\fR" 4
.IX Item "$blocking_timeout"
Programs will block up to the number of seconds specified by this option
before returning undef (could not get a lock).
If negative value was given, programs will not block but fail immediately
(\f(CW\*(C`LOCK_NB\*(C'\fR).
.Sp
Default is \f(CW30\fR.
.Sp
However, if existing lock is older than 1200 seconds i.e. 20 minutes,
lock will be stolen.
.ie n .IP "$mode" 4
.el .IP "\f(CW$mode\fR" 4
.IX Item "$mode"
Mode to open file.
If it implies any writing operations (\f(CW\*(Aq>\*(Aq\fR, \f(CW\*(Aq>>\*(Aq\fR,
\&\f(CW\*(Aq+<\*(Aq\fR, ...), tries to acquire exclusive lock (\f(CW\*(C`LOCK_EX\*(C'\fR),
otherwise shared lock (\f(CW\*(C`LOCK_SH\*(C'\fR).
.Sp
Default is \f(CW\*(Aq<\*(Aq\fR.
.Sp
Additionally, a special mode \f(CW\*(Aq+\*(Aq\fR will acquire exclusive lock
without opening file.  In this case the file does not have to exist.
.Sp
The numeric modes used for \fBsysopen()\fR (e.g. \f(CW\*(C`O_CREAT\*(C'\fR) are not supported.
.RE
.RS 4
.Sp
Returns:
.Sp
New filehandle.
If acquiring lock failed, won't open file.
If opening file failed, releases acquired lock.
In both cases returns false value.
.RE
.IP "close ( )" 4
.IX Item "close ( )"
Closes filehandle and releases lock on it.
.Sp
Note that destruction of instance will safely close filehandle and release
lock.
.Sp
Parameters:
.Sp
None.
.Sp
Returns:
.Sp
If close succeeded, returns true value, otherwise false value.
.Sp
If filehandle had not been locked by current process,
this method will safely close it and die.
.PP
Following methods are specific to this module.
.ie n .IP "basename ( [ $level ] )" 4
.el .IP "basename ( [ \f(CW$level\fR ] )" 4
.IX Item "basename ( [ $level ] )"
Gets base name of locked file.
.IP "extend ( )" 4
.IX Item "extend ( )"
Extends stale lock timeout.
The lock will never be stolen in 1200 seconds again.
.Sp
Parameters:
.Sp
None.
.Sp
Returns:
.Sp
If extension succeeded, returns true value, otherwise false value.
.Sp
If filehandle had not been locked by current process,
this method will die doing nothing.
.ie n .IP "rename ( $destfile )" 4
.el .IP "rename ( \f(CW$destfile\fR )" 4
.IX Item "rename ( $destfile )"
Renames file, closes filehandle and releases lock on it.
Filehandle must have acquired exclusive lock.
.Sp
Parameter:
.RS 4
.ie n .IP "$destfile" 4
.el .IP "\f(CW$destfile\fR" 4
.IX Item "$destfile"
Destination path of renaming.
.RE
.RS 4
.Sp
Returns:
.Sp
If renaming succeeded, returns true value, otherwise false value
and does not release lock.
In both cases filehandle is closed anyway.
.Sp
If filehandle had not been locked by current process,
this method will die doing nothing.
.RE
.IP "unlink ( )" 4
.IX Item "unlink ( )"
Deletes file and releases lock on it.
.Sp
Parameters:
.Sp
None.
.Sp
Returns:
.Sp
If unlink succeeded, returns true value, otherwise false value and
does not release lock.
.Sp
If filehandle had not been locked by current process,
this method will die without deleting file.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\*(L"Functions for filehandles, files or directories\*(R" in perlfunc,
\&\*(L"I/O Operators\*(R" in perlop,
IO::File, File::NFSLock.
.SH "HISTORY"
.IX Header "HISTORY"
Lock module written by Olivier Salau\*:n appeared on Sympa 5.3.
.PP
Support for \s-1NFS\s0 was added by Kazuo Moriwaka.
.PP
Rewritten Sympa::LockedFile module was initially written by \s-1IKEDA\s0 Soji
for Sympa 6.2.