1Tail(3) User Contributed Perl Documentation Tail(3)
2
6 File::Tail - Perl extension for reading from continously updated files
7
9 use File::Tail;
10 $file=File::Tail->new("/some/log/file");
11 while (defined($line=$file->read)) {
12 print "$line";
13 }
14 use File::Tail;
16 $file=File::Tail->new(name=>$name, maxinterval=>300, adjustafter=>7);
17 while (defined($line=$file->read)) {
18 print "$line";
19 }
20 OR, you could use tie (additional parameters can be passed with the
22 name, or can be set using $ref):
23 use File::Tail;
25 my $ref=tie *FH,"File::Tail",(name=>$name);
26 while (<FH>) {
27 print "$_";
28 }
29 Note that the above script will never exit. If there is nothing being
31 written to the file, it will simply block.
32 You can find more synopsii in the file logwatch, which is included in
34 the distribution.
35 Note: Select functionality was added in version 0.9, and it required
37 some reworking of all routines. ***PLEASE*** let me know if you see
38 anything strange happening.
39 You can find two way of using select in the file select_demo which is
41 included in the ditribution.
42
44 The primary purpose of File::Tail is reading and analysing log files
45 while they are being written, which is especialy usefull if you are
46 monitoring the logging process with a tool like Tobias Oetiker's MRTG.
47 The module tries very hard NOT to "busy-wait" on a file that has little
49 traffic. Any time it reads new data from the file, it counts the number
50 of new lines, and divides that number by the time that passed since
51 data were last written to the file before that. That is considered the
52 average time before new data will be written. When there is no new data
53 to read, "File::Tail" sleeps for that number of seconds. Thereafter,
54 the waiting time is recomputed dynamicaly. Note that "File::Tail" never
55 sleeps for more than the number of seconds set by "maxinterval".
56 If the file does not get altered for a while, "File::Tail" gets suspi‐
58 cious and startschecking if the file was truncated, or moved and recre‐
59 ated. If anything like that had happened, "File::Tail" will quietly
60 reopen the file, and continue reading. The only way to affect what hap‐
61 pens on reopen is by setting the reset_tail parameter (see below). The
62 effect of this is that the scripts need not be aware when the logfiles
63 were rotated, they will just quietly work on.
64 Note that the sleep and time used are from Time::HiRes, so this module
66 should do the right thing even if the time to sleep is less than one
67 second.
68 The logwatch script (also included) demonstrates several ways of call‐
70 ing the methods.
71
73 new ([ ARGS ])
74 Creates a "File::Tail". If it has only one paramter, it is assumed to
76 be the filename. If the open fails, the module performs a croak. I am
77 currently looking for a way to set $! and return undef.
78 You can pass several parameters to new:
80 name
82 This is the name of the file to open. The file will be opened for
83 reading. This must be a regular file, not a pipe or a terminal
84 (i.e. it must be seekable).
85 maxinterval
87 The maximum number of seconds (real number) that will be spent
88 sleeping. Default is 60, meaning "File::Tail" will never spend
89 more than sixty seconds without checking the file.
90 interval
92 The initial number of seconds (real number) that will be spent
93 sleeping, before the file is first checked. Default is ten seconds,
94 meaning "File::Tail" will sleep for 10 seconds and then determine,
95 how many new lines have appeared in the file.
96 adjustafter
98 The number of "times" "File::Tail" waits for the current interval,
99 before adjusting the interval upwards. The default is 10.
100 resetafter
102 The number of seconds after last change when "File::Tail" decides
103 the file may have been closed and reopened. The default is
104 adjustafter*maxinterval.
105 maxbuf
107 The maximum size of the internal buffer. When File::Tail suddenly
108 found an enormous ammount of information in the file (for instance
109 if the retry parameters were set to very infrequent checking and
110 the file was rotated), File::Tail sometimes slurped way too much
111 file into memory. This sets the maximum size of File::Tail's buf‐
112 fer.
113 Default value is 16384 (bytes).
115 A large internal buffer may result in worse performance (as well as
117 increased memory usage), since File::Tail will have to do more work
118 processing the internal buffer.
119 nowait
121 Does not block on read, but returns an empty string if there is
122 nothing to read. DO NOT USE THIS unless you know what you are
123 doing. If you are using it in a loop, you probably DON'T know what
124 you are doing. If you want to read tails from multiple files, use
125 select.
126 ignore_nonexistant
128 Do not complain if the file doesn't exist when it is first
129 opened or when it is to be reopened. (File may be reopened after
130 resetafter seconds have passed since last data was found.)
131 tail
133 When first started, read and return C<n> lines from the file.
134 If C<n> is zero, start at the end of file. If C<n> is negative,
135 return the whole file.
136 Default is C<0>.
138 reset_tail
140 Same as tail, but applies after reset. (i.e. after the
141 file has been automaticaly closed and reopened). Defaults to
142 C<-1>, i.e. does not skip any information present in the
143 file when it first checks it.
144 Why would you want it otherwise? I've seen files which
146 have been cycled like this:
147 grep -v lastmonth log >newlog
149 mv log archive/lastmonth
150 mv newlog log
151 kill -HUP logger
152 Obviously, if this happens and you have reset_tail set to c<-1>,
154 you will suddenly get a whole bunch of lines - lines you already
155 saw. So in this case, reset_tail should probably be set to a small
156 positive number or even 0.
157 name_changes
159 Some logging systems change the name of the file they are writing
160 to, sometimes to include a date, sometimes a sequence number, some‐
161 times other, even more bizarre changes.
162 Instead of trying to implement various clever detection methods,
164 File::Tail will call the code reference defined in name_changes.
165 The code reference should return the string which is the new name
166 of the file to try opening.
167 Note that if the file does not exist, File::Tail will report a
169 fatal error (unless ignore_nonexistant has also been specified).
170 debug
172 Set to nonzero if you want to see more about the inner workings of
173 File::Tail. Otherwise not useful.
174 errmode
176 Modeled after the methods from Net:Telnet, here you decide how the
177 errors should be handled. The parameter can be a code reference
178 which is called with the error string as a parameter, an array with
179 a code reference as the first parameter and other parameters to be
180 passed to handler subroutine, or one of the words:
181 return - ignore any error (just put error message in errmsg).
183 warn - output the error message but continue die - display
184 error message and exit
185 Default is die.
187
189 read
190 "read" returns one line from the input file. If there are no lines
192 ready, it blocks until there are.
193 select
195 "select" is intended to enable the programmer to simoultaneously wait
197 for input on normal filehandles and File::Tail filehandles. Of course,
198 you may use it to simply read from more than one File::Tail filehandle
199 at a time.
200 Basicaly, you call File::Tail::select just as you would normal select,
202 with fields for rbits, wbits and ebits, as well as a timeout, however,
203 you can tack any number of File::Tail objects (not File::Tail filehan‐
204 dles!) to the end.
205 Usage example:
207 foreach (@ARGV) {
209 push(@files,File::Tail->new(name=>"$_",debug=>$debug));
210 }
211 while (1) {
212 ($nfound,$timeleft,@pending)=
213 File::Tail::select(undef,undef,undef,$timeout,@files);
214 unless ($nfound) {
215 # timeout - do something else here, if you need to
216 } else {
217 foreach (@pending) {
218 print $_->{"input"}." (".localtime(time).") ".$_->read;
219 }
220 }
221 #
223 # There is a more elaborate example in select_demo in the distribution.
224 #
225 When you do this, File::Tail's select emulates normal select, with two
227 exceptions:
228 a) it will return if there is input on any of the parameters (i.e. nor‐
230 mal filehandles) _or_ File::Tails.
231 b) In addition to "($nfound, $timeleft)", the return array will also
233 contain a list of File::Tail objects which are ready for reading.
234 $nfound will contain the correct number of filehandles to be read (i.e.
235 both normal and File::Tails).
236 Once select returns, when you want to determine which File::Tail
238 objects have input ready, you can either use the list of objects select
239 returned, or you can check each individual object with $object->pre‐
240 dict. This returns the ammount of time (in fractional seconds) after
241 which the handle expects input. If it returns 0, there is input wait‐
242 ing. There is no guarantee that there will be input waiting after the
243 returned number of seconds has passed. However, File::Tail won't do
244 any I/O on the file until that time has passed. Note that the value of
245 $timeleft may or may not be correct - that depends on the underlying
246 operating system (and it's select), so you're better off NOT relying on
247 it.
248 Also note, if you are determining which files are ready for input by
250 calling each individual predict, the $nfound value may be invalid,
251 because one or more of File::Tail object may have become ready between
252 the time select has returned and the time when you checked it.
253
255 Planned for 1.0: Using $/ instead of \n to separate "lines" (which
256 should make it possible to read wtmp type files). Except that I dis‐
257 covered I have no need for that enhancement If you do, feel free to
258 send me the patches and I'll apply them - if I feel they don't add too
259 much processing time.
260
262 Matija Grabnar, matija.grabnar@arnes.si
263
265 perl(1), tail (1), MRTG
266 (http://ee-staff.ethz.ch/~oetiker/webtools/mrtg/mrtg.html)
267perl v5.8.8 2006-06-08 Tail(3)