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 |
|