--- name: "Log::Report::Dispatcher::File" section: "3pm" platform: "linux" package: "perl-log-report" version: "1.46-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/Log::Report::Dispatcher::File" --- # Log::Report::Dispatcher::File(3pm) send messages to a file or file-handle ## NAME Log::Report::Dispatcher::File - send messages to a file or file-handle ## INHERITANCE ``` Log::Report::Dispatcher::File is a Log::Report::Dispatcher ``` ## SYNOPSIS ``` dispatcher Log::Report::Dispatcher::File => 'stderr', to => \*STDERR, accept => 'NOTICE-'; # close a dispatcher dispatcher close => 'stderr'; # let dispatcher open and close the file dispatcher FILE => 'mylog', to => '/var/log/mylog', charset => 'utf-8'; ... dispatcher close => 'mylog'; # will close file # open yourself, then also close yourself open OUT, ">:encoding('iso-8859-1')", '/var/log/mylog' or fault "..."; dispatcher FILE => 'mylog', to => \*OUT; ... dispatcher close => 'mylog'; close OUT; # dispatch into a scalar my $output = ''; open $outfile, '>', \$output; dispatcher FILE => 'into-scalar', to => \$outfile; ... dispatcher close => 'into-scalar'; print $output; ``` ## DESCRIPTION This basic file logger accepts an file-handle or filename as destination. \[1.00\] writing to the file protected by a lock, so multiple processes can write to the same file. Extends "DESCRIPTION" in Log::Report::Dispatcher. ## METHODS Extends "METHODS" in Log::Report::Dispatcher. ### Constructors Extends "Constructors" in Log::Report::Dispatcher. - $class-\>**new**($type, $name, %options) Inherited, see "Constructors" in Log::Report::Dispatcher ``` -Option --Defined in --Default accept Log::Report::Dispatcher depend on mode charset Log::Report::Dispatcher LC_CTYPE format format_reason Log::Report::Dispatcher 'LOWERCASE' locale Log::Report::Dispatcher mode Log::Report::Dispatcher 'NORMAL' replace false to ``` - accept =\> $reasons\|\\@reasons - charset =\> CHARSET - format =\> CODE\|'LONG' \[1.00\] process each printed line. By default, this adds a timestamp, but you may want to add hostname, process number, or more. ``` format => sub { '['.localtime().'] '.$_[0] } format => sub { shift } # no timestamp format => 'LONG' ``` The first parameter to format is the string to print; it is already translated and trailed by a newline. The second parameter is the text-domain (if known). \[1.10\] As third parameter, you get the message raw object as well (maybe you want to use the message context?) \[1.19\] After the three positional parameters, there may be a list of pairs providing additional facts about the exception. It may contain `"location"` information. The "LONG" format is equivalent to: ``` my $t = strftime "%FT%T", gmtime; "[$t $$] $_[1] $_[0]" ``` Use of context: ``` format => sub { my ($msgstr, $domain, $msg, %more) = @_; my $host = $msg->context->{host}; "$host $msgstr"; } ``` - format\_reason =\> 'UPPERCASE'\|'LOWERCASE'\|'UCFIRST'\|'IGNORE'\|CODE - locale =\> LOCALE - mode =\> 'NORMAL'\|'VERBOSE'\|'ASSERT'\|'DEBUG'\|0..3 - replace =\> BOOLEAN Only used in combination with a `"to"` filename: throw away the old file if it exists. Probably you wish to append to existing information. Use the locale setting by default, which is LC\_CTYPE or LC\_ALL or LANG (in that order). If these contain a character-set which Perl understands, then that is used, otherwise silently ignored. - to =\> $file\|$fh\|OBJECT\|CODE You can either specify a `$file` by name, which is opened in append mode with autoflush on. Or pass any kind of file handle `$fh`, or some OBJECT which implements a `print()` method. You probably want to have autoflush enabled on your file-handles. When cleaning-up the dispatcher, the file will only be closed in case of a named `$file`. \[1.10\] When you pass a CODE, then for each log message the function is called with two arguments: this dispatcher object and the message object. In some way (maybe via the message context) you have to determine the log filename. This means that probably many log-files are open at the same time. ``` # configuration time dispatcher FILE => 'logfile', to => sub { my ($disp, $msg) = @_; $msg->context->{logfile} }; # whenever you want to change the logfile textdomain->updateContext(logfile => '/var/log/app'); (textdomain 'mydomain')->setContext(logfile => '/var/log/app'); # or error __x"help", _context => {logfile => '/dev/tty'}; error __x"help", _context => "logfile=/dev/tty"; ``` ### Attributes Extends "Attributes" in Log::Report::Dispatcher. - $obj-\>**filename**() Returns the name of the opened file, or `"undef"` in case this dispatcher was started from a file-handle or file-object. - $obj-\>**format**() - $obj-\>**isDisabled**() Inherited, see "Attributes" in Log::Report::Dispatcher - $obj-\>**mode**() Inherited, see "Attributes" in Log::Report::Dispatcher - $obj-\>**name**() Inherited, see "Attributes" in Log::Report::Dispatcher - $obj-\>**needs**( \[$reason\] ) Inherited, see "Attributes" in Log::Report::Dispatcher - $obj-\>**output**($msg) Returns the file-handle to write the log lines to. \[1.10\] This may depend on the `$msg` (especially message context) - $obj-\>**type**() Inherited, see "Attributes" in Log::Report::Dispatcher ### File maintenance - $obj-\>**rotate**($filename\|CODE) \[1.00\] Move the current file to `$filename`, and start a new file. ### Logging Extends "Logging" in Log::Report::Dispatcher. - $any-\>**addSkipStack**(@CODE) Inherited, see "Logging" in Log::Report::Dispatcher - $obj-\>**close**() Only when initiated with a FILENAME, the file will be closed. In any other case, nothing will be done. Improves base, see "Logging" in Log::Report::Dispatcher - $any-\>**collectLocation**() Inherited, see "Logging" in Log::Report::Dispatcher - $any-\>**collectStack**( \[$maxdepth\] ) Inherited, see "Logging" in Log::Report::Dispatcher - $obj-\>**log**(\\%options, $reason, $message, $domain) Inherited, see "Logging" in Log::Report::Dispatcher - $obj-\>**skipStack**() Inherited, see "Logging" in Log::Report::Dispatcher - $any-\>**stackTraceLine**(%options) Inherited, see "Logging" in Log::Report::Dispatcher - $obj-\>**translate**(\\%options, $reason, $message) Inherited, see "Logging" in Log::Report::Dispatcher ## DETAILS Extends "DETAILS" in Log::Report::Dispatcher. ## DIAGNOSTICS - Error: cannot rotate log file which was opened as file-handle Cast by `rotate()` - Fault: cannot write log into $file: $! Cast by `rotate()` - Error: dispatcher $name needs parameter 'to' Cast by `new()` - Fault: unable to rotate logfile $fn to $oldfn: $! Cast by `rotate()` - Error: unknown format parameter \`$what' Cast by `new()` ## SEE ALSO This module is part of Log-Report version 1.46, built on June 16, 2026. Website: *http://perl.overmeer.net/CPAN/* ## LICENSE For contributors see file ChangeLog. This software is copyright (c) 2007-2026 by Mark Overmeer. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.