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

FreeBSD Manual Pages

  
 
  

home | help
Log::Handler::Output::User(Contributed Perl DocumLog::Handler::Output::File(3)

NAME
       Log::Handler::Output::File - Log	messages to a file.

SYNOPSIS
	   use Log::Handler::Output::File;

	   my $log = Log::Handler::Output::File->new(
	       filename	   => "file.log",
	       filelock	   => 1,
	       fileopen	   => 1,
	       reopen	   => 1,
	       mode	   => "append",
	       autoflush   => 1,
	       permissions => "0664",
	       utf8	   => 0,
	   );

	   $log->log(message =>	$message);

DESCRIPTION
       Log messages to a file.

METHODS
   new()
       Call "new()" to create a	new Log::Handler::Output::File object.

       The following options are possible:

       filename
	   With	"filename" you can set a file name as a	string or as a array
	   reference.  If you set a array reference then the parts will	be
	   concat with "catfile" from "File::Spec".

	   Set a file name:

	       my $log = Log::Handler::Output::File->new( filename => "file.log"  );

	   Set a array reference:

	       my $log = Log::Handler::Output::File->new(

		   # foo/bar/baz.log
		   filename => [ "foo",	"bar", "baz.log" ],

		   # /foo/bar/baz.log
		   filename => [ "", "foo", "bar", "baz.log" ],

	       );

       filelock
	   Maybe it's desirable	to lock	the log	file by	each write operation
	   because a lot of processes write at the same	time to	the log	file.
	   You can set the option "filelock" to	0 or 1.

	       0 - no file lock
	       1 - exclusive lock (LOCK_EX) and	unlock (LOCK_UN) by each write operation (default)

       fileopen
	   Open	a log file transient or	permanent.

	       0 - open	and close the logfile by each write operation
	       1 - open	the logfile if C<new()>	called and try to reopen the
		   file	if C<reopen> is	set to 1 and the inode of the file has changed (default)

       reopen
	   This	option works only if option "fileopen" is set to 1.

	       0 - deactivated
	       1 - try to reopen the log file if the inode changed (default)

       How to use fileopen and reopen
	   Please note that it's better	to set "reopen"	and "fileopen" to 0 on
	   Windows because Windows unfortunately haven't the faintest idea of
	   inodes.

	   To write your code independent you should control it:

	       my $os_is_win = $^O =~ /win/i ? 0 : 1;

	       my $log = Log::Handler::Output::File->new(
		  filename => "file.log",
		  mode	   => "append",
		  fileopen => $os_is_win
	       );

	   If you set "fileopen" to 0 then it implies that "reopen" has	no
	   importance.

       mode
	   There are three possible modes to open a log	file.

	       append -	O_WRONLY | O_APPEND | O_CREAT (default)
	       excl   -	O_WRONLY | O_EXCL   | O_CREAT
	       trunc  -	O_WRONLY | O_TRUNC  | O_CREAT

	   "append" would open the log file in any case	and appends the
	   messages at the end of the log file.

	   "excl" would	fail by	open the log file if the log file already
	   exists.

	   "trunc" would truncate the complete log file	if it exists. Please
	   take	care to	use this option.

	   Take	a look to the documentation of "sysopen()" to get more
	   information.

       autoflush
	       0 - autoflush off
	       1 - autoflush on	(default)

       permissions
	   The option "permissions" sets the permission	of the file if it
	   creates and must be set as a	octal value. The permission need to be
	   in octal and	are modified by	your process's current "umask".

	   That	means that you have to use the unix style permissions such as
	   "chmod".  0640 is the default permission for	this option. That
	   means that the owner	got read and write permissions and users in
	   the same group got only read	permissions. All other users got no
	   access.

	   Take	a look to the documentation of "sysopen()" to get more
	   information.

       utf8, utf-8
	       utf8   =	 binmode, $fh, ":utf8";
	       utf-8  =	 binmode, $fh, "encoding(utf-8)";

	   Yes,	there is a difference.

	   <http://perldoc.perl.org/perldiag.html#Malformed-UTF-8-character-(%25s)>

	   <http://perldoc.perl.org/Encode.html#UTF-8-vs.-utf8-vs.-UTF8>

       dateext
	   It's	possible to set	a pattern in the filename that is replaced
	   with	a date.	 If the	date - and the filename	- changed the file is
	   closed and reopened with the	new filename. The filename is
	   converted with "POSIX::strftime".

	   Example:

	       my $log = Log::Handler::Output::File->new(
		   filename  =>	"file-%Y-%m-%d.log",
		   dateext => 1
	       );

	   In this example the file "file-2015-06-12.log" is created. At the
	   next	day the	filename changed, the log file "file-2015-06-12.log"
	   is closed and "file-2015-06-13.log" is opened.

	   This	feature	is a small improvement for systems where no logrotate
	   is available	like Windows systems. On this way you have the chance
	   to delete old log files without to stop/start a daemon.

   log()
       Call "log()" if you want	to log messages	to the log file.

       Example:

	   $log->log(message =>	"this message goes to the logfile");

   flush()
       Call "flush()" if you want to re-open the log file.

       This is useful if you don't want	to use option "reopen".	As example if
       a rotate	mechanism moves	the logfile and	you want to re-open a new one.

   validate()
       Validate	a configuration.

   reload()
       Reload with a new configuration.

   errstr()
       Call "errstr()" to get the last error message.

   close()
       Call "close()" to close the log file yourself - normally	you don't need
       to use it, because the log file will be opened and closed
       automatically.

PREREQUISITES
	   Carp
	   Fcntl
	   File::Spec
	   Params::Validate

EXPORTS
       No exports.

REPORT BUGS
       Please report all bugs to <jschulz.cpan(at)bloonix.de>.

       If you send me a	mail then add Log::Handler into	the subject.

AUTHOR
       Jonny Schulz <jschulz.cpan(at)bloonix.de>.

COPYRIGHT
       Copyright (C) 2007-2009 by Jonny	Schulz.	All rights reserved.

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

perl v5.24.1			  2015-06-12	 Log::Handler::Output::File(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | PREREQUISITES | EXPORTS | REPORT BUGS | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Log::Handler::Output::File&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help