perlancar > File-Write-Rotate-0.30 > File::Write::Rotate



Annotate this POD



Open  0
View/Report Bugs
Module Version: 0.30   Source  


File::Write::Rotate - Write to files that archive/rotate themselves


This document describes version 0.30 of File::Write::Rotate (from Perl distribution File-Write-Rotate), released on 2016-06-06.


 use File::Write::Rotate;

 my $fwr = File::Write::Rotate->new(
     dir          => '/var/log',    # required
     prefix       => 'myapp',       # required
     #suffix      => '.log',        # default is ''
     size         => 25*1024*1024,  # default is 10MB, unless period is set
     histories    => 12,            # default is 10
     #buffer_size => 100,           # default is none

 # write, will write to /var/log/myapp.log, automatically rotate old log files
 # to myapp.log.1 when myapp.log reaches 25MB. will keep old log files up to
 # myapp.log.12.
 $fwr->write("This is a line\n");
 $fwr->write("This is", " another line\n");

To compressing old log files:


This is usually done in a separate process, because it potentially takes a long time if the files to compress are large; we are rotating automatically in write() so doing automatic compression too would annoyingly block writer for a potentially long time.


This module can be used to write to file, usually for logging, that can rotate itself. File will be opened in append mode. By default, locking will be done to avoid conflict when there are multiple writers. Rotation can be done by size (after a certain size is reached), by time (daily/monthly/yearly), or both.

I first wrote this module for logging script STDERR output to files (see Tie::Handle::FileWriteRotate).


buffer_size => int

Get or set buffer size. If set to a value larger than 0, then when a write() failed, instead of dying, the message will be stored in an internal buffer first (a regular Perl array). When the number of items in the buffer exceeds this size, then write() will die upon failure. Otherwise, every write() will try to flush the buffer.

Can be used for example when a program runs as superuser/root then temporarily drops privilege to a normal user. During this period, logging can fail because the program cannot lock the lock file or write to the logging directory. Before dropping privilege, the program can set buffer_size to some larger-than-zero value to hold the messages emitted during dropping privilege. The next write() as the superuser/root will succeed and flush the buffer to disk (provided there is no other error condition, of course).

path => str (ro)

Current file's path.

handle => (ro)

Current file handle. You should not use this directly, but use write() instead. This attribute is provided for special circumstances (e.g. in hooks, see example in the hook section).

hook_before_write => code

Will be called by write() before actually writing to filehandle (but after locking is done). Code will be passed ($self, \@msgs, $fh) where @msgs is an array of strings to be written (the contents of buffer, if any, plus arguments passed to write()) and $fh is the filehandle.

hook_before_rotate => code

Will be called by the rotating routine before actually doing rotating. Code will be passed ($self).

This can be used to write a footer to the end of each file, e.g.:

 # hook_before_rotate
 my ($self) = @_;
 my $fh = $self->handle;
 print $fh "Some footer\n";

Since this hook is indirectly called by write(), locking is already done.

hook_after_rotate => code

Will be called by the rotating routine after the rotating process. Code will be passed ($self, \@renamed, \@deleted) where @renamed is array of new filenames that have been renamed, @deleted is array of new filenames that have been deleted.

hook_after_create => code

Will be called by after a new file is created. Code will be passed ($self).

This hook can be used to write a header to each file, e.g.:

 # hook_after_create
 my ($self) = @_;
 my $fh $self->handle;
 print $fh "header\n";

Since this is called indirectly by write(), locking is also already done.

binmode => str


$obj = File::Write::Rotate->new(%args)

Create new object. Known arguments:

lock_file_path => STR

Returns a string representing the complete pathname to the lock file, based on dir and prefix attributes.


Write to file. Will automatically rotate file if period changes or file size exceeds specified limit. When rotating, will only keep a specified number of histories and delete the older ones.

Does not append newline so you'll have to do it yourself.


Compress old rotated files and remove the uncompressed originals. Currently uses IO::Compress::Gzip to do the compression. Extension given to compressed file is .gz.

Will not lock writers, but will create <prefix> PID file to prevent multiple compression processes running and to signal the writers to postpone rotation.

After compression is finished, will remove the PID file, so rotation can be done again on the next write() if necessary.


Why use autorotating file?

Mainly convenience and low maintenance. You no longer need a separate rotator process like the Unix logrotate utility (which when accidentally disabled or misconfigured will cause your logs to stop being rotated and grow indefinitely).

What is the downside of using FWR (and LDFR)?

Mainly (significant) performance overhead. At (almost) every write(), FWR needs to check file sizes and/or dates for rotation. Under default configuration (where lock_mode is write), it also performs locking on each write() to make it safe to use with multiple processes. Below is a casual benchmark to give a sense of the overhead, tested on my Core i5-2400 3.1GHz desktop:

Writing lines in the size of ~ 200 bytes, raw writing to disk (SSD) has the speed of around 3.4mil/s, while using FWR it goes down to around ~13k/s. Using lock_mode none or exclusive, the speed is ~52k/s.

However, this is not something you'll notice or need to worry about unless you're writing near that speed.

If you need more speed, you can try setting rotate_probability which will cause FWR to only check for rotation probabilistically, e.g. if you set this to 0.1 then checks will only be done in about 1 of 10 writes. This can significantly reduce the overhead and increase write speed several times (e.g. 5-8 times), but understand that this will make the writes "overflow" a bit, e.g. file sizes will exceed for a bit if you do size-based rotation. More suitable if you only do size-based rotation since it is usually okay to exceed sizes for a bit.


Please visit the project's homepage at


Source repository is at


Please report any bugs or feature requests on the bugtracker website

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.


Log::Dispatch::FileRotate, which inspires this module. Differences between File::Write::Rotate (FWR) and Log::Dispatch::FileRotate (LDFR) are as follows:

There is no significant overhead difference between FWR and LDFR (FWR is slightly faster than LDFR on my testing).

Tie::Handle::FileWriteRotate and Log::Dispatch::FileWriteRotate, which use this module.


perlancar <>


This software is copyright (c) 2016 by

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

syntax highlighting: