NAME

Linux::PipeMagic - Perl extension to use the zero copy IO syscalls

SYNOPSIS

use Linux::PipeMagic qw/ systee syssplice syssendfile /;
systee($fh_in, $fh_out, $num_bytes, 0);
syssplice($fh_in, $fh_out, $num_bytes, 0);
syssendfile($fh_out, $fh_in, $num_bytes);

DESCRIPTION

Linux::PipeMagic is a Perl XS wrapper around the splice(2), tee(2) and sendfile(2) syscalls. You can use them to efficiently copy data from one file descriptor to another inside the kernel (splice), or to efficiently copy data from one pipe to another (tee).

FUNCTIONS

sysplice($fh_in, $fh_out, $num_bytes, $flags)

Copies $num_bytes from $fh_in to $fh_out. This is roughly equivalent to,

sysread($fh_in, my $buf, $num_bytes);
syswrite($fh_out, $buf);

although the transfer takes place entirely in kernel space.

Returns the number of bytes transferred.

systee($fh_in, $fh_out, $num_bytes, $flags)

Copies $num_bytes from $fh_in to $fh_out. The filehandles must both be of type pipe. This works similarly like syssplice but does not advance the read pointer in $fh_in.

Returns the number of bytes transferred.

syssendfile($fh_out, $fh_in, $num_bytes)

Copies $num_bytes from $fh_in to $fh_out. With current versions of Linux, $fh_in must be a file opened for reading, and $fh_out must be a writable socket. Note the different order of parameters compared to the other functions.

CONSTANTS

  • SPLICE_F_MOVE

  • SPLICE_F_NONBLOCK

  • SPLICE_F_MORE

  • SPLICE_F_GIFT

CAVEATS

Only Linux is supported, on other OSs the calls will fail with ENOSYS and the constants will not be available. tee(2) and splice(2) syscalls only exist on Linux. sendfile(2) is provided by the BSDs, however it takes different parameters to the Linux call.

SEE ALSO

See the Linux manpages for more details on how splice and tee can be used, including the flags.

AUTHOR

Dave Lambley, <dlambley@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2011, 2012, 2022 by Dave Lambley

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.1 or, at your option, any later version of Perl 5 you may have available.