---
name: "Log::Log4perl::Config::Watch"
section: "3pm"
platform: "linux"
package: "perl-log-log4perl"
version: "1.58-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/Log::Log4perl::Config::Watch"
---

# Log::Log4perl::Config::Watch(3pm)

Detect file changes

## NAME

Log::Log4perl::Config::Watch - Detect file changes

## SYNOPSIS

```
    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!\n";
        }
        sleep(1);
    }
```

## DESCRIPTION

This module helps detecting changes in files. Although it comes with the `"Log::Log4perl"` distribution, it can be used independently.

The constructor defines the file to be watched and the check interval  in seconds. Subsequent calls to `change_detected()` will

- •

  return a false value immediately without doing physical file checks if `"check_interval"` hasn't elapsed.

- •

  perform a physical test on the specified file if the number of seconds specified in `"check_interval"`  have elapsed since the last physical check. If the file's modification date has changed since the last physical check, it will return a true  value, otherwise a false value is returned.

Bottom line: `"check_interval"` allows you to call the function `change_detected()` 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 `"check_interval"` seconds have elapsed).

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's clock, it'll just work fine.

To disable the resource-saving delay feature, just set `"check_interval"`  to 0 and `change_detected()` will run a physical file test on every call.

If you already have the current time available, you can pass it on to `change_detected()` as an optional parameter, like in

```
    change_detected($time)
```

which then won't trigger a call to `time()`, but use the value provided.

### SIGNAL MODE

Instead of polling time and file changes, `new()` can be instructed  to set up a signal handler. If you call the constructor like

```
    my $watcher = Log::Log4perl::Config::Watch->new(
                          file    => "/data/my.conf",
                          signal  => 'HUP'
                  );
```

then a signal handler will be installed, setting the object's variable  `"$self->{signal_caught}"` to a true value when the signal arrives. Comes with all the problems that signal handlers go along with.

### TRIGGER CHECKS

To trigger a physical file check on the next call to `change_detected()` regardless if `"check_interval"` has expired or not, call

```
    $watcher->force_next_check();
```

on the watcher object.

### 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.

```
    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!\n";
        }
        sleep(1);
    }
```

The parameters `"check_interval"` and `"signal"` limit the number of physical  file system checks, similarily as with `change_detected()`.

## LICENSE

Copyright 2002-2026 by Mike Schilli \<m@perlmeister.com\> and Kevin Goess \<cpan@goess.org\>.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.