.\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Multi 3"
.TH Multi 3 "2008-04-27" "perl v5.10.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
.Vb 1
\&  File::Tail::Multi \- Perl extension to a stateful tail of multiple files for Unix systems
.Ve
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 10
\&  use File::Tail::Multi;
\&  my @_LIST_OF_FILE_PATHS = ("/path/to/one/file", "/path/to/another/file");
\&  my $rptTail = File::Tail::Multi\->new( 
\&        Function => \e&_read_line,
\&        LastRun_File => "/path/to/app.lastrun",
\&        Files =>    @_LIST_OF_FILE_PATHS
\&        );
\&  sub _read_line {
\&    my $lines_ref = shift;      
\&        foreach ( @{$lines_ref} ) {
\&                chomp;
\&                next if $_ =~ //;
\&                #go play, here\*(Aqs the line
\&        }
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.Vb 3
\& Derived from MultiTail, this perl library makes it easy to
\& tail a dynamic list of files and match/except lines using full
\& regular expressions and even maintains their state locally.
.Ve
.PP
File::Tail::Multi;
.PP
.Vb 3
\&        will tail multiple files and return the records 
\&        read to a Data Structure. The Data Structure can 
\&        be processed by File::Tail::Multi functions
.Ve
.PP
The  files  specified  are processed in accordance with the 
following rules:
.PP
Note: File devices and inode number uniquely identify each entry 
in the \s-1UNIX\s0 filesystem. If the \fIstat()\fR command shows them to be 
the same, then only one will be used. Windows \s-1NT\s0 filesystem
\&\s-1NTFS\s0 does not allow links so I don't check for links on \s-1NT\s0.
.PP
(1) Files that exist at program start  time  will  be  
    positioned to Object attribute \*(L"NumLines\*(R" before input.
.PP
(2) Files that become available subsequently  will  be  read
    from the beginning. Attribute ScanForFiles must be set to
    True (>=1) for the option.
.PP
(3) If a file that has been selected as per rules 1 or 2  is
    deleted  or  truncated input will continue until end-of-file
    is reached before the file is closed.
.PP
(4) If a file is deleted and  it is recreated it
    is treated as a new file, will  be  read
    from the beginning
.PP
(5) To conserve file descriptors, files that are selected for
    input  are  not actually opened until data is present beyond
    the input point selected.  For example,
    if a file exists when ptail starts, ptail will determine the
    file mtime at that time and only open the file when the  mtime
    increases.
.PP
.Vb 3
\&    Note: mtime = Time when data was last modified. Changed by  the
\&                  following functions: creat, mknod, pipe, utime,
\&                  and write.
.Ve
.PP
(6) If an opened file has not been updated for File::Tail::Multi Object attribute
    \*(L"MaxAge\*(R" minutes it will be closed.  
    It will be reopened if it is later updated.
.PP
(7) Since File::Tail::Multi is \s-1OO\s0 you can alway change its attributes. If you change
    the list of file to be tailed (Files attribute) the attribute
    ScanForFiles will set to true and all dir and files ilists will be
    check for new files.
.SH "METHODS"
.IX Header "METHODS"
.IP "new" 4
.IX Item "new"
Creating a new \s-1PTAIL\s0 object
.Sp
\&\f(CW$tail\fR = File::Tail::Multi\->new( 
			OutputPrefix => 'tf',
            RemoveDuplicate => \f(CW$True\fR,
            Files => ['/var/log','/var/adm/*.log'] );
.Sp
Or
.Sp
\&\f(CW$tail\fR = File::Tail::Multi\->new;
\&\f(CW$tail\fR\->Files(['/var/log','/var/adm/*.log']);
\&\f(CW$tail\fR\->RemoveDuplicate($True);
.Sp
.Vb 2
\&    class/object method takes arguments ( All have defaults )
\&    and returning a reference to a newly created File::Tail::Multi object.
\&
\&    File     :  File attribute accepts file names that includes 
\&        both explicit file/dir names and file/dir expressions.
\&        Duplicate file paths are rejected, along with non\-duplicate 
\&    names that resolve to a device/inode combination that is currently 
\&        being read. NT file name must start with drive letter or //. 
\& 
\&    Pattern  :  Arguments can be a file name or an array of patterns
\&        Stores in object attribute  "LineArray" all lines
\&        that contain the patterns
\&        (Default is *)
\&
\&    ExceptPattern : Arguments can be a file name or an array of patterns
\&        Stores in object attribute  "LineArray" all lines except
\&        those that contain the patterns
\&        (Default is *)
\&
\&    MaxAge  : Maximum time in minute that an open file will be held open
\&        without an update.
\&        (Default is 10 minute)
\&
\&    NumLines : Files that exist at File::Tail::Multi start time will have up to
\&        NumLines lines from the end of file displayed. 
\&        Similar to tail \-NumLines.  
\&        (Default is 10)
\&
\&    Fuction  : Reference to a function that will be run by the File::Tail::Multi
\&        object.
\&        File::Tail::Multi object will pass a ref array of all the lines read from
\&        the files and passed through any filters you set in the object
\&                 to the function.
\&        0 = (Default) No Fuction
\&
\&    ScanForFiles : Maximum time in minute before Read will scan for new
\&                                 files.
\&        If you change the attribute "Files" with fuction update_attribute
\&        the next Read will scan for new files.
\&        0 = (Default) Off 
\&
\&    RemoveDuplicate : Removes all duplicate lines from LineArray
\&        0 = (Default) Off
\&        1 = On
\&
\&    Debug : Turn Debuging messages on for File::Tail::Multi.pm.
\&        0 = (Default) Off
\&        1 = On
\&
\&    LastRun_File : Path to file where the last read status of each tailed file is stored
\&
\&    OutputPrefix : Determines the prefix applied to each output record.
\&        Output records are store in File::Tail::Multi object attribute "LineArray"
\&        The prefix is separated from the record by \*(Aq: \*(Aq.
\&        Prefixes supported are:
\&                       p  : path name of the input file
\&                       f  : file name of the input file
\&                       t  : time in HHMMSS
\&                       tg : time in HHMMSS GMT
\&                       tc : time in MM/DD/YYYY HH:MM:SS
\&                       pt : path and time
\&                       ptg: path and time GMT
\&                       ptc: path and time complete
\&                       ft : file and time
\&                       ftg: file and time GMT
\&                       ftc: file and time complete
\&                       tp : time and path
\&                       tpg: time and path GMT
\&                       tpc: time complete and path
\&                       tf : time and file
\&                       tfg: time and file GMT
\&                       tfc: time complete and file
\&        0 = (Default) No prefix
\&        GMT = Greenwich time ZONE
\&
\& Exit Codes
\&
\&         1001 \- MaxAge is less the zero
\&         1002 \- NumLines is less the zero
\&         1003 \- OutputPrefix must one ( )
\&         1004 \- Pattern must is not a file or ARRAY
\&         1005 \- ExceptPattern is not a file or ARRAY
\&         1006 \- Debug is not 0 or 1
\&         1007 \- ScanForFiles is less the zero
\&         1008 \- RemoveDuplicate is not 0 or 1
\&         1009 \- Function is not ref to fuction
\&         1010 \- File attribute not set
.Ve
.IP "read" 4
.IX Item "read"
Read all new data from file
.Sp
\&\f(CW$tail\fR\->read
.Sp
Read all new date from tailed files and return new lines as part of the
Data Structure (File::Tail::Multi Object attribute LineArray)
.IP "readline" 4
.IX Item "readline"
Read one line of new data from file. After it reads \f(CW$NumLines\fR, program quits
.Sp
\&\f(CW$tail\fR\->readline
.Sp
Read only one line of new date from tailed files and return new lines as part of the
Data Structure (File::Tail::Multi Object attribute LineArray)
.IP "print" 4
.IX Item "print"
Print all line contained in File::Tail::Multi Object attribute LineArray
.Sp
\&\f(CW$tail\fR\->print
.IP "update_attribute" 4
.IX Item "update_attribute"
Allow you to Update (Change) any File::Tail::Multi Object attribute
.Sp
\&\f(CW$tail\fR\->update_attribute(
	Files => [\*(L"/var/log\*(R",\*(L"/var/adm\*(R",\*(L"/home/nnysgm/logwatcher/foo*\*(R"],
	ExceptPattern => /home/nnysgm/ExceptPattern.txt,
	RemoveDuplicate => \f(CW$True\fR
	);
.Sp
This changes the Files, ExceptPattern and RemoveDuplicate
attributes for the Object \f(CW$tail\fR.
.Sp
New files will be scanned for during next Read if \*(L"Files\*(R" attribute is 
changed.
.Sp
Also you can use supplied methods to set attribute values.
.Sp
\&\f(CW$tail\fR\->RemoveDuplicate($True);
\&\f(CW$tail\fR\->NumLines(100);
.IP "version" 4
.IX Item "version"
Return version number on \s-1PTAIL\s0 package
.Sp
\&\f(CW$tail\fR\->version
.IP "debug" 4
.IX Item "debug"
Toggle the debug switch for File::Tail::Multi package
.Sp
\&\f(CW$tail\fR\->debug
.Sp
.Vb 1
\&        There are a number of  function in the File::Tail::Multi.pm module.
\&                
\&                o printstat :
\&                        Print out stat output for each file.
\&                o printfilestates :
\&                        Print out All file states. 
\&                        (See note in File::Tail::Multi.pm for function OpenUpdateFiles)
\&                o printpat :
\&                        Print out lines from pattern file array.
\&                o printexceptpat :
\&                        Print out line from pattern file except array.
.Ve
.IP "close_all_files" 4
.IX Item "close_all_files"
Closes all file that are being tailed
.Sp
\&\f(CW$tail\fR\->close_all_files
.SH "EXAMPLE"
.IX Header "EXAMPLE"
1)
	use File::Tail::Multi;
.PP
.Vb 4
\&        $tail1=File::Tail::Multi\->new (  OutputPrefix => "f", 
\&                      Debug => "$True", 
\&                      Files => ["/var/adm/messages"]
\&        );
\&
\&        while(1) {
\&                $tail1\->read;
\&                #
\&                $tail1\->print;
\&                sleep 10;
\&        }
.Ve
.PP
\&\f(CW$tail1\fR=File::Tail::Multi\->new : Create new ptail object
.PP
\&\- Files => Tail file /var/adm/messages
.PP
\&\- OutputPrefix => Prepend the name of the file beginning of each
  line in object attribute  \*(L"LineArray\*(R"
.PP
\&\f(CW$tail1\fR\->read      : Read all line from files
.PP
\&\f(CW$tail1\fR\->print     : Print all line in object attribute  \*(L"LineArray\*(R";
.PP
2)
	use File::Tail::Multi;
.PP
.Vb 6
\&        $tail1=File::Tail::Multi\->new (  OutputPrefix => "tf", 
\&                      Pattern => "/home/nnysgm/logwatcher/pattern",
\&                      ExceptPattern => "/home/nnysgm/logwatcher/epattern",
\&                      Fuction = > \e&want,
\&            Files => ["/var/adm","/var/log/*.log"]
\&        );
\&
\&        while(1) {
\&                $tail1\->read;
\&                #
\&                $tail1\->print;
\&                sleep 10;
\&        }
\&        
\&        sub want {
\&                        (your code .... );
\&        }
.Ve
.PP
\&\f(CW$tail1\fR=File::Tail::Multi\->new : Create new ptail object
.PP
\&\- OutputPrefix => Prepend the name of the file and time to the
  beginning of each line in object attribute  \*(L"LineArray\*(R"
.PP
\&\- ExceptPattern => Stores in object attribute  \*(L"LineArray\*(R" all lines except 
  those that contain the patterns from file \*(L"epattern\*(R"
\&\- Pattern => Stores in object attribute  \*(L"LineArray\*(R" all lines  
  that contain the patterns from file \*(L"pattern\*(R"
.PP
\&\- Fuction => ref to a function that will be run by File::Tail::Multi object.
  File::Tail::Multi object will pass a ref array to the function of all the lines read from 
  the file and passed through any filters you set in the object.
.PP
\&\- Files => Tail all files in dir /var/adm and all .log files
  dir /var/log.
.PP
\&\f(CW$tail1\fR\->read      : Read all line from files
.PP
\&\f(CW$tail1\fR\->print     : Print all line in object attribute  \*(L"LineArray\*(R";
.PP
3)
   use File::Tail::Multi;
.PP
.Vb 1
\&   $tail=File::Tail::Multi\->new;
\&
\&        $tail\->OutputPrefix(tf);
\&   $tail\->Fuction(\e&want);
\&   $tail\->Files(["/var/adm","/var/log/*.log"]);
\&  
\&   while(1) {
\&      $tail1\->read;
\&   }
\&                      
\&   sub want {
\&         (your code .... );
\&   }
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Arvind Tripathy, arvindt@gmail.com
.SH "SEE ALSO"
.IX Header "SEE ALSO"
<a href='search.cpan.org/perldoc?File%3A%3ATail'>File::Tail</a>
.PP
<a href='search.cpan.org/perldoc?File%3A%3ATail%3A%3AApp'>File\-Tail\-App</a>
.PP
<a href='search.cpan.org/perldoc?MultiTail'>MultiTail</a>
.SH "Copyright and License"
.IX Header "Copyright and License"
Copyright 2008 by Arvind Tripathy
.PP
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.