{
    "content": [
        {
            "type": "text",
            "text": "# POE::Wheel::FollowTail (perldoc)\n\n## NAME\n\nPOE::Wheel::FollowTail - follow the tail of an ever-growing file\n\n## SYNOPSIS\n\n#!perl\nuse POE qw(Wheel::FollowTail);\nPOE::Session->create(\ninlinestates => {\nstart => sub {\n$[HEAP]{tailor} = POE::Wheel::FollowTail->new(\nFilename => \"/var/log/system.log\",\nInputEvent => \"gotlogline\",\nResetEvent => \"gotlogrollover\",\n);\n},\ngotlogline => sub {\nprint \"Log: $[ARG0]\\n\";\n},\ngotlogrollover => sub {\nprint \"Log rolled over.\\n\";\n},\n}\n);\nPOE::Kernel->run();\nexit;\n\n## DESCRIPTION\n\nPOE::Wheel::FollowTail objects watch for new data at the end of a file and generate new events\nwhen things happen to the file. Its \"Filter\" parameter defines how to parse data from the file.\nEach new item is sent to the creator's session as an \"InputEvent\" event. Log rotation will\ntrigger a \"ResetEvent\".\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **PUBLIC METHODS** (4 subsections)\n- **PUBLIC EVENTS** (4 subsections)\n- **SEE ALSO**\n- **BUGS**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "POE::Wheel::FollowTail",
        "section": "",
        "mode": "perldoc",
        "summary": "POE::Wheel::FollowTail - follow the tail of an ever-growing file",
        "synopsis": "#!perl\nuse POE qw(Wheel::FollowTail);\nPOE::Session->create(\ninlinestates => {\nstart => sub {\n$[HEAP]{tailor} = POE::Wheel::FollowTail->new(\nFilename => \"/var/log/system.log\",\nInputEvent => \"gotlogline\",\nResetEvent => \"gotlogrollover\",\n);\n},\ngotlogline => sub {\nprint \"Log: $[ARG0]\\n\";\n},\ngotlogrollover => sub {\nprint \"Log rolled over.\\n\";\n},\n}\n);\nPOE::Kernel->run();\nexit;",
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 25,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 7,
                "subsections": []
            },
            {
                "name": "PUBLIC METHODS",
                "lines": 1,
                "subsections": [
                    {
                        "name": "new",
                        "lines": 2
                    },
                    {
                        "name": "new",
                        "lines": 95
                    },
                    {
                        "name": "event",
                        "lines": 24
                    },
                    {
                        "name": "tell",
                        "lines": 19
                    }
                ]
            },
            {
                "name": "PUBLIC EVENTS",
                "lines": 2,
                "subsections": [
                    {
                        "name": "IdleEvent",
                        "lines": 5
                    },
                    {
                        "name": "InputEvent",
                        "lines": 12
                    },
                    {
                        "name": "ResetEvent",
                        "lines": 9
                    },
                    {
                        "name": "ErrorEvent",
                        "lines": 21
                    }
                ]
            },
            {
                "name": "SEE ALSO",
                "lines": 4,
                "subsections": []
            },
            {
                "name": "BUGS",
                "lines": 8,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "POE::Wheel::FollowTail - follow the tail of an ever-growing file\n",
                "subsections": []
            },
            "SYNOPSIS": {
                "content": "#!perl\n\nuse POE qw(Wheel::FollowTail);\n\nPOE::Session->create(\ninlinestates => {\nstart => sub {\n$[HEAP]{tailor} = POE::Wheel::FollowTail->new(\nFilename => \"/var/log/system.log\",\nInputEvent => \"gotlogline\",\nResetEvent => \"gotlogrollover\",\n);\n},\ngotlogline => sub {\nprint \"Log: $[ARG0]\\n\";\n},\ngotlogrollover => sub {\nprint \"Log rolled over.\\n\";\n},\n}\n);\n\nPOE::Kernel->run();\nexit;\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "POE::Wheel::FollowTail objects watch for new data at the end of a file and generate new events\nwhen things happen to the file. Its \"Filter\" parameter defines how to parse data from the file.\nEach new item is sent to the creator's session as an \"InputEvent\" event. Log rotation will\ntrigger a \"ResetEvent\".\n\nPOE::Wheel::FollowTail only reads from a file, so it doesn't implement a put() method.\n",
                "subsections": []
            },
            "PUBLIC METHODS": {
                "content": "new",
                "subsections": [
                    {
                        "name": "new",
                        "content": "generate events when the corresponding file's status changes.\n"
                    },
                    {
                        "name": "new",
                        "content": "Driver\nThe optional \"Driver\" parameter specifies which driver to use when reading from the tailed file.\nIf omitted, POE::Wheel::FollowTail will use POE::Driver::SysRW. This is almost always the right\nthing to do.\n\nFilter\n\"Filter\" is an optional constructor parameter that specifies how to parse data from the followed\nfile. By default, POE::Wheel::FollowTail will use POE::Filter::Line to parse files as plain,\nnewline-separated text.\n\n$[HEAP]{tailor} = POE::Wheel::FollowTail->new(\nFilename => \"/var/log/snort/alert\",\nFilter => POE::Filter::Snort->new(),\nInputEvent => \"gotsnortalert\",\n);\n\nPollInterval\nPOE::Wheel::FollowTail needs to periodically check for new data on the followed file.\n\"PollInterval\" specifies the number of seconds to wait between checks. Applications that need to\npoll once per second may omit \"PollInterval\", as it defaults to 1.\n\nLonger poll intervals may be used to reduce the polling overhead for infrequently updated files.\n\n$[HEAP]{tailor} = POE::Wheel::FollowTail->new(\n...,\nPollInterval => 10,\n);\n\nSeek\nIf specified, \"Seek\" instructs POE::Wheel::FollowTail to seek to a specific spot in the tailed\nfile before beginning to read from it. A positive \"Seek\" value is interpreted as the number of\noctets to seek from the start of the file. Negative \"Seek\" will, like negative array indices,\nseek backwards from the end of the file. Zero \"Seek\" starts reading from the beginning of the\nfile.\n\nBe careful when using \"Seek\", as it's quite easy to seek into the middle of a record. When in\ndoubt, and when beginning at the end of the file, omit \"Seek\" entirely. POE::Wheel::FollowTail\nwill seek 4 kilobytes back from the end of the file, then parse and discard all records unto\nEOF. As long as the file's records are smaller than 4 kilobytes, this will guarantee that the\nfirst record returned will be complete.\n\n\"Seek\" may also be used with the wheel's tell() method to restore the file position after a\nprogram restart. Save the tell() value prior to exiting, and load and \"Seek\" back to it on\nsubsequent start-up.\n\nSeekBack\n\"SeekBack\" behaves like the inverse of \"Seek\". A positive value acts like a negative \"Seek\". A\nnegative value acts like a positive \"Seek\". A zero \"SeekBack\" instructs POE::Wheel::FollowTail\nto begin at the very end of the file.\n\n\"Seek\" and \"SeekBack\" are mutually exclusive.\n\nSee \"Seek\" for caveats, techniques, and an explanation of the magic that happens when neither\n\"Seek\" nor \"SeekBack\" is specified.\n\nHandle\nPOE::Wheel::FollowTail may follow a previously opened file \"Handle\". Unfortunately it cannot\nfollow log resets this way, as it won't be able to reopen the file once it has been reset.\nApplications that must follow resets should use \"Filename\" instead.\n\n\"Handle\" is still useful for files that will never be reset, or for devices that require setup\noutside of POE::Wheel::FollowTail's purview.\n\n\"Handle\" and \"Filename\" are mutually exclusive. One of them is required, however.\n\nFilename\nSpecify the \"Filename\" to watch. POE::Wheel::FollowTail will wait for the file to appear if it\ndoesn't exist. The wheel will also reopen the file if it disappears, such as when it has been\nreset or rolled over. In the case of a reset, POE::Wheel::FollowTail will also emit a\n\"ResetEvent\", if one has been requested.\n\n\"Handle\" and \"Filename\" are mutually exclusive. One of them is required, however.\n\nSee the \"SYNOPSIS\" for an example.\n\nIdleEvent\n\"IdleEvent\" is an optional event. If specified, it will fire whenever POE::Wheel::FollowTail\nchecks for activity but sees nothing. It was added in POE 1.362 as a way to advance certain test\nprograms without needing to wait conservatively large amounts of time.\n\n\"IdleEvent\" is described in \"PUBLIC EVENTS\".\n\nInputEvent\nThe \"InputEvent\" parameter is required, and it specifies the event to emit when new data arrives\nin the watched file. \"InputEvent\" is described in detail in \"PUBLIC EVENTS\".\n\nResetEvent\n\"ResetEvent\" is an optional. It specifies the name of the event that indicates file rollover or\nreset. Please see \"PUBLIC EVENTS\" for more details.\n\nErrorEvent\nPOE::Wheel::FollowTail may emit optional \"ErrorEvent\"s whenever it runs into trouble. The data\nthat comes with this event is explained in \"PUBLIC EVENTS\".\n\nevent"
                    },
                    {
                        "name": "event",
                        "content": "re-creating the object. It accepts one or more of the events listed in \"PUBLIC EVENTS\".\nUndefined event names disable those events.\n\nStop handling log resets:\n\nsub someeventhandler {\n$[HEAP]{tailor}->event( ResetEvent => undef );\n}\n\nThe events are described in more detail in \"PUBLIC EVENTS\".\n\nID\nThe ID() method returns the wheel's unique ID. It's useful for storing the wheel in a hash. All\nPOE::Wheel events should be accompanied by a wheel ID, which allows the wheel to be referenced\nin their event handlers.\n\nsub setuptailor {\nmy $wheel = POE::Wheel::FollowTail->new(... incomplete ...);\n$[HEAP]{tailors}{$wheel->ID} = $wheel;\n}\n\nSee the example in \"ErrorEvent\" for a handler that will find this wheel again.\n\ntell"
                    },
                    {
                        "name": "tell",
                        "content": "be useful for saving the position program termination. new()'s \"Seek\" parameter may be used to\nresume watching the file where tell() left off.\n\nsub handleshutdown {\n# Not robust.  Do better in production.\nopen my $save, \">\", \"position.save\" or die $!;\nprint $save $[HEAP]{tailor}->tell(), \"\\n\";\nclose $save;\n}\n\nsub handlestartup {\nopen my $save, \"<\", \"position.save\" or die $!;\nchomp(my $seek = <$save>);\n$[HEAP]{tailor} = POE::Wheel::FollowTail->new(\n...,\nSeek => $seek,\n);\n}\n"
                    }
                ]
            },
            "PUBLIC EVENTS": {
                "content": "POE::Wheel::FollowTail emits a small number of events.\n",
                "subsections": [
                    {
                        "name": "IdleEvent",
                        "content": "\"IdleEvent\" specifies the name of an event to be fired when POE::Wheel::FollowTail doesn't\ndetect activity on the watched file.\n\n$[ARG0] contains the ID of the POE::Wheel::FollowTail object that fired the event.\n"
                    },
                    {
                        "name": "InputEvent",
                        "content": "\"InputEvent\" sets the name of the event to emit when new data arrives into the tailed file. The\nevent will be accompanied by two parameters:\n\n$[ARG0] contains the data that was read from the file, after being parsed by the current\n\"Filter\".\n\n$[ARG1] contains the wheel's ID, which may be used as a key into a data structure tracking\nmultiple wheels. No assumption should be made about the nature or format of this ID, as it may\nchange at any time. Therefore, track your wheels in a hash.\n\nSee the \"SYNOPSIS\" for an example.\n"
                    },
                    {
                        "name": "ResetEvent",
                        "content": "\"ResetEvent\" names the event to be emitted whenever the wheel detects that the followed file has\nbeen reset. It's only available when watching files by name, as POE::Wheel::FollowTail must\nreopen the file after it has been reset.\n\n\"ResetEvent\" comes with only one parameter, $[ARG0], which contains the wheel's ID. See\n\"InputEvent\" for some notes about what may be done with wheel IDs.\n\nSee the \"SYNOPSIS\" for an example.\n"
                    },
                    {
                        "name": "ErrorEvent",
                        "content": "\"ErrorEvent\" names the event emitted when POE::Wheel::FollowTail encounters a problem. Every\n\"ErrorEvent\" comes with four parameters that describe the error and its situation:\n\n$[ARG0] describes the operation that failed. This is usually \"read\", since\nPOE::Wheel::FollowTail spends most of its time reading from a file.\n\n$[ARG1] and $[ARG2] contain the numeric and stringified values of $!, respectively. They will\nnever contain EAGAIN (or its local equivalent) since POE::Wheel::FollowTail handles that error\nitself.\n\n$[ARG3] contains the wheel's ID, which has been discussed in \"InputEvent\".\n\nThis error handler logs a message to STDERR and then shuts down the wheel. It assumes that the\nsession is watching multiple files.\n\nsub handletailerror {\nmy ($operation, $errnum, $errstr, $wheelid) = @[ARG0..ARG3];\nwarn \"Wheel $wheelid: $operation error $errnum: $errstr\\n\";\ndelete $[HEAP]{tailors}{$wheelid};\n}\n"
                    }
                ]
            },
            "SEE ALSO": {
                "content": "POE::Wheel describes the basic operations of all wheels in more depth. You need to know this.\n\nThe SEE ALSO section in POE contains a table of contents covering the entire POE distribution.\n",
                "subsections": []
            },
            "BUGS": {
                "content": "This wheel can't tail pipes and consoles on some operating systems.\n\nPOE::Wheel::FollowTail generally reads ahead of the data it returns, so the tell() position may\nbe later in the file than the data an application has already received.\n\nAUTHORS & COPYRIGHTS\nPlease see POE for more information about authors and contributors.\n",
                "subsections": []
            }
        }
    }
}