ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/File-Rdiff/README
Revision: 1.1
Committed: Tue Mar 8 20:18:52 2005 UTC (19 years, 3 months ago) by root
Branch: MAIN
CVS Tags: HEAD
Log Message:
*** empty log message ***

File Contents

# User Rev Content
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