1Agent::Channel::File(3)User Contributed Perl DocumentatioAngent::Channel::File(3)
2
3
4

NAME

6       Log::Agent::Channel::File - file logging channel for Log::Agent
7

SYNOPSIS

9        require Log::Agent::Channel::File;
10
11        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

DESCRIPTION

22       The file channel performs logging to a file, along with the necessary
23       prefixing and stamping of the messages.
24
25       Internally, the "Log::Agent::Driver::File" driver creates such objects
26       for each logging channel defined at driver creation time.
27
28       The creation routine make() takes the following arguments:
29
30       "-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
35       "-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
41       "-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
45           Default is false.
46
47       "-no_newline" => flag
48           When set to true, never append any "\n" (on Unix) or "\r\n" (on
49           Windows) to log messages.
50
51           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
55           Default is false, meaning newline markers are systematically
56           appended.
57
58       "-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
63           Default is false.
64
65       "-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
72           Default is false, meaning uppercasing is performed.
73
74       "-prefix" => prefix
75           The application prefix string to prepend to messages.
76
77       "-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
81           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
85       "-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
90           However, you will get this message in the file
91
92            Rotation for 'filename' may be wrong (shared with distinct policies)
93
94           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
98       "-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
102           Default is false.
103
104       "-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
109           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

CAVEAT

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

AUTHORS

123       Originally written by Raphael Manfredi <Raphael_Manfredi@pobox.com>,
124       currently maintained by Mark Rogaski <mrogaski@cpan.org>.
125

LICENSE

127       Copyright (C) 1999 Raphael Manfredi.  Copyright (C) 2002 Mark Rogaski,
128       mrogaski@cpan.org; all rights reserved.
129
130       See Log::Agent(3) or the README file included with the distribution for
131       license information.
132

SEE ALSO

134       Log::Agent::Logger(3), Log::Agent::Channel(3).
135
136
137
138perl v5.38.0                      2023-07-20           Agent::Channel::File(3)
Impressum