| 1 |
=head1 NAME |
| 2 |
|
| 3 |
File::Rdiff |
| 4 |
|
| 5 |
=head1 SYNOPSIS |
| 6 |
|
| 7 |
use File::Rdiff |
| 8 |
|
| 9 |
=head1 DESCRIPTION |
| 10 |
|
| 11 |
A more-or-less direct interface to librsync (L<http://rproxy.samba.org>). |
| 12 |
|
| 13 |
For usage examples (better than this very sparse documentation), see the |
| 14 |
two example scripts rdiff1 and rdiff2 that came with the distribution. |
| 15 |
|
| 16 |
=over 4 |
| 17 |
|
| 18 |
=cut |
| 19 |
|
| 20 |
package File::Rdiff; |
| 21 |
|
| 22 |
require DynaLoader; |
| 23 |
require Exporter; |
| 24 |
|
| 25 |
$VERSION = 0.01; |
| 26 |
@ISA = qw/DynaLoader Exporter/; |
| 27 |
|
| 28 |
bootstrap File::Rdiff $VERSION; |
| 29 |
|
| 30 |
{ |
| 31 |
my @loglevels = qw(LOG_EMERG LOG_ALERT LOG_CRIT LOG_ERR LOG_WARNING LOG_NOTICE LOG_INFO LOG_DEBUG); |
| 32 |
my @result = qw(DONE BLOCKED RUNNING TEST_SKIPPED IO_ERROR SYNTAX_ERROR MEM_ERROR INPUT_ENDED BAD_MAGIC UNIMPLEMENTED CORRUPT INTERNAL_ERROR PARAM_ERROR); |
| 33 |
|
| 34 |
%EXPORT_TAGS = ( |
| 35 |
loglevels => [@loglevels], |
| 36 |
trace => [@loglevels, qw(trace_level trace_to)], |
| 37 |
result => [@result], |
| 38 |
error => [@result, qw(strerror)], |
| 39 |
file => [@result, qw(md4_file sig_file loadsig_file delta_file patch_file)], |
| 40 |
nonblocking => [@result], |
| 41 |
); |
| 42 |
|
| 43 |
my %export_ok; |
| 44 |
@export_ok{map @$_, values %EXPORT_TAGS} = (); |
| 45 |
@EXPORT_OK = keys %export_ok; |
| 46 |
} |
| 47 |
|
| 48 |
=item LIBRSYNC_VERSION |
| 49 |
|
| 50 |
A constant describing the version of the rsync library used in this |
| 51 |
module. My version claimed to be "0.9.5 librsync" when I wrote this |
| 52 |
document ;) |
| 53 |
|
| 54 |
=item $oldlevel = trace_level [$newlevel] |
| 55 |
|
| 56 |
Return the current tracelevel and optionally set a new one. |
| 57 |
|
| 58 |
=item $oldcb = trace_to [$newcb] |
| 59 |
|
| 60 |
Return the current trace callback and optionally set a new one. The callback will be |
| 61 |
called with the log level as the first argument and the log message as the second one. |
| 62 |
|
| 63 |
Calling C<trace_to> with C<undef> will restore the default handler (which |
| 64 |
currently prints the message to standard error). |
| 65 |
|
| 66 |
=item supports_trace |
| 67 |
|
| 68 |
Returns wether debugging traces are supported in this version of the library. |
| 69 |
|
| 70 |
=item $msg = strerror $rcode |
| 71 |
|
| 72 |
Returns a string representation of the given error code. You usually |
| 73 |
just "exit(1)" or something when a function/method fails, as all (most?) |
| 74 |
librsync functions log the error properly, so there is rarely a need to |
| 75 |
call this function. |
| 76 |
|
| 77 |
=item $md4 = md4_file $fh |
| 78 |
|
| 79 |
=item sig_file $old_fh, $sig_fh[, $block_len[, $strong_len]] |
| 80 |
|
| 81 |
=item $sig = loadsig_file $fh |
| 82 |
|
| 83 |
=item delta_file $signature, $new_fh, $delta_fh |
| 84 |
|
| 85 |
=item patch_file $base_fh, $delta_fh, $new_fh |
| 86 |
|
| 87 |
=back |
| 88 |
|
| 89 |
=head2 The File::Rdiff::Job class |
| 90 |
|
| 91 |
=head2 The File::Rdiff::Buffers class |
| 92 |
|
| 93 |
This class contains the input and output buffers for the non-blocking interface. It is slightly unusual |
| 94 |
in that it allows direct manipulation of (some) of it's internal variables. |
| 95 |
|
| 96 |
=over 4 |
| 97 |
|
| 98 |
=item new File::Rdiff::Buffers [$outsize] |
| 99 |
|
| 100 |
Creates and initializes a new buffers structure. C<$outsize> specifies |
| 101 |
the maximum number of bytes to be read into the output scalar until it is |
| 102 |
considered full. The default is 64k. |
| 103 |
|
| 104 |
=item $buffers->in($in) |
| 105 |
|
| 106 |
Set the next block of input to consume. Data will be read from this scalar |
| 107 |
(no copy will be made!) until all bytes have been consumed or a new input |
| 108 |
scalar is set. |
| 109 |
|
| 110 |
=item $out = $buffers->out |
| 111 |
|
| 112 |
Return the current output data and create a new buffer. Returns C<undef> if no data has been accumulated. |
| 113 |
|
| 114 |
=item $buffers->eof |
| 115 |
|
| 116 |
Set the eof flag to true. This indicates that no data is following the current input scalar. |
| 117 |
|
| 118 |
=item $buffers->avail_in |
| 119 |
|
| 120 |
Returns the numer of bytes still available for input. |
| 121 |
|
| 122 |
=item $buffers->avail_out |
| 123 |
|
| 124 |
Returns the number of bytes still available in the output buffer. |
| 125 |
|
| 126 |
=item $buffers->size |
| 127 |
|
| 128 |
The number of bytes that have been accumulated in the current buffer so far. |
| 129 |
|
| 130 |
=back |
| 131 |
|
| 132 |
=head2 The File::Rdiff::Job class |
| 133 |
|
| 134 |
=over 4 |
| 135 |
|
| 136 |
=back |
| 137 |
|
| 138 |
=head1 SEE ALSO |
| 139 |
|
| 140 |
L<File::Rsync>, L<rdiff1> (usage example using simple file API), L<rdiff2> (example using nonblocking API). |
| 141 |
|
| 142 |
=head1 BUGS |
| 143 |
|
| 144 |
- not well-tested so far. |
| 145 |
|
| 146 |
- low memory will result in segfaults rather than croaks. |
| 147 |
|
| 148 |
- no access to statistics yet |
| 149 |
|
| 150 |
- documentation leaves much to be deserved. |
| 151 |
|
| 152 |
=head1 AUTHOR |
| 153 |
|
| 154 |
Marc Lehmann <pcg@goof.com> |
| 155 |
http://www.goof.com/pcg/marc/ |
| 156 |
|
| 157 |
=cut |
| 158 |
|
| 159 |
1; |
| 160 |
|
