---

rsync.h File Reference

Main public interface to librsync. More...

Data Structures
struct	rs_stats
	Performance statistics from a librsync encoding or decoding operation. More...
struct	rs_mdfour
struct	rs_buffers_s
	Stream through which the calling application feeds data to and from the library. More...
Defines
#define	RS_MD4_LENGTH   16
#define	RS_DEFAULT_STRONG_LEN   8
	Default length of strong signatures, in bytes. More...
#define	RS_DEFAULT_BLOCK_LEN   2048
	Default block length, if not determined by any other factors. More...
Typedefs
typedef long	rs_long_t
	A long integer type that can handle the largest file offsets. More...
typedef void	rs_trace_fn_t (int level, char const *msg)
	Callback to write out log messages. More...
typedef struct rs_stats	rs_stats_t
	Performance statistics from a librsync encoding or decoding operation. More...
typedef struct rs_mdfour	rs_mdfour_t
	MD4 message-digest accumulator. More...
typedef unsigned int	rs_weak_sum_t
typedef unsigned char	rs_strong_sum_t [RS_MD4_LENGTH]
typedef struct rs_signature	rs_signature_t
typedef struct rs_buffers_s	rs_buffers_t
	Stream through which the calling application feeds data to and from the library. More...
typedef struct rs_job	rs_job_t
	Job of work to be done. More...
typedef enum rs_work_options	rs_work_options
	Bitmask values that may be passed to the options parameter of rs_work(). More...
typedef rs_result	rs_driven_cb (rs_job_t *job, rs_buffers_t *buf, void *opaque)
typedef rs_result	rs_copy_cb (void *opaque, off_t pos, size_t *len, void **buf)
	Callback used to retrieve parts of the basis file. More...
Enumerations
enum	rs_loglevel {   RS_LOG_EMERG = 0, RS_LOG_ALERT = 1, RS_LOG_CRIT = 2, RS_LOG_ERR = 3,   RS_LOG_WARNING = 4, RS_LOG_NOTICE = 5, RS_LOG_INFO = 6, RS_LOG_DEBUG = 7 }
	Log severity levels. More...
enum	rs_result {   RS_DONE = 0, RS_BLOCKED = 1, RS_RUNNING = 2, RS_TEST_SKIPPED = 77,   RS_IO_ERROR = 100, RS_SYNTAX_ERROR = 101, RS_MEM_ERROR = 102, RS_INPUT_ENDED = 103,   RS_BAD_MAGIC = 104, RS_UNIMPLEMENTED = 105, RS_CORRUPT = 106, RS_INTERNAL_ERROR = 107,   RS_PARAM_ERROR = 108 }
	Return codes from nonblocking rsync operations. More...
enum	rs_work_options { RS_END = 0x01 }
	Bitmask values that may be passed to the options parameter of rs_work(). More...
Functions
void	rs_trace_set_level (rs_loglevel level)
	Set the least important message severity that will be output. More...
void	rs_trace_to (rs_trace_fn_t *)
	Set trace callback. More...
void	rs_trace_stderr (int level, char const *msg)
	Default trace callback that writes to stderr. More...
int	rs_supports_trace (void)
	Check whether the library was compiled with debugging trace suport. More...
void	rs_hexify (char *to_buf, void const *from_buf, int from_len)
	Convert FROM_LEN bytes at FROM_BUF into a hex representation in TO_BUF, which must be twice as long plus one byte for the null terminator. More...
size_t	rs_unbase64 (char *s)
	Decode a base64 buffer in place. More...
void	rs_base64 (unsigned char const *buf, int n, char *out)
	Encode a buffer as base64. More...
char const*	rs_strerror (rs_result r)
	Return an English description of a rs_result value. More...
void	rs_mdfour (unsigned char *out, void const *in, int n)
void	rs_mdfour_begin (rs_mdfour_t *md)
void	rs_mdfour_update (rs_mdfour_t *md, void const *, size_t n)
void	rs_mdfour_result (rs_mdfour_t *md, unsigned char *out)
char*	rs_format_stats (rs_stats_t const *, char *, size_t)
	Return a human-readable representation of statistics. More...
int	rs_log_stats (rs_stats_t const *stats)
void	rs_free_sumset (rs_signature_t *)
	Deep deallocation of checksums. More...
void	rs_sumset_dump (rs_signature_t const *)
	Dump signatures to the log. More...
rs_result	rs_job_iter (rs_job_t *, rs_buffers_t *)
	Run a rs_job_t state machine until it blocks (RS_BLOCKED), returns an error, or completes (RS_COMPLETE). More...
rs_result	rs_job_drive (rs_job_t *job, rs_buffers_t *buf, rs_driven_cb in_cb, void *in_opaque, rs_driven_cb out_cb, void *out_opaque)
	Actively process a job, by making callbacks to fill and empty the buffers until the job is done. More...
