.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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
.\" ========================================================================
.\"
.IX Title "Paranoid::IO::Lockfile 3pm"
.TH Paranoid::IO::Lockfile 3pm 2024-03-07 "perl v5.38.2" "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
Paranoid::IO::Lockfile \- Paranoid Lockfile support
.SH VERSION
.IX Header "VERSION"
\&\f(CW$Id:\fR lib/Paranoid/IO/Lockfile.pm, 2.10 2022/03/08 00:01:04 acorliss Exp $
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 3
\&  use Paranoid::IO::Lockfile;
\&  use Fcntl qw(:flock);  # only needed if you use plock in lieu 
\&                         # of the other functions
\&
\&  $rv = plock($lockfile);
\&  $rv = plock($lockfile, LOCK_SH | LOCK_NB);
\&  $rv = plock($lockfile, LOCK_SH | LOCK_NB, $mode);
\&
\&  $rv = pexclock($lockfile);
\&  $rv = pshlock($lockfile);
\&  $rv = punlock($lockfile);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This module provides convenience functions for using a lockfile to coordinate
multi-process activities.  While basically just a thin wrapper for
Paranoid::IO functions it removes the small tedium of having to perform
the multiple opens required to ensure all processes are working off the same
files while avoiding race conditions.
.SH "IMPORT LISTS"
.IX Header "IMPORT LISTS"
This module exports the following symbols by default:
.PP
.Vb 1
\&    plock pexclock pshlock punlock
.Ve
.PP
The following specialized import lists also exist:
.PP
.Vb 3
\&    List        Members
\&    \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&    all         @defaults
.Ve
.SH SUBROUTINES/METHODS
.IX Header "SUBROUTINES/METHODS"
.SS plock
.IX Subsection "plock"
.Vb 3
\&  $rv = plock($filename);
\&  $rv = plock($filename, LOCK_EX);
\&  $rv = plock($filename, LOCK_EX, 0666);
.Ve
.PP
Creates or opens the requested file while applying the lock condition.  The
lock type defaults to \fBLOCK_EX\fR if omitted, while the file permissions
default to \fB0660\fR.  As always, umask applies.
.PP
There is one scenario in which one would want to use \fIplock\fR in lieu of
\&\fIpexclock\fR, etc:  if you wish to perform non-blocking lock attempts.  All
convenience functions are blocking.
.SS pexclock
.IX Subsection "pexclock"
.Vb 2
\&  $rv = pexclock($filename);
\&  $rv = pexclock($filename, $mode);
.Ve
.PP
A wrapper for \fBplock($filename, LOCK_EX)\fR.
.SS pshlock
.IX Subsection "pshlock"
.Vb 2
\&  $rv = pshlock($filename);
\&  $rv = pshlock($filename, $mode);
.Ve
.PP
A wrapper for \fBplock($filename, LOCK_SH)\fR.
.SS punlock
.IX Subsection "punlock"
.Vb 2
\&  $rv = punlock($filename);
\&  $rv = punlock($filename, $mode);
.Ve
.PP
A wrapper for \fBplock($filename, LOCK_UN)\fR.  This does not close the open 
file handle to the lock file.  For that you need to call Paranoid::IO's
\&\fIpclose\fR function.
.SH DEPENDENCIES
.IX Header "DEPENDENCIES"
.IP o 4
.IX Item "o"
Fcntl
.IP o 4
.IX Item "o"
Paranoid
.IP o 4
.IX Item "o"
Paranoid::Debug
.IP o 4
.IX Item "o"
Paranoid::IO
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
.SH AUTHOR
.IX Header "AUTHOR"
Arthur Corliss (corliss@digitalmages.com)
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
This software is free software.  Similar to Perl, you can redistribute it
and/or modify it under the terms of either:
.PP
.Vb 7
\&  a)     the GNU General Public License
\&         <https://www.gnu.org/licenses/gpl\-1.0.html> as published by the 
\&         Free Software Foundation <http://www.fsf.org/>; either version 1
\&         <https://www.gnu.org/licenses/gpl\-1.0.html>, or any later version
\&         <https://www.gnu.org/licenses/license\-list.html#GNUGPL>, or
\&  b)     the Artistic License 2.0
\&         <https://opensource.org/licenses/Artistic\-2.0>,
.Ve
.PP
subject to the following additional term:  No trademark rights to
"Paranoid" have been or are conveyed under any of the above licenses.
However, "Paranoid" may be used fairly to describe this unmodified
software, in good faith, but not as a trademark.
.PP
(c) 2005 \- 2020, Arthur Corliss (corliss@digitalmages.com)
(tm) 2008 \- 2020, Paranoid Inc. (www.paranoid.com)