librsync  2.0.1
Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
librsync.h File Reference

Public header for librsync. More...

Go to the source code of this file.

Data Structures

struct  rs_stats
 Performance statistics from a librsync encoding or decoding operation. More...
 
struct  rs_buffers_s
 Description of input and output buffers. More...
 

Macros

#define RS_MAX_STRONG_SUM_LENGTH   32
 
#define RS_DEFAULT_BLOCK_LEN   2048
 Default block length, if not determined by any other factors. More...
 

Typedefs

typedef unsigned char rs_byte_t
 
typedef void rs_trace_fn_t(rs_loglevel level, char const *msg)
 Callback to write out log messages. More...
 
typedef enum rs_result rs_result
 
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_MAX_STRONG_SUM_LENGTH]
 
typedef struct rs_signature rs_signature_t
 
typedef struct rs_buffers_s rs_buffers_t
 
typedef struct rs_job rs_job_t
 Job of work to be done. More...
 
typedef rs_result rs_driven_cb(rs_job_t *job, rs_buffers_t *buf, void *opaque)
 Type of application-supplied function for rs_job_drive(). More...
 
typedef rs_result rs_copy_cb(void *opaque, rs_long_t pos, size_t *len, void **buf)
 Callback used to retrieve parts of the basis file. More...
 

Enumerations

enum  rs_magic_number { RS_DELTA_MAGIC = 0x72730236, RS_MD4_SIG_MAGIC = 0x72730136, RS_BLAKE2_SIG_MAGIC = 0x72730137 }
 A uint32 magic number, emitted in bigendian/network order at the start of librsync files. More...
 
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...
 

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 (rs_loglevel 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. 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, size_t)
 
void rs_mdfour_begin (rs_mdfour_t *md)
 
void rs_mdfour_update (rs_mdfour_t *md, void const *in_void, size_t n)
 Feed some data into the MD4 accumulator. More...
 
void rs_mdfour_result (rs_mdfour_t *md, unsigned char *out)
 
char * rs_format_stats (rs_stats_t const *stats, char *buf, size_t size)
 Return a human-readable representation of statistics. More...
 
int rs_log_stats (rs_stats_t const *stats)
 Write statistics into the current log as text. More...
 
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 *job, rs_buffers_t *buffers)
 Run a rs_job state machine until it blocks (RS_BLOCKED), returns an error, or completes (RS_DONE). 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...
 
const rs_stats_trs_job_statistics (rs_job_t *job)
 Return a pointer to the statistics in a job. More...
 
rs_result rs_job_free (rs_job_t *)
 Deallocate job state. More...
 
rs_job_trs_sig_begin (size_t new_block_len, size_t strong_sum_len, rs_magic_number sig_magic)
 Start generating a signature. More...
 
rs_job_trs_delta_begin (rs_signature_t *)
 Prepare to compute a streaming delta. More...
 
rs_job_trs_loadsig_begin (rs_signature_t **)
 Read a signature from a file into an rs_signature structure in memory. More...
 
rs_result rs_build_hash_table (rs_signature_t *sums)
 Call this after loading a signature to index it. More...
 
rs_job_trs_patch_begin (rs_copy_cb *copy_cb, void *copy_arg)
 Apply a delta to a basis file to recreate the new file. More...
 
rs_result rs_sig_file (FILE *old_file, FILE *sig_file, size_t block_len, size_t strong_len, rs_magic_number sig_magic, rs_stats_t *stats)
 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, rs_stats_t *stats)
 Load signatures from a signature file into memory. More...
 
rs_result rs_file_copy_cb (void *arg, rs_long_t pos, size_t *len, void **buf)
 rs_copy_cb that reads from a stdio file. More...
 
rs_result rs_delta_file (rs_signature_t *, FILE *new_file, FILE *delta_file, rs_stats_t *)
 Generate a delta between a signature and a new file, int a delta file. More...
 
rs_result rs_patch_file (FILE *basis_file, FILE *delta_file, FILE *new_file, rs_stats_t *)
 Apply a patch, relative to a basis, into a new file. More...
 

Variables

char const rs_librsync_version []
 Library version string. More...
 
char const rs_licence_string []
 Summary of the licence for librsync. More...
 
const int RS_MD4_SUM_LENGTH
 
const int RS_BLAKE2_SUM_LENGTH
 
int rs_inbuflen
 Buffer sizes for file IO. More...
 
int rs_outbuflen
 

Detailed Description

Public header for librsync.

Definition in file librsync.h.

Macro Definition Documentation

#define RS_DEFAULT_BLOCK_LEN   2048

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