rs_result	rs_job_free (rs_job_t *)
int	rs_accum_value (rs_job_t *, char *sum, size_t sum_len)
rs_job_t*	rs_sig_begin (size_t new_block_len, size_t strong_sum_len)
	Set up a new encoding job. More...
rs_job_t*	rs_delta_begin (rs_signature_t *)
	Prepare to compute a streaming delta. More...
rs_job_t*	rs_loadsig_begin (rs_signature_t **)
	Read a signature from a file into an rs_signature_t structure in memory. More...
rs_job_t*	rs_patch_begin (rs_copy_cb *, void *copy_arg)
	Apply a delta to a basis to recreate the new file. More...
rs_result	rs_build_hash_table (rs_signature_t *sums)
void	rs_mdfour_file (FILE *in_file, char *result)
	Calculate the MD4 sum of a file. More...
rs_result	rs_sig_file (FILE *old_file, FILE *sig_file, size_t, size_t)
	Generate the signature of a basis file, and write it out to another. More...
rs_result	rs_loadsig_file (FILE *sig_file, rs_signature_t **sumset)
	Load signatures from a signature file into memory. More...
rs_result	rs_file_copy_cb (void *arg, off_t pos, size_t *len, void **buf)
	Default copy implementation that retrieves a part of a stdio file. More...
rs_result	rs_delta_file (rs_signature_t *, FILE *new_file, FILE *delta_file, rs_stats_t *)
rs_result	rs_patch_file (FILE *basis_file, FILE *delta_file, FILE *new_file, rs_stats_t *)
Variables
char const	rs_librsync_version [] = (PACKAGE " " VERSION)
	Library version string. More...
char const	rs_licence_string []
int	rs_inbuflen
	Buffer sizes for file IO. More...
int	rs_outbuflen
	Buffer sizes for file IO. More...

---

Detailed Description

Main public interface to librsync.

Author(s):

Martin Pool <mbp@samba.org>

Version:

librsync-0.9.1

Id:

rsync.h,v 1.10 2001/03/18 02:00:08 mbp Exp

See Introduction for an introduction to use of this library.

---

Define Documentation

#define RS_DEFAULT_STRONG_LEN   8

Default length of strong signatures, in bytes. The MD4 checksum is truncated to this size.

#define RS_DEFAULT_BLOCK_LEN   2048

Default block length, if not determined by any other factors.

---

Typedef Documentation

typedef long rs_long_t

A long integer type that can handle the largest file offsets. Perhaps this might have to be configured to be 'long long', 'long', or something else depending on the platform.

typedef void rs_trace_fn_t

Callback to write out log messages. Parameters: level   a syslog level. msg   message to be logged.

typedef struct rs_stats rs_stats_t

Performance statistics from a librsync encoding or decoding operation. See also: rs_format_stats(), rs_log_stats()

struct rs_mdfour rs_mdfour_t

MD4 message-digest accumulator. See also: rs_mdfour(), rs_mdfour_begin(), rs_mdfour_update(), rs_mdfour_result()

typedef struct rs_buffers_s rs_buffers_t

Stream through which the calling application feeds data to and from the library. See also: struct rs_buffers_s , Buffers

typedef struct rs_job rs_job_t

Job of work to be done. Created by functions such as rs_sig_begin(), and then iterated over by rs_job_iter().

typedef enum rs_work_options rs_work_options

Bitmask values that may be passed to the options parameter of rs_work().

typedef rs_result rs_copy_cb

Callback used to retrieve parts of the basis file. Parameters: pos   Position where copying should begin. len   On input, the amount of data that should be retrieved. Updated to show how much is actually available. buf   On input, a buffer of at least *len bytes. May be updated to point to a buffer allocated by the callback if it prefers.

---

Enumeration Type Documentation

enum rs_loglevel

Log severity levels. These are the same as syslog, at least in glibc. See also: rs_trace_set_level() Enumeration values: RS_LOG_EMERG   System is unusable. RS_LOG_ALERT   Action must be taken immediately. RS_LOG_CRIT   Critical conditions. RS_LOG_ERR   Error conditions. RS_LOG_WARNING   Warning conditions. RS_LOG_NOTICE   Normal but significant condition. RS_LOG_INFO   Informational. RS_LOG_DEBUG   Debug-level messages.

enum rs_result

Return codes from nonblocking rsync operations. Enumeration values: RS_DONE   Completed successfully. RS_BLOCKED   Blocked waiting for more data. RS_RUNNING   Not yet finished or blocked. This value should never be returned to the caller. RS_TEST_SKIPPED   Test neither passed or failed. RS_IO_ERROR   Error in file or network IO. RS_SYNTAX_ERROR   Command line syntax error. RS_MEM_ERROR   Out of memory. RS_INPUT_ENDED   End of input file, possibly unexpected. RS_BAD_MAGIC   Bad magic number at start of stream. Probably not a librsync file, or possibly the wrong kind of file or from an incompatible library version. RS_UNIMPLEMENTED   Author is lazy. RS_CORRUPT   Unbelievable value in stream. RS_INTERNAL_ERROR   Probably a library bug. RS_PARAM_ERROR   Bad value passed in to library, probably an application bug.

