NAME

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

SYNOPSIS

Warning! These system calls are dangerous! Warning!

  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. BUF will be tainted under taint mode. The call may throw an exception (e.g. if FH is undef), or otherwise will return the number of bytes read, or 0 on EOF, or -1 on error. "$!" in perlvar may contain a clue as to why the call errored out; reasons include invalid input (negative offsets) or a failure from pread(2).

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. "$!" in perlvar may contain a clue as to why the call errored out; reasons include invalid input (negative offsets) or a failure from pwrite(2).

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 specified file. Will create the file if it does not exist. Does not use PerlIO like the p* routines do, instead performs a direct open(2) call on the filename. The return value is the number of bytes written, or -1 on error. "$!" in perlvar may contain a clue as to why the call errored out; reasons include invalid input (negative offsets) or a failure from open(2) or pwrite(2).

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

thrig - Jeremy Mates (cpan:JMATES) <jmates at cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2013-2016,2018 by Jeremy Mates

This program is distributed under the (Revised) BSD License: http://www.opensource.org/licenses/BSD-3-Clause