ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/File-Rdiff/Rdiff.pm
Revision: 1.4
Committed: Wed Jan 12 20:35:42 2005 UTC (19 years, 5 months ago) by root
Branch: MAIN
Changes since 1.3: +1 -1 lines
Log Message:
*** empty log message ***

File Contents

# User Rev Content
1 root 1.1 =head1 NAME
2    
3 root 1.3 File::Rdiff -- generate remote signatures and patch files using librsync
4 root 1.1
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 root 1.2 Returns the numer of bytes still available for input. If there are no
121     input bytes available but the eof flag is set, returns -1 (to make boolean
122     tests easy to check wether to supply more data easier).
123 root 1.1
124     =item $buffers->avail_out
125    
126     Returns the number of bytes still available in the output buffer.
127    
128     =item $buffers->size
129    
130     The number of bytes that have been accumulated in the current buffer so far.
131    
132     =back
133    
134     =head2 The File::Rdiff::Job class
135    
136 root 1.2 It is possible to have multiple jobs running at the same time. The idea
137     is to create job objects and then drive them incrementally with input or
138     output data until all date has been processed.
139    
140 root 1.1 =over 4
141 root 1.2
142     =item new_sig File::Rdiff::Job [$new_block_len[, $strong_sum_len]]
143    
144     Create a job that converts a base stream into a signature stream (i.e. creates signatures).
145    
146     =item new_loadsig File::Rdiff::Job
147    
148     Create a job that converts the input stream into a in-memory
149     File::Rdiff::Signature object. The signature object can be fetched anytime
150     with the C<signature>-method.
151    
152     =item new_delta File::Rdiff::Job $signature
153    
154     Creates a job that creates (outputs) a delta between the input stream (the
155     newer file) and the file represented by the given signature.
156    
157     =item new_patch File::Rdiff::Job $callback_or_filehandle
158    
159     Creates a job that patches a file according to the input stream (a delta
160     stream). The single argument is used to read the base file contents. If it
161     is a filehandle, it must be a seekable handle to the base file.
162    
163     If it is a coderef, it will be called whenever base file data must be
164     read. Two arguments will be passed: the file offset and the length. The
165     callback should eithe return the data read (must be a string, not a
166     number!) or an error code.
167    
168     =item $job->iter($buffers)
169    
170     Do as much work as possible given the input and/or output data in the
171     File::Rdiff::Buffers structure and return either C<DONE> when the job is
172     finished, C<BLOCKED> if there aren't enough bytes available in the input
173     or output buffers (in which case you should deplete the output buffer
174     and/or fill the input buffer and loop), or some error code indicating that
175     the operation failed.
176    
177     =item $job->signature
178    
179     Only valid for C<new_loadsig>, so look there.
180 root 1.1
181     =back
182    
183     =head1 SEE ALSO
184    
185     L<File::Rsync>, L<rdiff1> (usage example using simple file API), L<rdiff2> (example using nonblocking API).
186    
187     =head1 BUGS
188    
189     - not well-tested so far.
190    
191     - low memory will result in segfaults rather than croaks.
192    
193     - no access to statistics yet
194    
195     - documentation leaves much to be deserved.
196    
197     =head1 AUTHOR
198    
199     Marc Lehmann <pcg@goof.com>
200 root 1.4 http://home.schmorp.de/
201 root 1.1
202     =cut
203    
204     1;
205