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 han‐
31 dle and then open a one to the new file specified.
32 OPTIONS
34 filename
36 Name of the log file.
37 mode
39 Messages will be append to the file if $mode is set to the string
40 "append". Will clobber the file if set to "clobber". If it is
41 "pipe", the file will be understood as executable to pipe output
42 to. Default mode is "append".
43 autoflush
45 "autoflush", if set to a true value, triggers flushing the data out
46 to the file on every call to "log()". "autoflush" is on by default.
47 syswrite
49 "syswrite", if set to a true value, makes sure that the appender
50 uses syswrite() instead of print() to log the message. "syswrite()"
51 usually maps to the operating system's "write()" function and makes
52 sure that no other process writes to the same log file while
53 "write()" is busy. Might safe you from having to use other syncro‐
54 nisation measures like semaphores (see: Synchronized 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 bin‐
86 mode 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 "recre‐
122 ate_check_interval" to 0 will have the appender 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 "newsys‐
131 log".
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 Design and implementation of this module has been greatly inspired by
141 Dave Rolsky's "Log::Dispatch" appender framework.
142
144 Mike Schilli <log4perl@perlmeister.com>, 2003, 2005
145perl v5.8.8 2002-07-10 Appender::File(3)