.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
.\"
.\" 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
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "Config::Watch 3"
.TH Config::Watch 3 2026-08-14 "perl v5.42.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
Log::Log4perl::Config::Watch \- Detect file changes
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&    use Log::Log4perl::Config::Watch;
\&
\&    my $watcher = Log::Log4perl::Config::Watch\->new(
\&                          file            => "/data/my.conf",
\&                          check_interval  => 30,
\&                  );
\&
\&    while(1) {
\&        if($watcher\->change_detected()) {
\&            print "Change detected!\en";
\&        }
\&        sleep(1);
\&    }
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This module helps detecting changes in files. Although it comes with the
\&\f(CW\*(C`Log::Log4perl\*(C'\fR distribution, it can be used independently.
.PP
The constructor defines the file to be watched and the check interval 
in seconds. Subsequent calls to \f(CWchange_detected()\fR will
.IP \(bu 4
return a false value immediately without doing physical file checks
if \f(CW\*(C`check_interval\*(C'\fR hasn\*(Aqt elapsed.
.IP \(bu 4
perform a physical test on the specified file if the number
of seconds specified in \f(CW\*(C`check_interval\*(C'\fR 
have elapsed since the last physical check. If the file\*(Aqs modification
date has changed since the last physical check, it will return a true 
value, otherwise a false value is returned.
.PP
Bottom line: \f(CW\*(C`check_interval\*(C'\fR allows you to call the function
\&\f(CWchange_detected()\fR as often as you like, without paying the performing
a significant performance penalty because file system operations 
are being performed (however, you pay the price of not knowing about
file changes until \f(CW\*(C`check_interval\*(C'\fR seconds have elapsed).
.PP
The module clearly distinguishes system time from file system time. 
If your (e.g. NFS mounted) file system is off by a constant amount
of time compared to the executing computer\*(Aqs clock, it\*(Aqll just
work fine.
.PP
To disable the resource\-saving delay feature, just set \f(CW\*(C`check_interval\*(C'\fR 
to 0 and \f(CWchange_detected()\fR will run a physical file test on
every call.
.PP
If you already have the current time available, you can pass it
on to \f(CWchange_detected()\fR as an optional parameter, like in
.PP
.Vb 1
\&    change_detected($time)
.Ve
.PP
which then won\*(Aqt trigger a call to \f(CWtime()\fR, but use the value
provided.
.SS "SIGNAL MODE"
.IX Subsection "SIGNAL MODE"
Instead of polling time and file changes, \f(CWnew()\fR can be instructed 
to set up a signal handler. If you call the constructor like
.PP
.Vb 4
\&    my $watcher = Log::Log4perl::Config::Watch\->new(
\&                          file    => "/data/my.conf",
\&                          signal  => \*(AqHUP\*(Aq
\&                  );
.Ve
.PP
then a signal handler will be installed, setting the object\*(Aqs variable 
\&\f(CW\*(C`$self\->{signal_caught}\*(C'\fR to a true value when the signal arrives.
Comes with all the problems that signal handlers go along with.
.SS "TRIGGER CHECKS"
.IX Subsection "TRIGGER CHECKS"
To trigger a physical file check on the next call to \f(CWchange_detected()\fR
regardless if \f(CW\*(C`check_interval\*(C'\fR has expired or not, call
.PP
.Vb 1
\&    $watcher\->force_next_check();
.Ve
.PP
on the watcher object.
.SS "DETECT MOVED FILES"
.IX Subsection "DETECT MOVED FILES"
The watcher can also be used to detect files that have moved. It will 
not only detect if a watched file has disappeared, but also if it has
been replaced by a new file in the meantime.
.PP
.Vb 4
\&    my $watcher = Log::Log4perl::Config::Watch\->new(
\&        file           => "/data/my.conf",
\&        check_interval => 30,
\&    );
\&
\&    while(1) {
\&        if($watcher\->file_has_moved()) {
\&            print "File has moved!\en";
\&        }
\&        sleep(1);
\&    }
.Ve
.PP
The parameters \f(CW\*(C`check_interval\*(C'\fR and \f(CW\*(C`signal\*(C'\fR limit the number of physical 
file system checks, similarily as with \f(CWchange_detected()\fR.
.SH LICENSE
.IX Header "LICENSE"
Copyright 2002\-2026 by Mike Schilli <m@perlmeister.com>
and Kevin Goess <cpan@goess.org>.
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.