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
58 suspicious and startschecking if the file was truncated, or moved and
59 recreated. If anything like that had happened, "File::Tail" will
60 quietly reopen the file, and continue reading. The only way to affect
61 what happens on reopen is by setting the reset_tail parameter (see
62 below). The effect of this is that the scripts need not be aware when
63 the logfiles 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
70 calling the methods.
71
73 new ([ ARGS ])
74 Creates a "File::Tail". If it has only one paramter, it is assumed to
75 be the filename. If the open fails, the module performs a croak. I am
76 currently looking for a way to set $! and return undef.
77 You can pass several parameters to new:
79 name
81 This is the name of the file to open. The file will be opened for
82 reading. This must be a regular file, not a pipe or a terminal
83 (i.e. it must be seekable).
84 maxinterval
86 The maximum number of seconds (real number) that will be spent
87 sleeping. Default is 60, meaning "File::Tail" will never spend
88 more than sixty seconds without checking the file.
89 interval
91 The initial number of seconds (real number) that will be spent
92 sleeping, before the file is first checked. Default is ten seconds,
93 meaning "File::Tail" will sleep for 10 seconds and then determine,
94 how many new lines have appeared in the file.
95 adjustafter
97 The number of "times" "File::Tail" waits for the current interval,
98 before adjusting the interval upwards. The default is 10.
99 resetafter
101 The number of seconds after last change when "File::Tail" decides
102 the file may have been closed and reopened. The default is
103 adjustafter*maxinterval.
104 maxbuf
106 The maximum size of the internal buffer. When File::Tail suddenly
107 found an enormous ammount of information in the file (for instance
108 if the retry parameters were set to very infrequent checking and
109 the file was rotated), File::Tail sometimes slurped way too much
110 file into memory. This sets the maximum size of File::Tail's
111 buffer.
112 Default value is 16384 (bytes).
114 A large internal buffer may result in worse performance (as well as
116 increased memory usage), since File::Tail will have to do more work
117 processing the internal buffer.
118 nowait
120 Does not block on read, but returns an empty string if there is
121 nothing to read. DO NOT USE THIS unless you know what you are
122 doing. If you are using it in a loop, you probably DON'T know what
123 you are doing. If you want to read tails from multiple files, use
124 select.
125 ignore_nonexistant
127 Do not complain if the file doesn't exist when it is first
128 opened or when it is to be reopened. (File may be reopened after
129 resetafter seconds have passed since last data was found.)
130 tail
132 When first started, read and return C<n> lines from the file.
133 If C<n> is zero, start at the end of file. If C<n> is negative,
134 return the whole file.
135 Default is C<0>.
137 reset_tail
139 Same as tail, but applies after reset. (i.e. after the
140 file has been automaticaly closed and reopened). Defaults to
141 C<-1>, i.e. does not skip any information present in the
142 file when it first checks it.
143 Why would you want it otherwise? I've seen files which
145 have been cycled like this:
146 grep -v lastmonth log >newlog
148 mv log archive/lastmonth
149 mv newlog log
150 kill -HUP logger
151 Obviously, if this happens and you have reset_tail set to c<-1>,
153 you will suddenly get a whole bunch of lines - lines you already
154 saw. So in this case, reset_tail should probably be set to a small
155 positive number or even 0.
156 name_changes
158 Some logging systems change the name of the file they are writing
159 to, sometimes to include a date, sometimes a sequence number,
160 sometimes other, even more bizarre changes.
161 Instead of trying to implement various clever detection methods,
163 File::Tail will call the code reference defined in name_changes.
164 The code reference should return the string which is the new name
165 of the file to try opening.
166 Note that if the file does not exist, File::Tail will report a
168 fatal error (unless ignore_nonexistant has also been specified).
169 debug
171 Set to nonzero if you want to see more about the inner workings of
172 File::Tail. Otherwise not useful.
173 errmode
175 Modeled after the methods from Net:Telnet, here you decide how the
176 errors should be handled. The parameter can be a code reference
177 which is called with the error string as a parameter, an array with
178 a code reference as the first parameter and other parameters to be
179 passed to handler subroutine, or one of the words:
180 return - ignore any error (just put error message in errmsg).
182 warn - output the error message but continue die - display
183 error message and exit
184 Default is die.
186
188 read
189 "read" returns one line from the input file. If there are no lines
190 ready, it blocks until there are.
191 select
193 "select" is intended to enable the programmer to simoultaneously wait
194 for input on normal filehandles and File::Tail filehandles. Of course,
195 you may use it to simply read from more than one File::Tail filehandle
196 at a time.
197 Basicaly, you call File::Tail::select just as you would normal select,
199 with fields for rbits, wbits and ebits, as well as a timeout, however,
200 you can tack any number of File::Tail objects (not File::Tail
201 filehandles!) to the end.
202 Usage example:
204 foreach (@ARGV) {
206 push(@files,File::Tail->new(name=>"$_",debug=>$debug));
207 }
208 while (1) {
209 ($nfound,$timeleft,@pending)=
210 File::Tail::select(undef,undef,undef,$timeout,@files);
211 unless ($nfound) {
212 # timeout - do something else here, if you need to
213 } else {
214 foreach (@pending) {
215 print $_->{"input"}." (".localtime(time).") ".$_->read;
216 }
217 }
218 #
220 # There is a more elaborate example in select_demo in the distribution.
221 #
222 When you do this, File::Tail's select emulates normal select, with two
224 exceptions:
225 a) it will return if there is input on any of the parameters (i.e.
227 normal filehandles) _or_ File::Tails.
228 b) In addition to "($nfound, $timeleft)", the return array will also
230 contain a list of File::Tail objects which are ready for reading.
231 $nfound will contain the correct number of filehandles to be read (i.e.
232 both normal and File::Tails).
233 Once select returns, when you want to determine which File::Tail
235 objects have input ready, you can either use the list of objects select
236 returned, or you can check each individual object with
237 $object->predict. This returns the ammount of time (in fractional
238 seconds) after which the handle expects input. If it returns 0, there
239 is input waiting. There is no guarantee that there will be input
240 waiting after the returned number of seconds has passed. However,
241 File::Tail won't do any I/O on the file until that time has passed.
242 Note that the value of $timeleft may or may not be correct - that
243 depends on the underlying operating system (and it's select), so you're
244 better off NOT relying on it.
245 Also note, if you are determining which files are ready for input by
247 calling each individual predict, the $nfound value may be invalid,
248 because one or more of File::Tail object may have become ready between
249 the time select has returned and the time when you checked it.
250
252 Planned for 1.0: Using $/ instead of \n to separate "lines" (which
253 should make it possible to read wtmp type files). Except that I
254 discovered I have no need for that enhancement If you do, feel free to
255 send me the patches and I'll apply them - if I feel they don't add too
256 much processing time.
257
259 Matija Grabnar, matija.grabnar@arnes.si
260
262 perl(1), tail (1), MRTG
263 (http://ee-staff.ethz.ch/~oetiker/webtools/mrtg/mrtg.html)
264perl v5.12.0 2010-05-01 Tail(3)