| 1 |
NAME |
| 2 |
File::Rdiff -- generate remote signatures and patch files using librsync |
| 3 |
|
| 4 |
SYNOPSIS |
| 5 |
use File::Rdiff |
| 6 |
|
| 7 |
DESCRIPTION |
| 8 |
A more-or-less direct interface to librsync (<http://rproxy.samba.org>). |
| 9 |
|
| 10 |
For usage examples (better than this very sparse documentation), see the |
| 11 |
two example scripts rdiff1 and rdiff2 that came with the distribution. |
| 12 |
|
| 13 |
LIBRSYNC_VERSION |
| 14 |
A constant describing the version of the rsync library used in this |
| 15 |
module. My version claimed to be "0.9.5 librsync" when I wrote this |
| 16 |
document ;) |
| 17 |
|
| 18 |
$oldlevel = trace_level [$newlevel] |
| 19 |
Return the current tracelevel and optionally set a new one. |
| 20 |
|
| 21 |
$oldcb = trace_to [$newcb] |
| 22 |
Return the current trace callback and optionally set a new one. The |
| 23 |
callback will be called with the log level as the first argument and |
| 24 |
the log message as the second one. |
| 25 |
|
| 26 |
Calling "trace_to" with "undef" will restore the default handler |
| 27 |
(which currently prints the message to standard error). |
| 28 |
|
| 29 |
supports_trace |
| 30 |
Returns wether debugging traces are supported in this version of the |
| 31 |
library. |
| 32 |
|
| 33 |
$msg = strerror $rcode |
| 34 |
Returns a string representation of the given error code. You usually |
| 35 |
just "exit(1)" or something when a function/method fails, as all |
| 36 |
(most?) librsync functions log the error properly, so there is |
| 37 |
rarely a need to call this function. |
| 38 |
|
| 39 |
$md4 = md4_file $fh |
| 40 |
sig_file $old_fh, $sig_fh[, $block_len[, $strong_len]] |
| 41 |
$sig = loadsig_file $fh |
| 42 |
delta_file $signature, $new_fh, $delta_fh |
| 43 |
patch_file $base_fh, $delta_fh, $new_fh |
| 44 |
|
| 45 |
The File::Rdiff::Job class |
| 46 |
The File::Rdiff::Buffers class |
| 47 |
This class contains the input and output buffers for the non-blocking |
| 48 |
interface. It is slightly unusual in that it allows direct manipulation |
| 49 |
of (some) of it's internal variables. |
| 50 |
|
| 51 |
new File::Rdiff::Buffers [$outsize] |
| 52 |
Creates and initializes a new buffers structure. $outsize specifies |
| 53 |
the maximum number of bytes to be read into the output scalar until |
| 54 |
it is considered full. The default is 64k. |
| 55 |
|
| 56 |
$buffers->in($in) |
| 57 |
Set the next block of input to consume. Data will be read from this |
| 58 |
scalar (no copy will be made!) until all bytes have been consumed or |
| 59 |
a new input scalar is set. |
| 60 |
|
| 61 |
$out = $buffers->out |
| 62 |
Return the current output data and create a new buffer. Returns |
| 63 |
"undef" if no data has been accumulated. |
| 64 |
|
| 65 |
$buffers->eof |
| 66 |
Set the eof flag to true. This indicates that no data is following |
| 67 |
the current input scalar. |
| 68 |
|
| 69 |
$buffers->avail_in |
| 70 |
Returns the numer of bytes still available for input. If there are |
| 71 |
no input bytes available but the eof flag is set, returns -1 (to |
| 72 |
make boolean tests easy to check wether to supply more data easier). |
| 73 |
|
| 74 |
$buffers->avail_out |
| 75 |
Returns the number of bytes still available in the output buffer. |
| 76 |
|
| 77 |
$buffers->size |
| 78 |
The number of bytes that have been accumulated in the current buffer |
| 79 |
so far. |
| 80 |
|
| 81 |
The File::Rdiff::Job class |
| 82 |
It is possible to have multiple jobs running at the same time. The idea |
| 83 |
is to create job objects and then drive them incrementally with input or |
| 84 |
output data until all date has been processed. |
| 85 |
|
| 86 |
new_sig File::Rdiff::Job [$new_block_len[, $strong_sum_len]] |
| 87 |
Create a job that converts a base stream into a signature stream |
| 88 |
(i.e. creates signatures). |
| 89 |
|
| 90 |
new_loadsig File::Rdiff::Job |
| 91 |
Create a job that converts the input stream into a in-memory |
| 92 |
File::Rdiff::Signature object. The signature object can be fetched |
| 93 |
anytime with the "signature"-method. |
| 94 |
|
| 95 |
new_delta File::Rdiff::Job $signature |
| 96 |
Creates a job that creates (outputs) a delta between the input |
| 97 |
stream (the newer file) and the file represented by the given |
| 98 |
signature. |
| 99 |
|
| 100 |
new_patch File::Rdiff::Job $callback_or_filehandle |
| 101 |
Creates a job that patches a file according to the input stream (a |
| 102 |
delta stream). The single argument is used to read the base file |
| 103 |
contents. If it is a filehandle, it must be a seekable handle to the |
| 104 |
base file. |
| 105 |
|
| 106 |
If it is a coderef, it will be called whenever base file data must |
| 107 |
be read. Two arguments will be passed: the file offset and the |
| 108 |
length. The callback should eithe return the data read (must be a |
| 109 |
string, not a number!) or an error code. |
| 110 |
|
| 111 |
$job->iter($buffers) |
| 112 |
Do as much work as possible given the input and/or output data in |
| 113 |
the File::Rdiff::Buffers structure and return either "DONE" when the |
| 114 |
job is finished, "BLOCKED" if there aren't enough bytes available in |
| 115 |
the input or output buffers (in which case you should deplete the |
| 116 |
output buffer and/or fill the input buffer and loop), or some error |
| 117 |
code indicating that the operation failed. |
| 118 |
|
| 119 |
$job->signature |
| 120 |
Only valid for "new_loadsig", so look there. |
| 121 |
|
| 122 |
SEE ALSO |
| 123 |
File::Rsync, rdiff1 (usage example using simple file API), rdiff2 |
| 124 |
(example using nonblocking API). |
| 125 |
|
| 126 |
BUGS |
| 127 |
- not well-tested so far. |
| 128 |
|
| 129 |
- low memory will result in segfaults rather than croaks. |
| 130 |
|
| 131 |
- no access to statistics yet |
| 132 |
|
| 133 |
- documentation leaves much to be deserved. |
| 134 |
|
| 135 |
AUTHOR |
| 136 |
Marc Lehmann <schmorp@schmorp.de> |
| 137 |
http://home.schmorp.de/ |
| 138 |
|
