NAME
      File::Tail::Multi - Perl extension to a stateful tail of multiple files for Unix systems

SYNOPSIS
      use File::Tail::Multi;
      my @_LIST_OF_FILE_PATHS = ("/path/to/one/file", "/path/to/another/file");
      my $rptTail = File::Tail::Multi->new( 
            Function => \&_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's the line
            }
      }

DESCRIPTION
     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.

    File::Tail::Multi;

            will tail multiple files and return the records 
            read to a Data Structure. The Data Structure can 
            be processed by File::Tail::Multi functions

    The files specified are processed in accordance with the following
    rules:

    Note: File devices and inode number uniquely identify each entry in the
    UNIX filesystem. If the stat() command shows them to be the same, then
    only one will be used. Windows NT filesystem NTFS does not allow links
    so I don't check for links on NT.

    (1) Files that exist at program start time will be positioned to Object
    attribute "NumLines" before input.

    (2) Files that become available subsequently will be read from the
    beginning. Attribute ScanForFiles must be set to True (>=1) for the
    option.

    (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.

    (4) If a file is deleted and it is recreated it is treated as a new
    file, will be read from the beginning

    (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.

        Note: mtime = Time when data was last modified. Changed by  the
                      following functions: creat, mknod, pipe, utime,
                      and write.

    (6) If an opened file has not been updated for File::Tail::Multi Object
    attribute "MaxAge" minutes it will be closed. It will be reopened if it
    is later updated.

    (7) Since File::Tail::Multi is OO 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.

METHODS
    new Creating a new PTAIL object

        $tail = File::Tail::Multi->new( OutputPrefix => 'tf',
        RemoveDuplicate => $True, Files => ['/var/log','/var/adm/*.log'] );

        Or

        $tail = File::Tail::Multi->new;
        $tail->Files(['/var/log','/var/adm/*.log']);
        $tail->RemoveDuplicate($True);

            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 ': '.
                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

    read
        Read all new data from file

        $tail->read

        Read all new date from tailed files and return new lines as part of
        the Data Structure (File::Tail::Multi Object attribute LineArray)

    readline
        Read one line of new data from file. After it reads $NumLines,
        program quits

        $tail->readline

        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)

    print
        Print all line contained in File::Tail::Multi Object attribute
        LineArray

        $tail->print

    update_attribute
        Allow you to Update (Change) any File::Tail::Multi Object attribute

        $tail->update_attribute( Files =>
        ["/var/log","/var/adm","/home/nnysgm/logwatcher/foo*"],
        ExceptPattern => /home/nnysgm/ExceptPattern.txt, RemoveDuplicate =>
        $True );

        This changes the Files, ExceptPattern and RemoveDuplicate attributes
        for the Object $tail.

        New files will be scanned for during next Read if "Files" attribute
        is changed.

        Also you can use supplied methods to set attribute values.

        $tail->RemoveDuplicate($True); $tail->NumLines(100);

    version
        Return version number on PTAIL package

        $tail->version

    debug
        Toggle the debug switch for File::Tail::Multi package

        $tail->debug

                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.

    close_all_files
        Closes all file that are being tailed

        $tail->close_all_files

EXAMPLE
    1) use File::Tail::Multi;

            $tail1=File::Tail::Multi->new (  OutputPrefix => "f", 
                          Debug => "$True", 
                          Files => ["/var/adm/messages"]
            );

            while(1) {
                    $tail1->read;
                    #
                    $tail1->print;
                    sleep 10;
            }

    $tail1=File::Tail::Multi->new : Create new ptail object

    - Files => Tail file /var/adm/messages

    - OutputPrefix => Prepend the name of the file beginning of each line in
    object attribute "LineArray"

    $tail1->read : Read all line from files

    $tail1->print : Print all line in object attribute "LineArray";

    2) use File::Tail::Multi;

            $tail1=File::Tail::Multi->new (  OutputPrefix => "tf", 
                          Pattern => "/home/nnysgm/logwatcher/pattern",
                          ExceptPattern => "/home/nnysgm/logwatcher/epattern",
                          Fuction = > \&want,
                Files => ["/var/adm","/var/log/*.log"]
            );

            while(1) {
                    $tail1->read;
                    #
                    $tail1->print;
                    sleep 10;
            }
        
            sub want {
                            (your code .... );
            }

    $tail1=File::Tail::Multi->new : Create new ptail object

    - OutputPrefix => Prepend the name of the file and time to the beginning
    of each line in object attribute "LineArray"

    - ExceptPattern => Stores in object attribute "LineArray" all lines
    except those that contain the patterns from file "epattern" - Pattern =>
    Stores in object attribute "LineArray" all lines that contain the
    patterns from file "pattern"

    - 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.

    - Files => Tail all files in dir /var/adm and all .log files dir
    /var/log.

    $tail1->read : Read all line from files

    $tail1->print : Print all line in object attribute "LineArray";

    3) use File::Tail::Multi;

       $tail=File::Tail::Multi->new;

            $tail->OutputPrefix(tf);
       $tail->Fuction(\&want);
       $tail->Files(["/var/adm","/var/log/*.log"]);
  
       while(1) {
          $tail1->read;
       }
                      
       sub want {
             (your code .... );
       }         

AUTHOR
    Arvind Tripathy, arvindt@gmail.com

SEE ALSO
    <a href='search.cpan.org/perldoc?File%3A%3ATail'>File::Tail</a>

    <a
    href='search.cpan.org/perldoc?File%3A%3ATail%3A%3AApp'>File-Tail-App</a>

    <a href='search.cpan.org/perldoc?MultiTail'>MultiTail</a>

Copyright and License
    Copyright 2008 by Arvind Tripathy

    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

