| Current File : //usr/local/share/man/man3/POE::Wheel::FollowTail.3pm |
.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" 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" ''
. ds C`
. ds C'
'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 >0, 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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "POE::Wheel::FollowTail 3"
.TH POE::Wheel::FollowTail 3 "2022-03-23" "perl v5.26.3" "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"
POE::Wheel::FollowTail \- follow the tail of an ever\-growing file
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #!perl
\&
\& use POE qw(Wheel::FollowTail);
\&
\& POE::Session\->create(
\& inline_states => {
\& _start => sub {
\& $_[HEAP]{tailor} = POE::Wheel::FollowTail\->new(
\& Filename => "/var/log/system.log",
\& InputEvent => "got_log_line",
\& ResetEvent => "got_log_rollover",
\& );
\& },
\& got_log_line => sub {
\& print "Log: $_[ARG0]\en";
\& },
\& got_log_rollover => sub {
\& print "Log rolled over.\en";
\& },
\& }
\& );
\&
\& POE::Kernel\->run();
\& exit;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
POE::Wheel::FollowTail objects watch for new data at the end of a file
and generate new events when things happen to the file. Its \f(CW\*(C`Filter\*(C'\fR
parameter defines how to parse data from the file. Each new item is sent
to the creator's session as an \f(CW\*(C`InputEvent\*(C'\fR event. Log rotation will
trigger a \f(CW\*(C`ResetEvent\*(C'\fR.
.PP
POE::Wheel::FollowTail only reads from a file, so it doesn't implement
a \fBput()\fR method.
.SH "PUBLIC METHODS"
.IX Header "PUBLIC METHODS"
.SS "new"
.IX Subsection "new"
\&\fBnew()\fR returns a new POE::Wheel::FollowTail object. As long as this
object exists, it will generate events when the corresponding file's
status changes.
.PP
\&\fBnew()\fR accepts a small set of named parameters:
.PP
\fIDriver\fR
.IX Subsection "Driver"
.PP
The optional \f(CW\*(C`Driver\*(C'\fR parameter specifies which driver to use when
reading from the tailed file. If omitted, POE::Wheel::FollowTail will
use POE::Driver::SysRW. This is almost always the right thing to do.
.PP
\fIFilter\fR
.IX Subsection "Filter"
.PP
\&\f(CW\*(C`Filter\*(C'\fR is an optional constructor parameter that specifies how to
parse data from the followed file. By default, POE::Wheel::FollowTail
will use POE::Filter::Line to parse files as plain, newline-separated
text.
.PP
.Vb 5
\& $_[HEAP]{tailor} = POE::Wheel::FollowTail\->new(
\& Filename => "/var/log/snort/alert",
\& Filter => POE::Filter::Snort\->new(),
\& InputEvent => "got_snort_alert",
\& );
.Ve
.PP
\fIPollInterval\fR
.IX Subsection "PollInterval"
.PP
POE::Wheel::FollowTail needs to periodically check for new data on the
followed file. \f(CW\*(C`PollInterval\*(C'\fR specifies the number of seconds to
wait between checks. Applications that need to poll once per second
may omit \f(CW\*(C`PollInterval\*(C'\fR, as it defaults to 1.
.PP
Longer poll intervals may be used to reduce the polling overhead for
infrequently updated files.
.PP
.Vb 4
\& $_[HEAP]{tailor} = POE::Wheel::FollowTail\->new(
\& ...,
\& PollInterval => 10,
\& );
.Ve
.PP
\fISeek\fR
.IX Subsection "Seek"
.PP
If specified, \f(CW\*(C`Seek\*(C'\fR instructs POE::Wheel::FollowTail to seek to a
specific spot in the tailed file before beginning to read from it. A
positive \f(CW\*(C`Seek\*(C'\fR value is interpreted as the number of octets to seek
from the start of the file. Negative \f(CW\*(C`Seek\*(C'\fR will, like negative
array indices, seek backwards from the end of the file. Zero \f(CW\*(C`Seek\*(C'\fR
starts reading from the beginning of the file.
.PP
Be careful when using \f(CW\*(C`Seek\*(C'\fR, as it's quite easy to seek into the
middle of a record. When in doubt, and when beginning at the end of
the file, omit \f(CW\*(C`Seek\*(C'\fR entirely. POE::Wheel::FollowTail will seek
4 kilobytes back from the end of the file, then parse and discard all
records unto \s-1EOF.\s0 As long as the file's records are smaller than 4
kilobytes, this will guarantee that the first record returned will be
complete.
.PP
\&\f(CW\*(C`Seek\*(C'\fR may also be used with the wheel's \fBtell()\fR method to restore the
file position after a program restart. Save the \fBtell()\fR value prior to
exiting, and load and \f(CW\*(C`Seek\*(C'\fR back to it on subsequent start-up.
.PP
\fISeekBack\fR
.IX Subsection "SeekBack"
.PP
\&\f(CW\*(C`SeekBack\*(C'\fR behaves like the inverse of \f(CW\*(C`Seek\*(C'\fR. A positive value
acts like a negative \f(CW\*(C`Seek\*(C'\fR. A negative value acts like a positive
\&\f(CW\*(C`Seek\*(C'\fR. A zero \f(CW\*(C`SeekBack\*(C'\fR instructs POE::Wheel::FollowTail to begin
at the very end of the file.
.PP
\&\f(CW\*(C`Seek\*(C'\fR and \f(CW\*(C`SeekBack\*(C'\fR are mutually exclusive.
.PP
See \*(L"Seek\*(R" for caveats, techniques, and an explanation of the magic
that happens when neither \f(CW\*(C`Seek\*(C'\fR nor \f(CW\*(C`SeekBack\*(C'\fR is specified.
.PP
\fIHandle\fR
.IX Subsection "Handle"
.PP
POE::Wheel::FollowTail may follow a previously opened file \f(CW\*(C`Handle\*(C'\fR.
Unfortunately it cannot follow log resets this way, as it won't be
able to reopen the file once it has been reset. Applications that
must follow resets should use \f(CW\*(C`Filename\*(C'\fR instead.
.PP
\&\f(CW\*(C`Handle\*(C'\fR is still useful for files that will never be reset, or for
devices that require setup outside of POE::Wheel::FollowTail's
purview.
.PP
\&\f(CW\*(C`Handle\*(C'\fR and \f(CW\*(C`Filename\*(C'\fR are mutually exclusive. One of them is
required, however.
.PP
\fIFilename\fR
.IX Subsection "Filename"
.PP
Specify the \f(CW\*(C`Filename\*(C'\fR to watch. POE::Wheel::FollowTail will wait
for the file to appear if it doesn't exist. The wheel will also
reopen the file if it disappears, such as when it has been reset or
rolled over. In the case of a reset, POE::Wheel::FollowTail will also
emit a \f(CW\*(C`ResetEvent\*(C'\fR, if one has been requested.
.PP
\&\f(CW\*(C`Handle\*(C'\fR and \f(CW\*(C`Filename\*(C'\fR are mutually exclusive. One of them is
required, however.
.PP
See the \*(L"\s-1SYNOPSIS\*(R"\s0 for an example.
.PP
\fIIdleEvent\fR
.IX Subsection "IdleEvent"
.PP
\&\f(CW\*(C`IdleEvent\*(C'\fR is an optional event. If specified, it will fire
whenever POE::Wheel::FollowTail checks for activity but sees nothing.
It was added in \s-1POE 1.362\s0 as a way to advance certain test programs
without needing to wait conservatively large amounts of time.
.PP
\&\f(CW\*(C`IdleEvent\*(C'\fR is described in \*(L"\s-1PUBLIC EVENTS\*(R"\s0.
.PP
\fIInputEvent\fR
.IX Subsection "InputEvent"
.PP
The \f(CW\*(C`InputEvent\*(C'\fR parameter is required, and it specifies the event to
emit when new data arrives in the watched file. \f(CW\*(C`InputEvent\*(C'\fR is
described in detail in \*(L"\s-1PUBLIC EVENTS\*(R"\s0.
.PP
\fIResetEvent\fR
.IX Subsection "ResetEvent"
.PP
\&\f(CW\*(C`ResetEvent\*(C'\fR is an optional. It specifies the name of the event that
indicates file rollover or reset. Please see \*(L"\s-1PUBLIC EVENTS\*(R"\s0 for
more details.
.PP
\fIErrorEvent\fR
.IX Subsection "ErrorEvent"
.PP
POE::Wheel::FollowTail may emit optional \f(CW\*(C`ErrorEvent\*(C'\fRs whenever it
runs into trouble. The data that comes with this event is explained
in \*(L"\s-1PUBLIC EVENTS\*(R"\s0.
.SS "event"
.IX Subsection "event"
\&\fBevent()\fR allows a session to change the events emitted by a wheel
without destroying and re-creating the object. It accepts one or more
of the events listed in \*(L"\s-1PUBLIC EVENTS\*(R"\s0. Undefined event names
disable those events.
.PP
Stop handling log resets:
.PP
.Vb 3
\& sub some_event_handler {
\& $_[HEAP]{tailor}\->event( ResetEvent => undef );
\& }
.Ve
.PP
The events are described in more detail in \*(L"\s-1PUBLIC EVENTS\*(R"\s0.
.SS "\s-1ID\s0"
.IX Subsection "ID"
The \s-1\fBID\s0()\fR method returns the wheel's unique \s-1ID.\s0 It's useful for
storing the wheel in a hash. All POE::Wheel events should be
accompanied by a wheel \s-1ID,\s0 which allows the wheel to be referenced in
their event handlers.
.PP
.Vb 4
\& sub setup_tailor {
\& my $wheel = POE::Wheel::FollowTail\->new(... incomplete ...);
\& $_[HEAP]{tailors}{$wheel\->ID} = $wheel;
\& }
.Ve
.PP
See the example in \*(L"ErrorEvent\*(R" for a handler that will find this
wheel again.
.SS "tell"
.IX Subsection "tell"
\&\fBtell()\fR returns the current position for the file being watched by
POE::Wheel::FollowTail. It may be useful for saving the position
program termination. \fBnew()\fR's \f(CW\*(C`Seek\*(C'\fR parameter may be used to
resume watching the file where \fBtell()\fR left off.
.PP
.Vb 6
\& sub handle_shutdown {
\& # Not robust. Do better in production.
\& open my $save, ">", "position.save" or die $!;
\& print $save $_[HEAP]{tailor}\->tell(), "\en";
\& close $save;
\& }
\&
\& sub handle_startup {
\& open my $save, "<", "position.save" or die $!;
\& chomp(my $seek = <$save>);
\& $_[HEAP]{tailor} = POE::Wheel::FollowTail\->new(
\& ...,
\& Seek => $seek,
\& );
\& }
.Ve
.SH "PUBLIC EVENTS"
.IX Header "PUBLIC EVENTS"
POE::Wheel::FollowTail emits a small number of events.
.SS "IdleEvent"
.IX Subsection "IdleEvent"
\&\f(CW\*(C`IdleEvent\*(C'\fR specifies the name of an event to be fired when
POE::Wheel::FollowTail doesn't detect activity on the watched file.
.PP
\&\f(CW$_[ARG0]\fR contains the \s-1ID\s0 of the POE::Wheel::FollowTail object that
fired the event.
.SS "InputEvent"
.IX Subsection "InputEvent"
\&\f(CW\*(C`InputEvent\*(C'\fR sets the name of the event to emit when new data arrives
into the tailed file. The event will be accompanied by two
parameters:
.PP
\&\f(CW$_[ARG0]\fR contains the data that was read from the file, after being
parsed by the current \f(CW\*(C`Filter\*(C'\fR.
.PP
\&\f(CW$_[ARG1]\fR contains the wheel's \s-1ID,\s0 which may be used as a key into a
data structure tracking multiple wheels. No assumption should be made
about the nature or format of this \s-1ID,\s0 as it may change at any time.
Therefore, track your wheels in a hash.
.PP
See the \*(L"\s-1SYNOPSIS\*(R"\s0 for an example.
.SS "ResetEvent"
.IX Subsection "ResetEvent"
\&\f(CW\*(C`ResetEvent\*(C'\fR names the event to be emitted whenever the wheel detects
that the followed file has been reset. It's only available when
watching files by name, as POE::Wheel::FollowTail must reopen the file
after it has been reset.
.PP
\&\f(CW\*(C`ResetEvent\*(C'\fR comes with only one parameter, \f(CW$_[ARG0]\fR, which
contains the wheel's \s-1ID.\s0 See \*(L"InputEvent\*(R" for some notes about what
may be done with wheel IDs.
.PP
See the \*(L"\s-1SYNOPSIS\*(R"\s0 for an example.
.SS "ErrorEvent"
.IX Subsection "ErrorEvent"
\&\f(CW\*(C`ErrorEvent\*(C'\fR names the event emitted when POE::Wheel::FollowTail
encounters a problem. Every \f(CW\*(C`ErrorEvent\*(C'\fR comes with four parameters
that describe the error and its situation:
.PP
\&\f(CW$_[ARG0]\fR describes the operation that failed. This is usually
\&\*(L"read\*(R", since POE::Wheel::FollowTail spends most of its time reading
from a file.
.PP
\&\f(CW$_[ARG1]\fR and \f(CW$_[ARG2]\fR contain the numeric and stringified values
of \f(CW$!\fR, respectively. They will never contain \s-1EAGAIN\s0 (or its local
equivalent) since POE::Wheel::FollowTail handles that error itself.
.PP
\&\f(CW$_[ARG3]\fR contains the wheel's \s-1ID,\s0 which has been discussed in
\&\*(L"InputEvent\*(R".
.PP
This error handler logs a message to \s-1STDERR\s0 and then shuts down the
wheel. It assumes that the session is watching multiple files.
.PP
.Vb 5
\& sub handle_tail_error {
\& my ($operation, $errnum, $errstr, $wheel_id) = @_[ARG0..ARG3];
\& warn "Wheel $wheel_id: $operation error $errnum: $errstr\en";
\& delete $_[HEAP]{tailors}{$wheel_id};
\& }
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
POE::Wheel describes the basic operations of all wheels in more
depth. You need to know this.
.PP
The \s-1SEE ALSO\s0 section in \s-1POE\s0 contains a table of contents covering
the entire \s-1POE\s0 distribution.
.SH "BUGS"
.IX Header "BUGS"
This wheel can't tail pipes and consoles on some operating systems.
.PP
POE::Wheel::FollowTail generally reads ahead of the data it returns,
so the \fBtell()\fR position may be later in the file than the data an
application has already received.
.SH "AUTHORS & COPYRIGHTS"
.IX Header "AUTHORS & COPYRIGHTS"
Please see \s-1POE\s0 for more information about authors and contributors.