librsync
2.0.2
|
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 uint8_t | rs_byte_t |
typedef intmax_t | rs_long_t |
typedef void | rs_trace_fn_t (rs_loglevel level, char const *msg) |
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 uint32_t | 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_t * | rs_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_t * | rs_sig_begin (size_t new_block_len, size_t strong_sum_len, rs_magic_number sig_magic) |
Start generating a signature. 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 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_t * | rs_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 into 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 |
Public header for librsync.
Definition in file librsync.h.
#define RS_DEFAULT_BLOCK_LEN 2048 |
Default block length, if not determined by any other factors.
Definition at line 336 of file librsync.h.
typedef struct rs_stats rs_stats_t |
Performance statistics from a librsync encoding or decoding operation.
struct rs_mdfour rs_mdfour_t |
MD4 message-digest accumulator.
Definition at line 219 of file librsync.h.
typedef struct rs_buffers_s rs_buffers_t |
Definition at line 333 of file librsync.h.
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.
Definition at line 347 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().
Definition at line 368 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.
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, but should not be greater than the input value. |
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. |
Definition at line 430 of file librsync.h.
enum rs_magic_number |
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_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_BLAKE2_SIG_MAGIC |
A signature file using the BLAKE2 hash. Supported from librsync 1.0. The four-byte literal
|
Definition at line 68 of file librsync.h.
enum rs_loglevel |
Log severity levels.
These are the same as syslog, at least in glibc.
Definition at line 100 of file librsync.h.
enum rs_result |
Return codes from nonblocking rsync operations.
Definition at line 161 of file librsync.h.
void rs_trace_set_level | ( | rs_loglevel | level | ) |
void rs_trace_to | ( | rs_trace_fn_t * | new_impl | ) |
Set trace callback.
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.
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().
int rs_supports_trace | ( | void | ) |
void rs_hexify | ( | char * | to_buf, |
void const * | from_buf, | ||
int | from_len | ||
) |
size_t rs_unbase64 | ( | char * | s | ) |
void rs_base64 | ( | unsigned char const * | buf, |
int | n, | ||
char * | out | ||
) |
char const* rs_strerror | ( | rs_result | r | ) |
void rs_mdfour_update | ( | rs_mdfour_t * | md, |
void const * | in_void, | ||
size_t | n | ||
) |
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.
stats | Statistics from an encoding or decoding operation. |
buf | Buffer to receive result. |
size | Size of buffer. |
buf
.int rs_log_stats | ( | rs_stats_t const * | stats | ) |
void rs_free_sumset | ( | rs_signature_t * | ) |
void rs_sumset_dump | ( | rs_signature_t const * | ) |
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).
job | Description of job state. |
buffers | Pointer to structure describing input and output buffers. |
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.
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 | ||
) |
const rs_stats_t* rs_job_statistics | ( | rs_job_t * | job | ) |
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.
sig_magic | Indicates the version of signature file format to generate. See rs_magic_number. |
new_block_len | Size of checksum blocks. Larger values make the signature shorter, and the delta longer. |
strong_sum_len | If 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. |
rs_job_t* rs_delta_begin | ( | rs_signature_t * | ) |
Prepare to compute a streaming delta.
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.
Definition at line 140 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.
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.
copy_cb | Callback used to retrieve content from the basis file. |
copy_arg | Opaque environment pointer passed through to the callback. |
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.
old_file | Stdio readable file whose signature will be generated. |
sig_file | Writable stdio file to which the signature will be written./ |
block_len | block size for signature generation, in bytes |
strong_len | truncated length of strong checksums, in bytes |
sig_magic | A signature magic number indicating what format to use. |
stats | Optional pointer to receive statistics. |
rs_result rs_loadsig_file | ( | FILE * | sig_file, |
rs_signature_t ** | sumset, | ||
rs_stats_t * | stats | ||
) |
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 137 of file fileutil.c.
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 * | |||
) |
char const rs_librsync_version[] |
char const rs_licence_string[] |
Summary of the licence for librsync.