1Log::Handler::Output::FUisleer(3C)ontributed Perl DocumeLnotga:t:iHoanndler::Output::File(3)
2
3
4

NAME

6       Log::Handler::Output::File - Log messages to a file.
7

SYNOPSIS

9           use Log::Handler::Output::File;
10
11           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
22           $log->log(message => $message);
23

DESCRIPTION

25       Log messages to a file.
26

METHODS

28   new()
29       Call "new()" to create a new Log::Handler::Output::File object.
30
31       The following options are possible:
32
33       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
38           Set a file name:
39
40               my $log = Log::Handler::Output::File->new( filename => "file.log"  );
41
42           Set a array reference:
43
44               my $log = Log::Handler::Output::File->new(
45
46                   # foo/bar/baz.log
47                   filename => [ "foo", "bar", "baz.log" ],
48
49                   # /foo/bar/baz.log
50                   filename => [ "", "foo", "bar", "baz.log" ],
51
52               );
53
54       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
59               0 - no file lock
60               1 - exclusive lock (LOCK_EX) and unlock (LOCK_UN) by each write operation (default)
61
62       fileopen
63           Open a log file transient or permanent.
64
65               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
69       reopen
70           This option works only if option "fileopen" is set to 1.
71
72               0 - deactivated
73               1 - try to reopen the log file if the inode changed (default)
74
75       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
80           To write your code independent you should control it:
81
82               my $os_is_win = $^O =~ /win/i ? 0 : 1;
83
84               my $log = Log::Handler::Output::File->new(
85                  filename => "file.log",
86                  mode     => "append",
87                  fileopen => $os_is_win
88               );
89
90           If you set "fileopen" to 0 then it implies that "reopen" has no
91           importance.
92
93       mode
94           There are three possible modes to open a log file.
95
96               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
100           "append" would open the log file in any case and appends the
101           messages at the end of the log file.
102
103           "excl" would fail by open the log file if the log file already
104           exists.
105
106           "trunc" would truncate the complete log file if it exists. Please
107           take care to use this option.
108
109           Take a look to the documentation of "sysopen()" to get more
110           information.
111
112       autoflush
113               0 - autoflush off
114               1 - autoflush on (default)
115
116       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
121           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
127           Take a look to the documentation of "sysopen()" to get more
128           information.
129
130       utf8, utf-8
131               utf8   =  binmode, $fh, ":utf8";
132               utf-8  =  binmode, $fh, "encoding(utf-8)";
133
134           Yes, there is a difference.
135
136           <http://perldoc.perl.org/perldiag.html#Malformed-UTF-8-character-(%25s)>
137
138           <http://perldoc.perl.org/Encode.html#UTF-8-vs.-utf8-vs.-UTF8>
139
140       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
146           Example:
147
148               my $log = Log::Handler::Output::File->new(
149                   filename  => "file-%Y-%m-%d.log",
150                   dateext => 1
151               );
152
153           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
157           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
161   log()
162       Call "log()" if you want to log messages to the log file.
163
164       Example:
165
166           $log->log(message => "this message goes to the logfile");
167
168   flush()
169       Call "flush()" if you want to re-open the log file.
170
171       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
174   validate()
175       Validate a configuration.
176
177   reload()
178       Reload with a new configuration.
179
180   errstr()
181       Call "errstr()" to get the last error message.
182
183   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

PREREQUISITES

189           Carp
190           Fcntl
191           File::Spec
192           Params::Validate
193

EXPORTS

195       No exports.
196

REPORT BUGS

198       Please report all bugs to <jschulz.cpan(at)bloonix.de>.
199
200       If you send me a mail then add Log::Handler into the subject.
201

AUTHOR

203       Jonny Schulz <jschulz.cpan(at)bloonix.de>.
204
206       Copyright (C) 2007-2009 by Jonny Schulz. All rights reserved.
207
208       This program is free software; you can redistribute it and/or modify it
209       under the same terms as Perl itself.
210
211
212
213perl v5.34.0                      2021-07-22     Log::Handler::Output::File(3)
Impressum