enum rs_work_options

Bitmask values that may be passed to the options parameter of rs_work(). Enumeration values: RS_END   End of input file; please finish up.

---

Function Documentation

void rs_trace_set_level ( rs_loglevel level )

Set the least important message severity that will be output.

void rs_trace_to ( rs_trace_fn_t * new_impl )

Set trace callback. The callback scheme allows for use within applications that may have their own particular ways of reporting errors: log files for a web server, perhaps, and an error dialog for a browser. Todo: Do we really need such fine-grained control, or just yes/no tracing?

void rs_trace_stderr ( int level, char const * msg )

Default trace callback that writes to stderr. Implements rs_trace_fn_t, and may be passed to rs_trace_to().

int rs_supports_trace ( void )

Check whether the library was compiled with debugging trace suport. If this returns false, then trying to turn trace on will achieve nothing.

void rs_hexify ( char * to_buf, void const * from_buf, int from_len )

Convert FROM_LEN bytes at FROM_BUF into a hex representation in TO_BUF, which must be twice as long plus one byte for the null terminator.

size_t rs_unbase64 ( char * s )

Decode a base64 buffer in place. Returns: the number of binary bytes.

void rs_base64 ( unsigned char const * buf, int n, char * out )

Encode a buffer as base64.

char const* rs_strerror ( rs_result r )

Return an English description of a rs_result value.

char * rs_format_stats ( rs_stats_t const * stats, char * buf, size_t size )

Return a human-readable representation of statistics. The string is truncated if it does not fit. 100 characters should be sufficient space. Parameters: stats   Statistics from an encoding or decoding operation. buf   Buffer to receive result. size   Size of buffer. Returns: buf

void rs_free_sumset ( rs_signature_t * psums )

Deep deallocation of checksums.

void rs_sumset_dump ( rs_signature_t const * sums )

Dump signatures to the log.

rs_result rs_job_iter ( rs_job_t * job, rs_buffers_t * buffers )

Run a rs_job_t state machine until it blocks (RS_BLOCKED), returns an error, or completes (RS_COMPLETE). Returns: The rs_result that caused iteration to stop. Parameters: ending   True if there is no more data after what's in the input buffer. The final block checksum will run across whatever's in there, without trying to accumulate anything else.

rs_result rs_job_drive ( rs_job_t * job, rs_buffers_t * buf, rs_driven_cb in_cb, void * in_opaque, rs_driven_cb out_cb, void * out_opaque )

Actively process a job, by making callbacks to fill and empty the buffers until the job is done.

rs_job_t* rs_sig_begin ( size_t new_block_len, size_t strong_sum_len )

Set up a new encoding job. See also: rs_sig_file()

rs_job_t* rs_delta_begin ( rs_signature_t * sig )

Prepare to compute a streaming delta.

rs_job_t* rs_loadsig_begin ( rs_signature_t ** signature )

Read a signature from a file into an rs_signature_t structure in memory. Once there, it can be used to generate a delta to a newer version of the file. Note: After loading the signatures, you must call rs_build_hash_table() before you can use them.

rs_job_t* rs_patch_begin ( rs_copy_cb * copy_cb, void * copy_arg )

Apply a delta to a basis to recreate the new file. This gives you back a rs_job_t object, which can be cranked by calling rs_job_iter() and updating the stream pointers. When finished, call rs_job_finish() to dispose of it. Parameters: stream   Contains pointers to input and output buffers, to be adjusted by caller on each iteration. copy_cb   Callback used to retrieve content from the basis file. copy_arg   Opaque environment pointer passed through to the callback. Todo: As output is produced, accumulate the MD4 checksum of the output. Then if we find a CHECKSUM command we can check it's contents against the output. Implement COPY commands. See also: rs_patch_file()

void rs_mdfour_file ( FILE * in_file, char * result )

Calculate the MD4 sum of a file. Parameters: result   Binary (not hex) MD4 of the whole contents of the file.

rs_result rs_sig_file ( FILE * old_file, FILE * sig_file, size_t new_block_len, size_t strong_len )

Generate the signature of a basis file, and write it out to another. Parameters: new_block_len   block size for signature generation, in bytes strong_len   truncated length of strong checksums, in bytes See also: rs_sig_begin()

rs_result rs_loadsig_file ( FILE * sig_file, rs_signature_t ** sumset )

Load signatures from a signature file into memory. Return a pointer to the newly allocated structure in SUMSET. See also: rs_readsig_begin()

rs_result rs_file_copy_cb ( void * arg, off_t pos, size_t * len, void ** buf )

Default copy implementation that retrieves a part of a stdio file.

---

Variable Documentation

char const rs_librsync_version[] = (PACKAGE " " VERSION)

Library version string.

int rs_inbuflen

Buffer sizes for file IO.

int rs_outbuflen

Buffer sizes for file IO.

---