1 |
root |
1.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 |
|
|
|