Definition at line 405 of file librsync.h.

Typedef Documentation

rs_trace_fn_t

Callback to write out log messages.

Parameters
levela syslog level.
msgmessage to be logged.
See also
Debugging trace and error logging

Definition at line 137 of file librsync.h.

typedef struct rs_stats rs_stats_t

Performance statistics from a librsync encoding or decoding operation.

See also
api_stats
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()

Definition at line 266 of file librsync.h.

typedef struct rs_buffers_s rs_buffers_t
See also
rs_buffers_s

Definition at line 402 of file librsync.h.

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().

The contents are opaque to the application, and instances are always allocated by the library.

See also
Streaming jobs
rs_job

Definition at line 420 of file librsync.h.

typedef rs_result rs_driven_cb(rs_job_t *job, rs_buffers_t *buf, void *opaque)

Type of application-supplied function for rs_job_drive().

See also
Pull stream interface.

Definition at line 447 of file librsync.h.

typedef rs_result rs_copy_cb(void *opaque, rs_long_t pos, size_t *len, void **buf)

Callback used to retrieve parts of the basis file.

Parameters
posPosition where copying should begin.
lenOn input, the amount of data that should be retrieved. Updated to show how much is actually available, but should not be greater than the input value.
bufOn input, a buffer of at least *len bytes. May be updated to point to a buffer allocated by the callback if it prefers.

Definition at line 531 of file librsync.h.

Enumeration Type Documentation

A uint32 magic number, emitted in bigendian/network order at the start of librsync files.

Enumerator
RS_DELTA_MAGIC 

A delta file.

At present, there's only one delta format.

The four-byte literal "rs\x026".

RS_MD4_SIG_MAGIC 

A signature file with MD4 signatures.

Backward compatible with librsync < 1.0, but strongly deprecated because it creates a security vulnerability on files containing partly untrusted data. See https://github.com/librsync/librsync/issues/5.

The four-byte literal "rs\x016".

See also
rs_sig_begin()
RS_BLAKE2_SIG_MAGIC 

A signature file using the BLAKE2 hash.

Supported from librsync 1.0.

The four-byte literal "rs\x017".

See also
rs_sig_begin()

Definition at line 75 of file librsync.h.

Log severity levels.

These are the same as syslog, at least in glibc.

See also
rs_trace_set_level()
Debugging trace and error logging
Enumerator
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.

Definition at line 118 of file librsync.h.

enum rs_result

Return codes from nonblocking rsync operations.

See also
rs_strerror()
api_callbacks
Enumerator
RS_DONE 

Completed successfully.

RS_BLOCKED 

Blocked waiting for more data.

RS_RUNNING 

The job is still running, and not yet finished or blocked.

(This value should never be seen by the application.)

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 

Unexpected end of input file, perhaps due to a truncated file or dropped network connection.

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.

Definition at line 192 of file librsync.h.

Function Documentation

void rs_trace_set_level ( rs_loglevel  level)

Set the least important message severity that will be output.

See also
Debugging trace and error logging

Definition at line 102 of file trace.c.

void rs_trace_to ( rs_trace_fn_t new_impl)

Set trace callback.

See also
Debugging trace and error logging

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?

Definition at line 95 of file trace.c.

void rs_trace_stderr ( rs_loglevel  level,
char const *  msg 
)

Default trace callback that writes to stderr.

Implements rs_trace_fn_t, and may be passed to rs_trace_to().

See also
Debugging trace and error logging
int rs_supports_trace ( void  )

Check whether the library was compiled with debugging trace.

Returns
True if the library contains trace code; otherwise false. If this returns false, then trying to turn trace on will achieve nothing.
See also
Debugging trace and error logging

Definition at line 214 of file trace.c.

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.

Definition at line 34 of file hex.c.

size_t rs_unbase64 ( char *  s)

Decode a base64 buffer in place.

Returns
The number of binary bytes.

Definition at line 36 of file base64.c.

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

Encode a buffer as base64.

Definition at line 71 of file base64.c.

char const* rs_strerror ( rs_result  r)

Return an English description of a rs_result value.

Definition at line 51 of file msg.c.

void rs_mdfour_update ( rs_mdfour_t md,
void const *  in_void,
size_t  n 
)

Feed some data into the MD4 accumulator.

Parameters
mdMD4 accumulator.
in_voidData to add.
nNumber of bytes fed in.

Definition at line 327 of file mdfour.c.

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
statsStatistics from an encoding or decoding operation.
bufBuffer to receive result.
sizeSize of buffer.
Returns
buf.
See also
Stats

