Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Log::Report::DispatcheUseriContributed Perl DoLog::Report::Dispatcher::File(3)

       Log::Report::Dispatcher::File - send messages to	a file or file-handle

	  is a Log::Report::Dispatcher

	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;

       This basic file logger accepts an file-handle or	filename as

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

       Extends "METHODS" in Log::Report::Dispatcher.

       Extends "Constructors" in Log::Report::Dispatcher.

	   Only	when initiated with a FILENAME,	the file will be closed.  In
	   any other case, nothing will	be done.

       Log::Report::Dispatcher::File->new($type, $name,	%options)
	    -Option	  --Defined in		   --Default
	     accept	    Log::Report::Dispatcher  depend on mode
	     charset	    Log::Report::Dispatcher  LOCALE
	     format				     <adds timestamp>
	     format_reason  Log::Report::Dispatcher  'LOWERCASE'
	     locale	    Log::Report::Dispatcher  <system locale>
	     mode	    Log::Report::Dispatcher  'NORMAL'
	     replace				     false
	     to					     <required>

	   accept => 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

		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 $msg 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";

	   locale => LOCALE
	   mode	=> 'NORMAL'|'VERBOSE'|'ASSERT'|'DEBUG'|0..3
	   replace => BOOLEAN
	     Only used in combination with a FILENAME: throw away the old file
	     if	it exists.  Probably you wish to append	to existing

	     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.

	     You can either specify a FILENAME,	which is opened	in append mode
	     with autoflush on.	Or pass	any kind of FILE-HANDLE	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 FILENAME.

	     [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";

       Extends "Accessors" in Log::Report::Dispatcher.

	   Returns the name of the opened file,	or "undef" in case this
	   dispatcher was started from a file-handle or	file-object.

	   Inherited, see "Accessors" in Log::Report::Dispatcher

	   Inherited, see "Accessors" in Log::Report::Dispatcher

	   Inherited, see "Accessors" in Log::Report::Dispatcher

       $obj->needs( [$reason] )
	   Inherited, see "Accessors" in Log::Report::Dispatcher

	   Returns the file-handle to write the	log lines to. [1.10] This may
	   depend on the $msg (especially message context)

	   Inherited, see "Accessors" in Log::Report::Dispatcher

   File	maintenance
	   [1.00] Move the current file	to $filename, and start	a new file.

       Extends "Logging" in Log::Report::Dispatcher.

	   Inherited, see "Logging" in Log::Report::Dispatcher

	   Inherited, see "Logging" in Log::Report::Dispatcher

       $obj->collectStack( [$maxdepth] )
       Log::Report::Dispatcher::File->collectStack( [$maxdepth]	)
	   Inherited, see "Logging" in Log::Report::Dispatcher

       $obj->log(HASH-$of-%options, $reason, $message, $domain)
	   Inherited, see "Logging" in Log::Report::Dispatcher

	   Inherited, see "Logging" in Log::Report::Dispatcher

	   Inherited, see "Logging" in Log::Report::Dispatcher

       $obj->translate(HASH-$of-%options, $reason, $message)
	   Inherited, see "Logging" in Log::Report::Dispatcher

       Extends "DETAILS" in Log::Report::Dispatcher.

       This module is part of Log-Report distribution version 1.33, built on
       July 17,	2021. Website:

       Copyrights 2007-2021 by [Mark Overmeer <>]. For other
       contributors see	ChangeLog.

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

perl v5.32.1			  2021-07-17  Log::Report::Dispatcher::File(3)


Want to link to this manual page? Use this URL:

home | help