README
1NAME
2 File::Tail::Multi - Perl extension to a stateful tail of multiple files for Unix systems
3
4SYNOPSIS
5 use File::Tail::Multi;
6 my @_LIST_OF_FILE_PATHS = ("/path/to/one/file", "/path/to/another/file");
7 my $rptTail = File::Tail::Multi->new(
8 Function => \&_read_line,
9 LastRun_File => "/path/to/app.lastrun",
10 Files => @_LIST_OF_FILE_PATHS
11 );
12 sub _read_line {
13 my $lines_ref = shift;
14 foreach ( @{$lines_ref} ) {
15 chomp;
16 next if $_ =~ //;
17 #go play, here's the line
18 }
19 }
20
21DESCRIPTION
22 Derived from MultiTail, this perl library makes it easy to
23 tail a dynamic list of files and match/except lines using full
24 regular expressions and even maintains their state locally.
25
26 File::Tail::Multi;
27
28 will tail multiple files and return the records
29 read to a Data Structure. The Data Structure can
30 be processed by File::Tail::Multi functions
31
32 The files specified are processed in accordance with the following
33 rules:
34
35 Note: File devices and inode number uniquely identify each entry in the
36 UNIX filesystem. If the stat() command shows them to be the same, then
37 only one will be used. Windows NT filesystem NTFS does not allow links
38 so I don't check for links on NT.
39
40 (1) Files that exist at program start time will be positioned to Object
41 attribute "NumLines" before input.
42
43 (2) Files that become available subsequently will be read from the
44 beginning. Attribute ScanForFiles must be set to True (>=1) for the
45 option.
46
47 (3) If a file that has been selected as per rules 1 or 2 is deleted or
48 truncated input will continue until end-of-file is reached before the
49 file is closed.
50
51 (4) If a file is deleted and it is recreated it is treated as a new
52 file, will be read from the beginning
53
54 (5) To conserve file descriptors, files that are selected for input are
55 not actually opened until data is present beyond the input point
56 selected. For example, if a file exists when ptail starts, ptail will
57 determine the file mtime at that time and only open the file when the
58 mtime increases.
59
60 Note: mtime = Time when data was last modified. Changed by the
61 following functions: creat, mknod, pipe, utime,
62 and write.
63
64 (6) If an opened file has not been updated for File::Tail::Multi Object
65 attribute "MaxAge" minutes it will be closed. It will be reopened if it
66 is later updated.
67
68 (7) Since File::Tail::Multi is OO you can alway change its attributes.
69 If you change the list of file to be tailed (Files attribute) the
70 attribute ScanForFiles will set to true and all dir and files ilists
71 will be check for new files.
72
73METHODS
74 new Creating a new PTAIL object
75
76 $tail = File::Tail::Multi->new( OutputPrefix => 'tf',
77 RemoveDuplicate => $True, Files => ['/var/log','/var/adm/*.log'] );
78
79 Or
80
81 $tail = File::Tail::Multi->new;
82 $tail->Files(['/var/log','/var/adm/*.log']);
83 $tail->RemoveDuplicate($True);
84
85 class/object method takes arguments ( All have defaults )
86 and returning a reference to a newly created File::Tail::Multi object.
87
88 File : File attribute accepts file names that includes
89 both explicit file/dir names and file/dir expressions.
90 Duplicate file paths are rejected, along with non-duplicate
91 names that resolve to a device/inode combination that is currently
92 being read. NT file name must start with drive letter or //.
93
94 Pattern : Arguments can be a file name or an array of patterns
95 Stores in object attribute "LineArray" all lines
96 that contain the patterns
97 (Default is *)
98
99 ExceptPattern : Arguments can be a file name or an array of patterns
100 Stores in object attribute "LineArray" all lines except
101 those that contain the patterns
102 (Default is *)
103
104 MaxAge : Maximum time in minute that an open file will be held open
105 without an update.
106 (Default is 10 minute)
107
108 NumLines : Files that exist at File::Tail::Multi start time will have up to
109 NumLines lines from the end of file displayed.
110 Similar to tail -NumLines.
111 (Default is 10)
112
113 Fuction : Reference to a function that will be run by the File::Tail::Multi
114 object.
115 File::Tail::Multi object will pass a ref array of all the lines read from
116 the files and passed through any filters you set in the object
117 to the function.
118 0 = (Default) No Fuction
119
120 ScanForFiles : Maximum time in minute before Read will scan for new
121 files.
122 If you change the attribute "Files" with fuction update_attribute
123 the next Read will scan for new files.
124 0 = (Default) Off
125
126 RemoveDuplicate : Removes all duplicate lines from LineArray
127 0 = (Default) Off
128 1 = On
129
130 Debug : Turn Debuging messages on for File::Tail::Multi.pm.
131 0 = (Default) Off
132 1 = On
133
134 LastRun_File : Path to file where the last read status of each tailed file is stored
135
136 OutputPrefix : Determines the prefix applied to each output record.
137 Output records are store in File::Tail::Multi object attribute "LineArray"
138 The prefix is separated from the record by ': '.
139 Prefixes supported are:
140 p : path name of the input file
141 f : file name of the input file
142 t : time in HHMMSS
143 tg : time in HHMMSS GMT
144 tc : time in MM/DD/YYYY HH:MM:SS
145 pt : path and time
146 ptg: path and time GMT
147 ptc: path and time complete
148 ft : file and time
149 ftg: file and time GMT
150 ftc: file and time complete
151 tp : time and path
152 tpg: time and path GMT
153 tpc: time complete and path
154 tf : time and file
155 tfg: time and file GMT
156 tfc: time complete and file
157 0 = (Default) No prefix
158 GMT = Greenwich time ZONE
159
160 Exit Codes
161
162 1001 - MaxAge is less the zero
163 1002 - NumLines is less the zero
164 1003 - OutputPrefix must one ( )
165 1004 - Pattern must is not a file or ARRAY
166 1005 - ExceptPattern is not a file or ARRAY
167 1006 - Debug is not 0 or 1
168 1007 - ScanForFiles is less the zero
169 1008 - RemoveDuplicate is not 0 or 1
170 1009 - Function is not ref to fuction
171 1010 - File attribute not set
172
173 read
174 Read all new data from file
175
176 $tail->read
177
178 Read all new date from tailed files and return new lines as part of
179 the Data Structure (File::Tail::Multi Object attribute LineArray)
180
181 readline
182 Read one line of new data from file. After it reads $NumLines,
183 program quits
184
185 $tail->readline
186
187 Read only one line of new date from tailed files and return new
188 lines as part of the Data Structure (File::Tail::Multi Object
189 attribute LineArray)
190
191 print
192 Print all line contained in File::Tail::Multi Object attribute
193 LineArray
194
195 $tail->print
196
197 update_attribute
198 Allow you to Update (Change) any File::Tail::Multi Object attribute
199
200 $tail->update_attribute( Files =>
201 ["/var/log","/var/adm","/home/nnysgm/logwatcher/foo*"],
202 ExceptPattern => /home/nnysgm/ExceptPattern.txt, RemoveDuplicate =>
203 $True );
204
205 This changes the Files, ExceptPattern and RemoveDuplicate attributes
206 for the Object $tail.
207
208 New files will be scanned for during next Read if "Files" attribute
209 is changed.
210
211 Also you can use supplied methods to set attribute values.
212
213 $tail->RemoveDuplicate($True); $tail->NumLines(100);
214
215 version
216 Return version number on PTAIL package
217
218 $tail->version
219
220 debug
221 Toggle the debug switch for File::Tail::Multi package
222
223 $tail->debug
224
225 There are a number of function in the File::Tail::Multi.pm module.
226
227 o printstat :
228 Print out stat output for each file.
229 o printfilestates :
230 Print out All file states.
231 (See note in File::Tail::Multi.pm for function OpenUpdateFiles)
232 o printpat :
233 Print out lines from pattern file array.
234 o printexceptpat :
235 Print out line from pattern file except array.
236
237 close_all_files
238 Closes all file that are being tailed
239
240 $tail->close_all_files
241
242EXAMPLE
243 1) use File::Tail::Multi;
244
245 $tail1=File::Tail::Multi->new ( OutputPrefix => "f",
246 Debug => "$True",
247 Files => ["/var/adm/messages"]
248 );
249
250 while(1) {
251 $tail1->read;
252 #
253 $tail1->print;
254 sleep 10;
255 }
256
257 $tail1=File::Tail::Multi->new : Create new ptail object
258
259 - Files => Tail file /var/adm/messages
260
261 - OutputPrefix => Prepend the name of the file beginning of each line in
262 object attribute "LineArray"
263
264 $tail1->read : Read all line from files
265
266 $tail1->print : Print all line in object attribute "LineArray";
267
268 2) use File::Tail::Multi;
269
270 $tail1=File::Tail::Multi->new ( OutputPrefix => "tf",
271 Pattern => "/home/nnysgm/logwatcher/pattern",
272 ExceptPattern => "/home/nnysgm/logwatcher/epattern",
273 Fuction = > \&want,
274 Files => ["/var/adm","/var/log/*.log"]
275 );
276
277 while(1) {
278 $tail1->read;
279 #
280 $tail1->print;
281 sleep 10;
282 }
283
284 sub want {
285 (your code .... );
286 }
287
288 $tail1=File::Tail::Multi->new : Create new ptail object
289
290 - OutputPrefix => Prepend the name of the file and time to the beginning
291 of each line in object attribute "LineArray"
292
293 - ExceptPattern => Stores in object attribute "LineArray" all lines
294 except those that contain the patterns from file "epattern" - Pattern =>
295 Stores in object attribute "LineArray" all lines that contain the
296 patterns from file "pattern"
297
298 - Fuction => ref to a function that will be run by File::Tail::Multi
299 object. File::Tail::Multi object will pass a ref array to the function
300 of all the lines read from the file and passed through any filters you
301 set in the object.
302
303 - Files => Tail all files in dir /var/adm and all .log files dir
304 /var/log.
305
306 $tail1->read : Read all line from files
307
308 $tail1->print : Print all line in object attribute "LineArray";
309
310 3) use File::Tail::Multi;
311
312 $tail=File::Tail::Multi->new;
313
314 $tail->OutputPrefix(tf);
315 $tail->Fuction(\&want);
316 $tail->Files(["/var/adm","/var/log/*.log"]);
317
318 while(1) {
319 $tail1->read;
320 }
321
322 sub want {
323 (your code .... );
324 }
325
326AUTHOR
327 Arvind Tripathy, arvindt@gmail.com
328
329SEE ALSO
330 <a href='search.cpan.org/perldoc?File%3A%3ATail'>File::Tail</a>
331
332 <a
333 href='search.cpan.org/perldoc?File%3A%3ATail%3A%3AApp'>File-Tail-App</a>
334
335 <a href='search.cpan.org/perldoc?MultiTail'>MultiTail</a>
336
337Copyright and License
338 Copyright 2008 by Arvind Tripathy
339
340 This library is free software; you can redistribute it and/or modify it
341 under the same terms as Perl itself.
342
343