Definition at line 59 of file stats.c.

int rs_log_stats ( rs_stats_t const *  stats)

Write statistics into the current log as text.

See also
Stats
Debugging trace and error logging

Definition at line 47 of file stats.c.

void rs_free_sumset ( rs_signature_t )

Deep deallocation of checksums.

Definition at line 36 of file sumset.c.

void rs_sumset_dump ( rs_signature_t const *  )

Dump signatures to the log.

Definition at line 53 of file sumset.c.

rs_result rs_job_iter ( rs_job_t job,
rs_buffers_t buffers 
)

Run a rs_job state machine until it blocks (RS_BLOCKED), returns an error, or completes (RS_DONE).

Parameters
jobDescription of job state.
buffersPointer to structure describing input and output buffers.
Returns
The rs_result that caused iteration to stop.

buffers->eof_in should be 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.

See also
Streaming jobs.

Definition at line 133 of file job.c.

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.

Definition at line 215 of file job.c.

const rs_stats_t* rs_job_statistics ( rs_job_t job)

Return a pointer to the statistics in a job.

Definition at line 200 of file job.c.

rs_result rs_job_free ( rs_job_t )

Deallocate job state.

Definition at line 90 of file job.c.

rs_job_t* rs_sig_begin ( size_t  new_block_len,
size_t  strong_sum_len,
rs_magic_number  sig_magic 
)

Start generating a signature.

Returns
A new rs_job_t into which the old file data can be passed.
Parameters
sig_magicIndicates the version of signature file format to generate. See rs_magic_number.
new_block_lenSize of checksum blocks. Larger values make the signature shorter, and the delta longer.
strong_sum_lenIf non-zero, truncate the strong signatures to this many bytes, to make the signature shorter. It's recommended you leave this at zero to get the full strength.
See also
rs_sig_file()

Definition at line 150 of file mksum.c.

rs_job_t* rs_delta_begin ( rs_signature_t )

Prepare to compute a streaming delta.

Todo:
Add a version of this that takes a rs_magic_number controlling the delta format.

Definition at line 443 of file delta.c.

rs_job_t* rs_loadsig_begin ( rs_signature_t **  )

Read a signature from a file into an rs_signature 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.

Definition at line 199 of file readsums.c.

rs_result rs_build_hash_table ( rs_signature_t sums)

Call this after loading a signature to index it.

Use rs_free_sumset() to release it after use.

Definition at line 111 of file search.c.

rs_job_t* rs_patch_begin ( rs_copy_cb copy_cb,
void *  copy_arg 
)

Apply a delta to a basis file 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_free() to dispose of it.

Parameters
copy_cbCallback used to retrieve content from the basis file.
copy_argOpaque 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.
Todo:
Implement COPY commands.
See also
rs_patch_file()
Streaming jobs

Definition at line 287 of file patch.c.

rs_result rs_sig_file ( FILE *  old_file,
FILE *  sig_file,
size_t  block_len,
size_t  strong_len,
rs_magic_number  sig_magic,
rs_stats_t stats 
)

Generate the signature of a basis file, and write it out to another.

Parameters
old_fileStdio readable file whose signature will be generated.
sig_fileWritable stdio file to which the signature will be written./
block_lenblock size for signature generation, in bytes
strong_lentruncated length of strong checksums, in bytes
sig_magicA signature magic number indicating what format to use.
statsOptional pointer to receive statistics.
See also
Whole-file API

Definition at line 95 of file whole.c.

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

Load signatures from a signature file into memory.

Return a pointer to the newly allocated structure in sumset.

See also
Whole-file API

Definition at line 114 of file whole.c.

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

rs_copy_cb that reads from a stdio file.

Definition at line 206 of file buf.c.

rs_result rs_delta_file ( rs_signature_t ,
FILE *  new_file,
FILE *  delta_file,
rs_stats_t  
)

Generate a delta between a signature and a new file, int a delta file.

See also
Whole-file API

Definition at line 131 of file whole.c.

rs_result rs_patch_file ( FILE *  basis_file,
FILE *  delta_file,
FILE *  new_file,
rs_stats_t  
)

Apply a patch, relative to a basis, into a new file.

See also
Whole-file API

Definition at line 151 of file whole.c.

Variable Documentation

char const rs_librsync_version[]

Library version string.

See also
Versioning

Definition at line 25 of file version.c.

char const rs_licence_string[]

Summary of the licence for librsync.

int rs_inbuflen

Buffer sizes for file IO.

You probably only need to change these in testing.

Buffer sizes for file IO.

Definition at line 66 of file buf.c.