# perldoc > POE::Wheel::FollowTail

---
type: CommandReference
command: POE::Wheel::FollowTail
mode: perldoc
section: 3pm
source: perldoc
---

## Quick Reference

- `POE::Wheel::FollowTail->new( Filename => $path, InputEvent => $event, ... )` — create a wheel to tail a file
- `$wheel->event( ResetEvent => undef )` — disable events
- `$wheel->ID()` — return unique wheel ID
- `$wheel->tell()` — return current file position
- `POE::Wheel::FollowTail->new( Handle => $fh, InputEvent => $event )` — tail an already-open file handle
- `$poe_kernel->run()` — start POE loop (after creating wheel)

## Name

`POE::Wheel::FollowTail` — follow the tail of an ever-growing file

## Synopsis

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]\n";
    },
    got_log_rollover => sub {
      print "Log rolled over.\n";
    },
  }
);

POE::Kernel->run();
exit;
## Options

### Constructor Parameters

- `Driver` — optional file driver; defaults to `POE::Driver::SysRW`
- `Filter` — optional data parser; defaults to `POE::Filter::Line` (newline-separated text)
- `PollInterval` — seconds between polls (default 1); increase for infrequently updated files
- `Seek` — seek to a specific position before reading: positive = from start, negative = backward from end, 0 = beginning. Without it, defaults to 4KB back from end.
- `SeekBack` — inverse of `Seek`; positive = backward from end, negative = forward from start, 0 = end. Mutually exclusive with `Seek`.
- `Handle` — an already-opened filehandle; cannot follow log resets. Mutually exclusive with `Filename`.
- `Filename` — path to file; watches for file creation and reopens on reset. Mutually exclusive with `Handle`.
- `IdleEvent` — event name fired when no activity detected (added in POE 1.362)
- `InputEvent` — **required**; event name for new data arrival
- `ResetEvent` — optional; event name fired on file rollover/reset
- `ErrorEvent` — optional; event name for errors

### Methods

- `event( EventName => $event, ... )` — change events after construction; pass `undef` to disable
- `ID()` — returns the wheel's unique ID (useful for hash storage)
- `tell()` — returns current file position; can be saved and restored via `Seek`

## Examples

### Basic usage (see Synopsis)

### Change events at runtime

perl
sub some_event_handler {
  $_[HEAP]{tailor}->event( ResetEvent => undef );
}
### Save and restore position across restarts

perl
sub handle_shutdown {
  open my $save, ">", "position.save" or die $!;
  print $save $_[HEAP]{tailor}->tell(), "\n";
  close $save;
}

sub handle_startup {
  open my $save, "<", "position.save" or die $!;
  chomp(my $seek = <$save>);
  $_[HEAP]{tailor} = POE::Wheel::FollowTail->new(
    ...,
    Seek => $seek,
  );
}
### Error event handler (shuts down wheel on error)

perl
sub handle_tail_error {
  my ($operation, $errnum, $errstr, $wheel_id) = @_[ARG0..ARG3];
  warn "Wheel $wheel_id: $operation error $errnum: $errstr\n";
  delete $_[HEAP]{tailors}{$wheel_id};
}
## See Also

- [POE::Wheel](http://localhost/phpMan.php/perldoc/POE%3A%3AWheel) — base wheel operations
- [POE::Filter::Line](http://localhost/phpMan.php/perldoc/POE%3A%3AFilter%3A%3ALine) — default filter for line-based text
- [POE::Driver::SysRW](http://localhost/phpMan.php/perldoc/POE%3A%3ADriver%3A%3ASysRW) — default file driver
- [POE](http://localhost/phpMan.php/perldoc/POE) — full distribution table of contents

## Exit Codes

Not applicable.