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 explicitely.
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
31 handle 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 syncronisation 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 0222 (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.
67 group
69 If set, specifies that the group of the newly created log file
70 should be different from the effective group id of the running
71 process. Only makes sense if the process is running as root. Both
72 numerical group ids and group names are acceptable.
73 utf8
75 If you're printing out Unicode strings, the output filehandle needs
76 to be set into ":utf8" mode:
77 my $app = Log::Log4perl::Appender::File->new(
79 filename => 'file.log',
80 mode => 'append',
81 utf8 => 1,
82 );
83 binmode
85 To manipulate the output filehandle via "binmode()", use the
86 binmode parameter:
87 my $app = Log::Log4perl::Appender::File->new(
89 filename => 'file.log',
90 mode => 'append',
91 binmode => ":utf8",
92 );
93 A setting of ":utf8" for "binmode" is equivalent to specifying the
95 "utf8" option (see above).
96 recreate
98 Normally, if a file appender logs to a file and the file gets moved
99 to a different location (e.g. via "mv"), the appender's open file
100 handle will automatically follow the file to the new location.
101 This may be undesirable. When using an external logfile rotator,
103 for example, the appender should create a new file under the old
104 name and start logging into it. If the "recreate" option is set to
105 a true value, "Log::Log4perl::Appender::File" will do exactly that.
106 It defaults to false. Check the "recreate_check_interval" option
107 for performance optimizations with this feature.
108 recreate_check_interval
110 In "recreate" mode, the appender has to continuously check if the
111 file it is logging to is still in the same location. This check is
112 fairly expensive, since it has to call "stat" on the file name and
113 figure out if its inode has changed. Doing this with every call to
114 "log" can be prohibitively expensive. Setting it to a positive
115 integer value N will only check the file every N seconds. It
116 defaults to 30.
117 This obviously means that the appender will continue writing to a
119 moved file until the next check occurs, in the worst case this will
120 happen "recreate_check_interval" seconds after the file has been
121 moved or deleted. If this is undesirable, setting
122 "recreate_check_interval" to 0 will have the appender check the
123 file with every call to "log()".
124 recreate_check_signal
126 In "recreate" mode, if this option is set to a signal name (e.g.
127 "USR1"), the appender will recreate a missing logfile when it
128 receives the signal. It uses less resources than constant polling.
129 The usual limitation with perl's signal handling apply. Check the
130 FAQ for using this option with the log rotating utility
131 "newsyslog".
132 recreate_pid_write
134 The popular log rotating utility "newsyslog" expects a pid file in
135 order to send the application a signal when its logs have been
136 rotated. This option expects a path to a file where the pid of the
137 currently running application gets written to. Check the FAQ for
138 using this option with the log rotating utility "newsyslog".
139 create_at_logtime
141 The file appender typically creates its logfile in its constructor,
142 i.e. at Log4perl "init()" time. This is desirable for most use
143 cases, because it makes sure that file permission problems get
144 detected right away, and not after days/weeks/months of operation
145 when the appender suddenly needs to log something and fails because
146 of a problem that was obvious at startup.
147 However, there are rare use cases where the file shouldn't be
149 created at Log4perl "init()" time, e.g. if the appender can't be
150 used by the current user although it is defined in the
151 configuration file. If you set "create_at_logtime" to a true value,
152 the file appender will try to create the file at log time. Note
153 that this setting lets permission problems sit undetected until log
154 time, which might be undesirable.
155 header_text
157 If you want Log4perl to print a header into every newly opened (or
158 re-opened) logfile, set "header_text" to either a string or a
159 subroutine returning a string. If the message doesn't have a
160 newline, a newline at the end of the header will be provided.
161 Design and implementation of this module has been greatly inspired by
163 Dave Rolsky's "Log::Dispatch" appender framework.
164
166 Copyright 2002-2009 by Mike Schilli <m@perlmeister.com> and Kevin Goess
167 <cpan@goess.org>.
168 This library is free software; you can redistribute it and/or modify it
170 under the same terms as Perl itself.
171perl v5.12.2 2010-08-31 Appender::File(3)