1Agent::Channel::File(3)User Contributed Perl DocumentatioAngent::Channel::File(3)
2
6 Log::Agent::Channel::File - file logging channel for Log::Agent
7
9 require Log::Agent::Channel::File;
10 my $driver = Log::Agent::Channel::File->make(
12 -prefix => "prefix",
13 -stampfmt => "own",
14 -showpid => 1,
15 -magic_open => 0,
16 -filename => "/tmp/output.err",
17 -fileperm => 0640,
18 -share => 1,
19 );
20
22 The file channel performs logging to a file, along with the necessary
23 prefixing and stamping of the messages.
24 Internally, the "Log::Agent::Driver::File" driver creates such objects
26 for each logging channel defined at driver creation time.
27 The creation routine make() takes the following arguments:
29 "-filename" => file
31 The file name where output should go. The file is opened in append
32 mode and autoflushing is turned on. See also the "-magic_open"
33 flag.
34 "-fileperm" => perm
36 The permissions that the file should be opened with (XOR'd with the
37 user's umask). Due to the nature of the underlying open() and
38 sysopen(), the value is limited to less than or equal to 0666. See
39 "umask" in perlfunc(3) for more details.
40 "-magic_open" => flag
42 When true, channel filenames beginning with '>' or '|' are opened
43 using Perl's open(). Otherwise, sysopen() is used, in append mode.
44 Default is false.
46 "-no_newline" => flag
48 When set to true, never append any "\n" (on Unix) or "\r\n" (on
49 Windows) to log messages.
50 Internally, Log::Agent relies on the channel to delimit logged
52 lines appropriately, so this flag is not used. However, it might
53 be useful for "Log::Agent::Logger" users.
54 Default is false, meaning newline markers are systematically
56 appended.
57 "-no_prefixing" => flag
59 When set to true, disable the prefixing logic entirely, i.e. the
60 following options are ignored completely: "-prefix", "-showpid",
61 "-no_ucfirst", "-stampfmt".
62 Default is false.
64 "-no_ucfirst" => flag
66 When set to true, don't upper-case the first letter of the log
67 message entry when there's no prefix inserted before the logged
68 line. When there is a prefix, a ":" character follows, and
69 therefore the leading letter of the message should not be upper-
70 cased anyway.
71 Default is false, meaning uppercasing is performed.
73 "-prefix" => prefix
75 The application prefix string to prepend to messages.
76 "-rotate" => object
78 This sets a default logfile rotation policy. You need to install
79 the additional "Log::Agent::Rotate" module to use this switch.
80 object is the "Log::Agent::Rotate" instance describing the rotating
82 policy for the channel. Only files which are not opened via a so-
83 called magic open can be rotated.
84 "-share" => flag
86 When true, this flag records the channel in a global pool indexed
87 by filenames. An existing file handle for the same filename may be
88 then be shared amongst several file channels.
89 However, you will get this message in the file
91 Rotation for 'filename' may be wrong (shared with distinct policies)
93 when a rotation policy different from the one used during the
95 initial opening is given. Which policy will be used is
96 unspecified, on purpose.
97 "-showpid" => flag
99 If set to true, the PID of the process will be appended within
100 square brackets after the prefix, to all messages.
101 Default is false.
103 "-stampfmt" => (name | CODE)
105 Specifies the time stamp format to use. By default, my "own" format
106 is used. See Log::Agent::Stamping for a description of the
107 available format names.
108 You may also specify a CODE ref: that routine will be called every
110 time we need to compute a time stamp. It should not expect any
111 parameter, and should return a string.
112
114 Beware of chdir(). If your program uses chdir(), you should always
115 specify logfiles by using absolute paths, otherwise you run the risk of
116 having your relative paths become invalid: there is no anchoring done
117 at the time you specify them. This is especially true when configured
118 for rotation, since the logfiles are recreated as needed and you might
119 end up with many logfiles scattered throughout all the directories you
120 chdir()ed to.
121
123 Originally written by Raphael Manfredi <Raphael_Manfredi@pobox.com>,
124 currently maintained by Mark Rogaski <mrogaski@cpan.org>.
125
127 Copyright (C) 1999 Raphael Manfredi. Copyright (C) 2002 Mark Rogaski,
128 mrogaski@cpan.org; all rights reserved.
129 See Log::Agent(3) or the README file included with the distribution for
131 license information.
132
134 Log::Agent::Logger(3), Log::Agent::Channel(3).
135perl v5.38.0 2023-07-20 Agent::Channel::File(3)