.\" 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 "INN::Utils::Shlock 3pm"
.TH INN::Utils::Shlock 3pm "2023-04-16" "INN 2.7.1" "InterNetNews 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"
INN::Utils::Shlock \- Wrapper around the shlock program
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This Perl module wraps the \fBshlock\fR\|(1) program so that it can easily be used.
Calling \fBshlock\fR is more portable than using \fBflock\fR\|(2) and its corresponding
Perl function because this function does not work as expected on all
existing systems.
.PP
See the \fBshlock\fR\|(1) documentation for more information.
.PP
Using INN::Utils::Shlock is straight-forward:
.PP
.Vb 2
\&    use lib \*(Aq<pathnews>/lib/perl\*(Aq;
\&    use INN::Utils::Shlock;
\&
\&    my $lockfile = "myprogram.LOCK";
\&
\&    # Acquire a lock.
\&    INN::Utils::Shlock::lock($lockfile);
\&
\&    # Do whatever you want.  The lock prevents concurrent accesses.
\&
\&    # Unlock.
\&    INN::Utils::Shlock::unlock($lockfile);
.Ve
.PP
These two functions return \f(CW1\fR on success, \f(CW0\fR on failure.  For example,
the success of (un)locking can be checked as:
.PP
.Vb 2
\&    INN::Utils::Shlock::lock($lockfile)
\&        or die "cannot create lock file";
.Ve
.PP
or:
.PP
.Vb 3
\&    if (! INN::Utils::Shlock::lock($lockfile, 4)) {
\&        die "giving up after 4 attempts to create lock file";
\&    }
.Ve
.PP
Instead of calling \f(CW\*(C`unlock(\f(CIlockfile\f(CW)\*(C'\fR, the \f(CW\*(C`releaselocks()\*(C'\fR
function can be called.  It removes any leftover locks, which is useful
when several different locks are used.  Another possible use is to call
it in an \s-1END\s0 code block:
.PP
.Vb 4
\&    END {
\&        # In case we bail out, while holding a lock.
\&        INN::Utils::Shlock::releaselocks();
\&    }
.Ve
.SH "INTERFACE"
.IX Header "INTERFACE"
.IP "lock(\fIlockfile\fR)" 4
.IX Item "lock(lockfile)"
Tries to create a lock file named \fIlockfile\fR.
.Sp
This function returns \f(CW1\fR on success, \f(CW0\fR on failure.
.IP "lock(\fIlockfile\fR, \fItries\fR)" 4
.IX Item "lock(lockfile, tries)"
Tries to create a lock file named \fIlockfile\fR.  If it fails, locking
attempts are repeated once every 2 seconds for at most \fItries\fR times
(including the first unsuccessful attempt).
.Sp
This function returns \f(CW1\fR on success, \f(CW0\fR on failure.
.IP "lock(\fIlockfile\fR, \fItries\fR, \fIdelay\fR)" 4
.IX Item "lock(lockfile, tries, delay)"
Tries to create a lock file named \fIlockfile\fR.  If it fails, locking
attempts are repeated once every \fIdelay\fR seconds for at most \fItries\fR
times (including the first unsuccessful attempt).
.Sp
Note that \f(CW\*(C`lock(\f(CIlockfile\f(CW)\*(C'\fR is equivalent to \f(CW\*(C`lock(\f(CIlockfile\f(CW,
1, 2)\*(C'\fR.
.Sp
This function returns \f(CW1\fR on success, \f(CW0\fR on failure.
.IP "\fBreleaselocks()\fR" 4
.IX Item "releaselocks()"
Removes all the lock files previously created by calling the \f(CW\*(C`lock(\f(CIlockfile\f(CW)\*(C'\fR function.
.Sp
This function returns the number of removed lock files.
.IP "unlock(\fIlockfile\fR)" 4
.IX Item "unlock(lockfile)"
Removes the file named \fIlockfile\fR.
.Sp
This function returns \f(CW1\fR on success, \f(CW0\fR on failure.
.SH "HISTORY"
.IX Header "HISTORY"
Documentation written by Julien Elie for InterNetNews.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBperl\fR\|(1), \fBshlock\fR\|(1).