1Log::Handler::Output::FUisleer(3C)ontributed Perl DocumeLnotga:t:iHoanndler::Output::File(3)
2
6 Log::Handler::Output::File - Log messages to a file.
7
9 use Log::Handler::Output::File;
10 my $log = Log::Handler::Output::File->new(
12 filename => "file.log",
13 filelock => 1,
14 fileopen => 1,
15 reopen => 1,
16 mode => "append",
17 autoflush => 1,
18 permissions => "0664",
19 utf8 => 0,
20 );
21 $log->log(message => $message);
23
25 Log messages to a file.
26
28 new()
29 Call new() to create a new Log::Handler::Output::File object.
30 The following options are possible:
32 filename
34 With "filename" you can set a file name as a string or as a array
35 reference. If you set a array reference then the parts will be
36 concat with "catfile" from "File::Spec".
37 Set a file name:
39 my $log = Log::Handler::Output::File->new( filename => "file.log" );
41 Set a array reference:
43 my $log = Log::Handler::Output::File->new(
45 # foo/bar/baz.log
47 filename => [ "foo", "bar", "baz.log" ],
48 # /foo/bar/baz.log
50 filename => [ "", "foo", "bar", "baz.log" ],
51 );
53 filelock
55 Maybe it's desirable to lock the log file by each write operation
56 because a lot of processes write at the same time to the log file.
57 You can set the option "filelock" to 0 or 1.
58 0 - no file lock
60 1 - exclusive lock (LOCK_EX) and unlock (LOCK_UN) by each write operation (default)
61 fileopen
63 Open a log file transient or permanent.
64 0 - open and close the logfile by each write operation
66 1 - open the logfile if C<new()> called and try to reopen the
67 file if C<reopen> is set to 1 and the inode of the file has changed (default)
68 reopen
70 This option works only if option "fileopen" is set to 1.
71 0 - deactivated
73 1 - try to reopen the log file if the inode changed (default)
74 How to use fileopen and reopen
76 Please note that it's better to set "reopen" and "fileopen" to 0 on
77 Windows because Windows unfortunately haven't the faintest idea of
78 inodes.
79 To write your code independent you should control it:
81 my $os_is_win = $^O =~ /win/i ? 0 : 1;
83 my $log = Log::Handler::Output::File->new(
85 filename => "file.log",
86 mode => "append",
87 fileopen => $os_is_win
88 );
89 If you set "fileopen" to 0 then it implies that "reopen" has no
91 importance.
92 mode
94 There are three possible modes to open a log file.
95 append - O_WRONLY | O_APPEND | O_CREAT (default)
97 excl - O_WRONLY | O_EXCL | O_CREAT
98 trunc - O_WRONLY | O_TRUNC | O_CREAT
99 "append" would open the log file in any case and appends the
101 messages at the end of the log file.
102 "excl" would fail by open the log file if the log file already
104 exists.
105 "trunc" would truncate the complete log file if it exists. Please
107 take care to use this option.
108 Take a look to the documentation of sysopen() to get more
110 information.
111 autoflush
113 0 - autoflush off
114 1 - autoflush on (default)
115 permissions
117 The option "permissions" sets the permission of the file if it
118 creates and must be set as a octal value. The permission need to be
119 in octal and are modified by your process's current "umask".
120 That means that you have to use the unix style permissions such as
122 "chmod". 0640 is the default permission for this option. That
123 means that the owner got read and write permissions and users in
124 the same group got only read permissions. All other users got no
125 access.
126 Take a look to the documentation of sysopen() to get more
128 information.
129 utf8, utf-8
131 utf8 = binmode, $fh, ":utf8";
132 utf-8 = binmode, $fh, "encoding(utf-8)";
133 Yes, there is a difference.
135 <http://perldoc.perl.org/perldiag.html#Malformed-UTF-8-character-(%25s)>
137 <http://perldoc.perl.org/Encode.html#UTF-8-vs.-utf8-vs.-UTF8>
139 dateext
141 It's possible to set a pattern in the filename that is replaced
142 with a date. If the date - and the filename - changed the file is
143 closed and reopened with the new filename. The filename is
144 converted with "POSIX::strftime".
145 Example:
147 my $log = Log::Handler::Output::File->new(
149 filename => "file-%Y-%m-%d.log",
150 dateext => 1
151 );
152 In this example the file "file-2015-06-12.log" is created. At the
154 next day the filename changed, the log file "file-2015-06-12.log"
155 is closed and "file-2015-06-13.log" is opened.
156 This feature is a small improvement for systems where no logrotate
158 is available like Windows systems. On this way you have the chance
159 to delete old log files without to stop/start a daemon.
160 log()
162 Call log() if you want to log messages to the log file.
163 Example:
165 $log->log(message => "this message goes to the logfile");
167 flush()
169 Call flush() if you want to re-open the log file.
170 This is useful if you don't want to use option "reopen". As example if
172 a rotate mechanism moves the logfile and you want to re-open a new one.
173 validate()
175 Validate a configuration.
176 reload()
178 Reload with a new configuration.
179 errstr()
181 Call errstr() to get the last error message.
182 close()
184 Call close() to close the log file yourself - normally you don't need
185 to use it, because the log file will be opened and closed
186 automatically.
187
189 Carp
190 Fcntl
191 File::Spec
192 Params::Validate
193
195 No exports.
196
198 Please report all bugs to <jschulz.cpan(at)bloonix.de>.
199 If you send me a mail then add Log::Handler into the subject.
201
203 Jonny Schulz <jschulz.cpan(at)bloonix.de>.
204
206 Copyright (C) 2007-2009 by Jonny Schulz. All rights reserved.
207 This program is free software; you can redistribute it and/or modify it
209 under the same terms as Perl itself.
210perl v5.36.0 2023-01-20 Log::Handler::Output::File(3)