NAME

File::ReplaceBytes - read or replace arbitrary data in files

SYNOPSIS

Warning! These system calls are dangerous!

use File::ReplaceBytes qw(pread pwrite replacebytes);

open my $fh, '+<', $file or die "cannot open $file: $!\n";

# read 16 bytes at offset of 8 bytes into $buf
my $buf;
pread($fh, $buf, 16, 8);

# write these bytes out in various locations to same file
pwrite($fh, $buf);        # at beginning of file
pwrite($fh, $buf, 4);     # write just 4 bytes of $buf
pwrite($fh, $buf, 0, 32); # all of $buf at 32 bytes into file

# these two are equivalent
pwrite($fh, $buf, 0);
pwrite($fh, $buf, length $buf);

replacebytes('somefile', $buf, 42);

DESCRIPTION

This module employs the pread(2) and pwrite(2) system calls to perform highly unsavory operations on files. These calls do not update the filehandle position reported by sysseek($fh,0,1), and will doubtless cause problems if mixed with any sort of buffered I/O. The filehandles used MUST be file-based filehandles, and MUST NOT be in-memory filehandles or sockets...look, I warned you.

EXPORTS

pread

pread(FH,BUF,LENGTH)
pread(FH,BUF,LENGTH,OFFSET)

FH must be a file handle, BUF a scalar, LENGTH how many bytes to read into BUF, and optionally, how far into the filehandle to start reading at. The call may throw an exception (e.g. if FH is undef), or otherwise will return the number of bytes read, or 0 if EOF, or -1 on error. BUF will be tainted under taint mode.

pwrite

pwrite(FH,BUF)
pwrite(FH,BUF,LENGTH)
pwrite(FH,BUF,LENGTH,OFFSET)

FH must be a file handle, BUF a scalar, whose LENGTH will be written, or otherwise a specified LENGTH number of bytes--but not beyond that of BUF, because that would be so very naughty--optionally at the specified OFFSET in bytes. If LENGTH is 0, the contents of BUF will be written. The call may throw an exception if FH is undef. The return value is the number of bytes written, or -1 on error.

replacebytes

replacebytes(FILENAME,BUF)
replacebytes(FILENAME,BUF,OFFSET)

Accepts a filename and scalar buffer, and writes the buffer to the specified offset (zero if not specified) in the said file. Does not use PerlIO like the p* routines do, instead performs a direct open(2) call on the filename.

CAVEATS

Everything mentioned above plus yet more besides.

SECURITY CONSIDERATIONS

This module MUST NOT be used if untrusted user input can influence how the file handles are created, as who knows what the p* system calls will do with whatever fileno value Perl returns for some socket or in-memory data filehandle?

SEE ALSO

dd(1), hexdump(1), pread(2), pwrite(2) and your backups. You have backups, right? Backups are nice.

AUTHOR

Jeremy Mates, <jmates@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2013 by Jeremy Mates

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