---
name: "Badger::Log::File"
section: "3pm"
platform: "linux"
package: "libbadger-perl"
version: "0.16-3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Badger::Log::File"
---

# Badger::Log::File(3pm)

writes log messages to a log file

## NAME

Badger::Log::File - writes log messages to a log file

## SYNOPSIS

```
    use Badger::Log::File;
    my $log = Badger::Log::File->new({
        filename  => '/var/log/badger.log',
        keep_open => 1,
    });
    $log->log('a debug message');
    $log->info('an info message');
    $log->warn('a warning message');
    $log->error('an error message');
    $log->fatal('a fatal error message');
```

## DESCRIPTION

This module is a subclass of Badger::Log that implements a simple mechanism for logging messages to a file.  It uses Badger::Filesystem for all the underlying file operations.

## CONFIGURATION OPTIONS

The following configuration options are available in addition to those inherited form the Badger::Log base class.

### filename

The name of the log file which you want messages appended to.  Either this or the filename\_format option must be provided.

### filename\_format

A format which can be used to generate a filename to write messages to. This can include any of the `"strftime()"` character sequences, e.g. `%Y` for the four digit year, `%m` for a two digit month number, `%d` for a two digit day of the month, etc.

```
    my $log = Badger::Log::File->new({
        filename_format  => '/var/log/badger-%Y-%m-%d.log',
        keep_open => 1,
    });
```

If, like me, you find it hard to remember the `"strftime()"` character sequences, then you can use an alternate format where the elements of the date and/or time are encoded as upper case words embedded in angle brackets. e.g. `"badger-<DATE>.log"`, or `"badger-<YEAR>-<MONTH>.log"`.

The words that can be embedded this way, and their corresponding `"strftime()"` character sequences are:

```
    DATE    => '%Y-%m-%d'       # e.g. 2022-08-24
    TIME    => '%H-%M-%S'       # e.g. 13:54:07
    YEAR    => '%Y'             # e.g. 2022
    MONTH   => '%m'             # e.g. 08
    DAY     => '%d'             # e.g. 24
    HOURS   => '%H'             # e.g. 13
    MINUTES => '%M'             # e.g. 54
    SECONDS => '%S'             # e.g. 07
```

The module will automatically create a new logfile when the `"filename_format"` generates a filename that is different to any previous value.

### filesystem

An optional reference to a Badger::Filesystem object, or the name of a filesystem class having a **file()** method similar to that in Badger::Filesystem. This defaults to the Badger::Filesystem class.

### keep\_open

A flag indicating if the log file should be kept open between calls to logging methods.  The default value is `0` meaning that the file will be opened for each message and closed again afterwards.  Set it to any true value to have the file kept open.

## METHODS

The following methods are implemented in addition to those inherited from Badger::Log and its base classes.

### log($level,$message)

This method redefines the **log()** method in Badger::Log to write logging messages to the log file.

### INTERNAL METHODS

### init(\\%config)

Custom initialiser method which calls the base class **init\_log()** method followed by the **init\_file()** method.

### init\_file(\\%config)

Custom initialiser method which handles the configuration and initialisation of the file-specific parts of the logger.

### expand\_filename()

Expands the format defined by the `"filename_format"` configuration option to a filename using the current date and time.

If `"filename_format"` has not been specified then it returns the value of the `"filename"` configuration option.

### filename\_changed()

Calls **expand\_filename()** to expand any `"filename_format"` and compares it to the current `"filename"` (which may have been generated by a previous call to this method).

If they are the same then it returns `"undef"`.  Otherwise it saves the new filename to the internal `"filename"` value and returns it.

### file()

Returns a reference to a Badger::Filesystem::File object based on the `"filename"` which can either be defined as a static configuration option or will be generated by the **expand\_filename()** method from the `"filename_format"` configuration option.

### filehandle()

Returns a filehandle for the current logfile.  If the filename has changed since the last call this method (determined by calling **filename\_changed()**) then any existing filehandle is closed (by calling **release()**) and the new file is opened to return a new filehandle (by calling **acquire()**).

### acquire()

This method acquires a file handle (an IO::File object) for the specified filename, opened ready for appending log messages.

### release()

The method releases a previously acquired file handle.  i.e. it closes the log file.

## AUTHOR

Andy Wardley \<http://wardley.org/\>

## COPYRIGHT

Copyright (C) 2005-2022 Andy Wardley.  All Rights Reserved.

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

## SEE ALSO

Badger::Log