[ViewVC] Annotation of: cvs/File-Rdiff/README

NAME
    File::Rdiff -- generate remote signatures and patch files using librsync

SYNOPSIS
     use File::Rdiff

DESCRIPTION
    A more-or-less direct interface to librsync (<http://rproxy.samba.org>).

    For usage examples (better than this very sparse documentation), see the
    two example scripts rdiff1 and rdiff2 that came with the distribution.

    LIBRSYNC_VERSION
        A constant describing the version of the rsync library used in this
        module. My version claimed to be "0.9.5 librsync" when I wrote this
        document ;)

    $oldlevel = trace_level [$newlevel]
        Return the current tracelevel and optionally set a new one.

    $oldcb = trace_to [$newcb]
        Return the current trace callback and optionally set a new one. The
        callback will be called with the log level as the first argument and
        the log message as the second one.

        Calling "trace_to" with "undef" will restore the default handler
        (which currently prints the message to standard error).

    supports_trace
        Returns wether debugging traces are supported in this version of the
        library.

    $msg = strerror $rcode
        Returns a string representation of the given error code. You usually
        just "exit(1)" or something when a function/method fails, as all
        (most?) librsync functions log the error properly, so there is
        rarely a need to call this function.

    $md4 = md4_file $fh
    sig_file $old_fh, $sig_fh[, $block_len[, $strong_len]]
    $sig = loadsig_file $fh
    delta_file $signature, $new_fh, $delta_fh
    patch_file $base_fh, $delta_fh, $new_fh

  The File::Rdiff::Job class
  The File::Rdiff::Buffers class
    This class contains the input and output buffers for the non-blocking
    interface. It is slightly unusual in that it allows direct manipulation
    of (some) of it's internal variables.

    new File::Rdiff::Buffers [$outsize]
        Creates and initializes a new buffers structure. $outsize specifies
        the maximum number of bytes to be read into the output scalar until
        it is considered full. The default is 64k.

    $buffers->in($in)
        Set the next block of input to consume. Data will be read from this
        scalar (no copy will be made!) until all bytes have been consumed or
        a new input scalar is set.

    $out = $buffers->out
        Return the current output data and create a new buffer. Returns
        "undef" if no data has been accumulated.

    $buffers->eof
        Set the eof flag to true. This indicates that no data is following
        the current input scalar.

    $buffers->avail_in
        Returns the numer of bytes still available for input. If there are
        no input bytes available but the eof flag is set, returns -1 (to
        make boolean tests easy to check wether to supply more data easier).

    $buffers->avail_out
        Returns the number of bytes still available in the output buffer.

    $buffers->size
        The number of bytes that have been accumulated in the current buffer
        so far.

  The File::Rdiff::Job class
    It is possible to have multiple jobs running at the same time. The idea
    is to create job objects and then drive them incrementally with input or
    output data until all date has been processed.

    new_sig File::Rdiff::Job [$new_block_len[, $strong_sum_len]]
        Create a job that converts a base stream into a signature stream
        (i.e. creates signatures).

    new_loadsig File::Rdiff::Job
        Create a job that converts the input stream into a in-memory
        File::Rdiff::Signature object. The signature object can be fetched
        anytime with the "signature"-method.

    new_delta File::Rdiff::Job $signature
        Creates a job that creates (outputs) a delta between the input
        stream (the newer file) and the file represented by the given
        signature.

    new_patch File::Rdiff::Job $callback_or_filehandle
        Creates a job that patches a file according to the input stream (a
        delta stream). The single argument is used to read the base file
        contents. If it is a filehandle, it must be a seekable handle to the
        base file.

        If it is a coderef, it will be called whenever base file data must
        be read. Two arguments will be passed: the file offset and the
        length. The callback should eithe return the data read (must be a
        string, not a number!) or an error code.

    $job->iter($buffers)
        Do as much work as possible given the input and/or output data in
        the File::Rdiff::Buffers structure and return either "DONE" when the
        job is finished, "BLOCKED" if there aren't enough bytes available in
        the input or output buffers (in which case you should deplete the
        output buffer and/or fill the input buffer and loop), or some error
        code indicating that the operation failed.

    $job->signature
        Only valid for "new_loadsig", so look there.

SEE ALSO
    File::Rsync, rdiff1 (usage example using simple file API), rdiff2
    (example using nonblocking API).

BUGS
    - not well-tested so far.

    - low memory will result in segfaults rather than croaks.

    - no access to statistics yet

    - documentation leaves much to be deserved.

AUTHOR
     Marc Lehmann <schmorp@schmorp.de>
     http://home.schmorp.de/

Revision:	1.1
Committed:	Tue Mar 8 20:18:52 2005 UTC (21 years, 6 months ago) by root
Branch:	MAIN
CVS Tags:	HEAD
Log Message:	* empty log message *
#	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