1Appender::File(3) User Contributed Perl Documentation Appender::File(3)
2
6 Log::Log4perl::Appender::File - Log to file
7
9 use Log::Log4perl::Appender::File;
10 my $app = Log::Log4perl::Appender::File->new(
12 filename => 'file.log',
13 mode => 'append',
14 autoflush => 1,
15 umask => 0222,
16 );
17 $file->log(message => "Log me\n");
19
21 This is a simple appender for writing to a file.
22 The log() method takes a single scalar. If a newline character should
24 terminate the message, it has to be added explicitly.
25 Upon destruction of the object, the filehandle to access the file is
27 flushed and closed.
28 If you want to switch over to a different logfile, use the
30 file_switch($newfile) method which will first close the old file handle
31 and then open a one to the new file specified.
32 OPTIONS
34 filename
35 Name of the log file.
36 mode
38 Messages will be append to the file if $mode is set to the string
39 "append". Will clobber the file if set to "clobber". If it is
40 "pipe", the file will be understood as executable to pipe output
41 to. Default mode is "append".
42 autoflush
44 "autoflush", if set to a true value, triggers flushing the data out
45 to the file on every call to log(). "autoflush" is on by default.
46 syswrite
48 "syswrite", if set to a true value, makes sure that the appender
49 uses syswrite() instead of print() to log the message. syswrite()
50 usually maps to the operating system's write() function and makes
51 sure that no other process writes to the same log file while
52 write() is busy. Might safe you from having to use other
53 synchronisation measures like semaphores (see: Synchronized
54 appender).
55 umask
57 Specifies the "umask" to use when creating the file, determining
58 the file's permission settings. If set to 0022 (default), new
59 files will be created with "rw-r--r--" permissions. If set to
60 0000, new files will be created with "rw-rw-rw-" permissions.
61 owner
63 If set, specifies that the owner of the newly created log file
64 should be different from the effective user id of the running
65 process. Only makes sense if the process is running as root. Both
66 numerical user ids and user names are acceptable. Log4perl does
67 not attempt to change the ownership of existing files.
68 group
70 If set, specifies that the group of the newly created log file
71 should be different from the effective group id of the running
72 process. Only makes sense if the process is running as root. Both
73 numerical group ids and group names are acceptable. Log4perl does
74 not attempt to change the group membership of existing files.
75 utf8
77 If you're printing out Unicode strings, the output filehandle needs
78 to be set into ":utf8" mode:
79 my $app = Log::Log4perl::Appender::File->new(
81 filename => 'file.log',
82 mode => 'append',
83 utf8 => 1,
84 );
85 binmode
87 To manipulate the output filehandle via binmode(), use the binmode
88 parameter:
89 my $app = Log::Log4perl::Appender::File->new(
91 filename => 'file.log',
92 mode => 'append',
93 binmode => ":utf8",
94 );
95 A setting of ":utf8" for "binmode" is equivalent to specifying the
97 "utf8" option (see above).
98 recreate
100 Normally, if a file appender logs to a file and the file gets moved
101 to a different location (e.g. via "mv"), the appender's open file
102 handle will automatically follow the file to the new location.
103 This may be undesirable. When using an external logfile rotator,
105 for example, the appender should create a new file under the old
106 name and start logging into it. If the "recreate" option is set to
107 a true value, "Log::Log4perl::Appender::File" will do exactly that.
108 It defaults to false. Check the "recreate_check_interval" option
109 for performance optimizations with this feature.
110 recreate_check_interval
112 In "recreate" mode, the appender has to continuously check if the
113 file it is logging to is still in the same location. This check is
114 fairly expensive, since it has to call "stat" on the file name and
115 figure out if its inode has changed. Doing this with every call to
116 "log" can be prohibitively expensive. Setting it to a positive
117 integer value N will only check the file every N seconds. It
118 defaults to 30.
119 This obviously means that the appender will continue writing to a
121 moved file until the next check occurs, in the worst case this will
122 happen "recreate_check_interval" seconds after the file has been
123 moved or deleted. If this is undesirable, setting
124 "recreate_check_interval" to 0 will have the appender check the
125 file with every call to log().
126 recreate_check_signal
128 In "recreate" mode, if this option is set to a signal name (e.g.
129 "USR1"), the appender will recreate a missing logfile when it
130 receives the signal. It uses less resources than constant polling.
131 The usual limitation with perl's signal handling apply. Check the
132 FAQ for using this option with the log rotating utility
133 "newsyslog".
134 recreate_pid_write
136 The popular log rotating utility "newsyslog" expects a pid file in
137 order to send the application a signal when its logs have been
138 rotated. This option expects a path to a file where the pid of the
139 currently running application gets written to. Check the FAQ for
140 using this option with the log rotating utility "newsyslog".
141 create_at_logtime
143 The file appender typically creates its logfile in its constructor,
144 i.e. at Log4perl init() time. This is desirable for most use
145 cases, because it makes sure that file permission problems get
146 detected right away, and not after days/weeks/months of operation
147 when the appender suddenly needs to log something and fails because
148 of a problem that was obvious at startup.
149 However, there are rare use cases where the file shouldn't be
151 created at Log4perl init() time, e.g. if the appender can't be used
152 by the current user although it is defined in the configuration
153 file. If you set "create_at_logtime" to a true value, the file
154 appender will try to create the file at log time. Note that this
155 setting lets permission problems sit undetected until log time,
156 which might be undesirable.
157 header_text
159 If you want Log4perl to print a header into every newly opened (or
160 re-opened) logfile, set "header_text" to either a string or a
161 subroutine returning a string. If the message doesn't have a
162 newline, a newline at the end of the header will be provided.
163 mkpath
165 If this this option is set to true, the directory path will be
166 created if it does not exist yet.
167 mkpath_umask
169 Specifies the "umask" to use when creating the directory,
170 determining the directory's permission settings. If set to 0022
171 (default), new directory will be created with "rwxr-xr-x"
172 permissions. If set to 0000, new directory will be created with
173 "rwxrwxrwx" permissions.
174 Design and implementation of this module has been greatly inspired by
176 Dave Rolsky's "Log::Dispatch" appender framework.
177
179 Copyright 2002-2013 by Mike Schilli <m@perlmeister.com> and Kevin Goess
180 <cpan@goess.org>.
181 This library is free software; you can redistribute it and/or modify it
183 under the same terms as Perl itself.
184
186 Please contribute patches to the project on Github:
187 http://github.com/mschilli/log4perl
189 Send bug reports or requests for enhancements to the authors via our
191 MAILING LIST (questions, bug reports, suggestions/patches):
193 log4perl-devel@lists.sourceforge.net
194 Authors (please contact them via the list above, not directly): Mike
196 Schilli <m@perlmeister.com>, Kevin Goess <cpan@goess.org>
197 Contributors (in alphabetical order): Ateeq Altaf, Cory Bennett, Jens
199 Berthold, Jeremy Bopp, Hutton Davidson, Chris R. Donnelly, Matisse
200 Enzer, Hugh Esco, Anthony Foiani, James FitzGibbon, Carl Franks, Dennis
201 Gregorovic, Andy Grundman, Paul Harrington, Alexander Hartmaier David
202 Hull, Robert Jacobson, Jason Kohles, Jeff Macdonald, Markus Peter,
203 Brett Rann, Peter Rabbitson, Erik Selberg, Aaron Straup Cope, Lars
204 Thegler, David Viner, Mac Yang.
205perl v5.36.0 2023-01-20 Appender::File(3)