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

Public header for librsync. More...

Include dependency graph for librsync.h:
This graph shows which files directly or indirectly include this file:

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...
 
#define RS_DEFAULT_MIN_STRONG_LEN   12
 Default minimum strong sum length, if the filesize is unknown. 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)
 Callback to write out log messages. More...
 
typedef enum rs_result rs_result
 Return codes from nonblocking rsync operations. 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 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
 The signature datastructure type. More...
 
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 , RS_RK_MD4_SIG_MAGIC = 0x72730146 ,
  RS_RK_BLAKE2_SIG_MAGIC = 0x72730147
}
 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

LIBRSYNC_EXPORT void rs_trace_set_level (rs_loglevel level)
 Set the least important message severity that will be output. More...
 
LIBRSYNC_EXPORT void rs_trace_to (rs_trace_fn_t *)
 Set trace callback. More...
 
LIBRSYNC_EXPORT void rs_trace_stderr (rs_loglevel level, char const *msg)
 Default trace callback that writes to stderr. More...
 
LIBRSYNC_EXPORT int rs_supports_trace (void)
 Check whether the library was compiled with debugging trace. More...
 
LIBRSYNC_EXPORT 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...
 
LIBRSYNC_EXPORT size_t rs_unbase64 (char *s)
 Decode a base64 buffer in place. More...
 
LIBRSYNC_EXPORT void rs_base64 (unsigned char const *buf, int n, char *out)
 Encode a buffer as base64. More...
 
LIBRSYNC_EXPORT char const * rs_strerror (rs_result r)
 Return an English description of a rs_result value. More...
 
LIBRSYNC_EXPORT void rs_mdfour (unsigned char *out, void const *in, size_t)
 
LIBRSYNC_EXPORT void rs_mdfour_begin (rs_mdfour_t *md)
 
LIBRSYNC_EXPORT void rs_mdfour_update (rs_mdfour_t *md, void const *in_void, size_t n)
 Feed some data into the MD4 accumulator. More...
 
LIBRSYNC_EXPORT void rs_mdfour_result (rs_mdfour_t *md, unsigned char *out)
 
LIBRSYNC_EXPORT char * rs_format_stats (rs_stats_t const *stats, char *buf, size_t size)
 Return a human-readable representation of statistics. More...
 
LIBRSYNC_EXPORT int rs_log_stats (rs_stats_t const *stats)
 Write statistics into the current log as text. More...
 
LIBRSYNC_EXPORT void rs_signature_log_stats (rs_signature_t const *sig)
 Log the rs_signature_delta match stats. More...
 
LIBRSYNC_EXPORT void rs_free_sumset (rs_signature_t *)
 Deep deallocation of checksums. More...
 
LIBRSYNC_EXPORT void rs_sumset_dump (rs_signature_t const *)
 Dump signatures to the log. More...
 
LIBRSYNC_EXPORT 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...
 
LIBRSYNC_EXPORT 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...
 
LIBRSYNC_EXPORT const rs_stats_trs_job_statistics (rs_job_t *job)
 Return a pointer to the statistics in a job. More...
 
LIBRSYNC_EXPORT rs_result rs_job_free (rs_job_t *)
 Deallocate job state. More...
 
LIBRSYNC_EXPORT rs_result rs_sig_args (rs_long_t old_fsize, rs_magic_number *magic, size_t *block_len, size_t *strong_len)
 Get or check signature arguments for a given file size. More...
 
LIBRSYNC_EXPORT rs_job_trs_sig_begin (size_t block_len, size_t strong_len, rs_magic_number sig_magic)
 Start generating a signature. More...
 
LIBRSYNC_EXPORT rs_job_trs_delta_begin (rs_signature_t *)
 Prepare to compute a streaming delta. More...
 
LIBRSYNC_EXPORT rs_job_trs_loadsig_begin (rs_signature_t **)
 Read a signature from a file into an rs_signature structure in memory. More...
 
LIBRSYNC_EXPORT rs_result rs_build_hash_table (rs_signature_t *sums)
 Call this after loading a signature to index it. More...
 
LIBRSYNC_EXPORT 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...
 
LIBRSYNC_EXPORT FILE * rs_file_open (char const *filename, char const *mode, int force)
 Open a file with special handling for stdin or stdout. More...
 
LIBRSYNC_EXPORT int rs_file_close (FILE *file)
 Close a file with special handling for stdin or stdout. More...
 
LIBRSYNC_EXPORT rs_long_t rs_file_size (FILE *file)
 Get the size of a file. More...
 
LIBRSYNC_EXPORT 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...
 
LIBRSYNC_EXPORT 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...
 
LIBRSYNC_EXPORT 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...
 
LIBRSYNC_EXPORT 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...
 
LIBRSYNC_EXPORT 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

LIBRSYNC_EXPORT char const rs_librsync_version []
 Library version string. More...
 
LIBRSYNC_EXPORT const int RS_MD4_SUM_LENGTH
 
LIBRSYNC_EXPORT const int RS_BLAKE2_SUM_LENGTH
 
LIBRSYNC_EXPORT int rs_inbuflen
 Buffer sizes for file IO. More...
 
LIBRSYNC_EXPORT int rs_outbuflen
 

Detailed Description

Public header for librsync.

Definition in file librsync.h.

Macro Definition Documentation

◆ RS_MAX_STRONG_SUM_LENGTH

#define RS_MAX_STRONG_SUM_LENGTH   32

Definition at line 240 of file librsync.h.

◆ RS_DEFAULT_BLOCK_LEN

#define RS_DEFAULT_BLOCK_LEN   2048

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

The 2K default assumes a typical file is about 4MB and should be OK for files up to 32G with more than 1GB ram.

Definition at line 367 of file librsync.h.

◆ RS_DEFAULT_MIN_STRONG_LEN

#define RS_DEFAULT_MIN_STRONG_LEN   12

Default minimum strong sum length, if the filesize is unknown.

This is conservative, and should be safe for files less than 45TB with a 2KB block_len, assuming no collision attack with crafted data.

Definition at line 373 of file librsync.h.

Typedef Documentation

◆ rs_byte_t

typedef uint8_t rs_byte_t

Definition at line 49 of file librsync.h.

◆ rs_long_t

typedef intmax_t rs_long_t

Definition at line 50 of file librsync.h.

◆ rs_trace_fn_t

typedef void rs_trace_fn_t(rs_loglevel level, char const *msg)

Callback to write out log messages.

Parameters
levela syslog level.
msgmessage to be logged.
See also
Trace output

Definition at line 136 of file librsync.h.

◆ rs_result

typedef enum rs_result rs_result

Return codes from nonblocking rsync operations.

See also
rs_strerror()
api_callbacks

◆ rs_stats_t

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

◆ rs_mdfour_t

typedef 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 236 of file librsync.h.

◆ rs_weak_sum_t

typedef uint32_t rs_weak_sum_t

Definition at line 242 of file librsync.h.

◆ rs_strong_sum_t

typedef unsigned char rs_strong_sum_t[RS_MAX_STRONG_SUM_LENGTH]

Definition at line 243 of file librsync.h.

◆ rs_signature_t

typedef struct rs_signature rs_signature_t

The signature datastructure type.

Definition at line 282 of file librsync.h.

◆ rs_buffers_t

typedef struct rs_buffers_s rs_buffers_t
See also
rs_buffers_s

Definition at line 361 of file librsync.h.

◆ rs_job_t

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 API
rs_job

Definition at line 384 of file librsync.h.

◆ rs_driven_cb

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 API

Definition at line 405 of file librsync.h.

◆ rs_copy_cb

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
opaqueThe opaque object to execute the callback with. Often the file to read from.
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 502 of file librsync.h.

Enumeration Type Documentation

◆ 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\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()
RS_RK_MD4_SIG_MAGIC 

A signature file with RabinKarp rollsum and MD4 hash.

Uses a faster/safer rollsum, but still strongly discouraged because of MD4's security vulnerability. Supported since librsync 2.2.0.

The four-byte literal "rs\x01F".

See also
rs_sig_begin()
RS_RK_BLAKE2_SIG_MAGIC 

A signature file with RabinKarp rollsum and BLAKE2 hash.

Uses a faster/safer rollsum together with the safer BLAKE2 hash. This is the recommended default supported since librsync 2.2.0.

The four-byte literal "rs\x01G".

See also
rs_sig_begin()

Definition at line 65 of file librsync.h.

◆ rs_loglevel

Log severity levels.

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

See also
rs_trace_set_level()
Trace output
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.

◆ rs_result

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 180 of file librsync.h.

Function Documentation

◆ rs_trace_set_level()

LIBRSYNC_EXPORT void rs_trace_set_level ( rs_loglevel  level)

Set the least important message severity that will be output.

See also
Trace output

Definition at line 62 of file trace.c.

◆ rs_trace_to()

LIBRSYNC_EXPORT void rs_trace_to ( rs_trace_fn_t new_impl)

Set trace callback.

See also
Trace output

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 57 of file trace.c.

◆ rs_trace_stderr()

LIBRSYNC_EXPORT 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
Trace output

◆ rs_supports_trace()

LIBRSYNC_EXPORT 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
Trace output

Definition at line 102 of file trace.c.

◆ rs_hexify()

LIBRSYNC_EXPORT 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 23 of file hex.c.

◆ rs_unbase64()

LIBRSYNC_EXPORT size_t rs_unbase64 ( char *  s)

Decode a base64 buffer in place.

Returns
The number of binary bytes.

Decode a base64 buffer in place.

See RFC1521 for the specification of base64.

Definition at line 30 of file base64.c.

◆ rs_base64()

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

Encode a buffer as base64.

Encode a buffer as base64.

Definition at line 60 of file base64.c.

◆ rs_strerror()

LIBRSYNC_EXPORT char const * rs_strerror ( rs_result  r)

Return an English description of a rs_result value.

Definition at line 46 of file msg.c.

◆ rs_mdfour()

LIBRSYNC_EXPORT void rs_mdfour ( unsigned char *  out,
void const *  in,
size_t  n 
)

Definition at line 320 of file mdfour.c.

◆ rs_mdfour_begin()

LIBRSYNC_EXPORT void rs_mdfour_begin ( rs_mdfour_t md)

Definition at line 224 of file mdfour.c.

◆ rs_mdfour_update()

LIBRSYNC_EXPORT 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 273 of file mdfour.c.

◆ rs_mdfour_result()

LIBRSYNC_EXPORT void rs_mdfour_result ( rs_mdfour_t md,
unsigned char *  out 
)

Definition at line 310 of file mdfour.c.

◆ rs_format_stats()

LIBRSYNC_EXPORT 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 40 of file stats.c.

◆ rs_log_stats()

LIBRSYNC_EXPORT int rs_log_stats ( rs_stats_t const *  stats)

Write statistics into the current log as text.

See also
Stats
Trace output

Definition at line 31 of file stats.c.

◆ rs_signature_log_stats()

LIBRSYNC_EXPORT void rs_signature_log_stats ( rs_signature_t const *  sig)

Log the rs_signature_delta match stats.

Definition at line 256 of file sumset.c.

◆ rs_free_sumset()

LIBRSYNC_EXPORT void rs_free_sumset ( rs_signature_t psums)

Deep deallocation of checksums.

Definition at line 294 of file sumset.c.

◆ rs_sumset_dump()

LIBRSYNC_EXPORT void rs_sumset_dump ( rs_signature_t const *  sums)

Dump signatures to the log.

Definition at line 300 of file sumset.c.

◆ rs_job_iter()

LIBRSYNC_EXPORT 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 API

Definition at line 85 of file job.c.

◆ rs_job_drive()

LIBRSYNC_EXPORT 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 139 of file job.c.

◆ rs_job_statistics()

LIBRSYNC_EXPORT const rs_stats_t * rs_job_statistics ( rs_job_t job)

Return a pointer to the statistics in a job.

Definition at line 134 of file job.c.

◆ rs_job_free()

LIBRSYNC_EXPORT rs_result rs_job_free ( rs_job_t job)

Deallocate job state.

Definition at line 58 of file job.c.

◆ rs_sig_args()

LIBRSYNC_EXPORT rs_result rs_sig_args ( rs_long_t  old_fsize,
rs_magic_number magic,
size_t *  block_len,
size_t *  strong_len 
)

Get or check signature arguments for a given file size.

This can be used to get the recommended arguments for generating a signature. On calling, old_fsize should be set to the old file size or -1 for "unknown". The magic and block_len arguments should be set to a valid value or 0 for "recommended". The strong_len input should be set to a valid value, 0 for "maximum", or -1 for "miniumum". Use strong_len=0 for the best protection against active hash collision attacks for the given magic type. Use strong_len=-1 for the smallest signature size that is safe against random hash collisions for the block_len and old_fsize. Use strong_len=20 for something probably good enough against attacks with smaller signatures. On return the 0 or -1 input args will be set to recommended values and the returned result will indicate if any inputs were invalid.

Parameters
old_fsize- the original file size (-1 for "unknown").
*magic- the magic type to use (0 for "recommended").
*block_len- the block length to use (0 for "recommended").
*strong_len- the strongsum length to use (0 for "maximum", -1 for "minimum").
Returns
RS_DONE if all arguments are valid, otherwise an error code.

Definition at line 113 of file sumset.c.

◆ rs_sig_begin()

LIBRSYNC_EXPORT rs_job_t * rs_sig_begin ( size_t  block_len,
size_t  strong_len,
rs_magic_number  sig_magic 
)

Start generating a signature.

It's recommended you use rs_sig_args() to get the recommended arguments for this based on the original file size.

Returns
A new rs_job_t into which the old file data can be passed.
Parameters
sig_magicSignature file format to generate (0 for "recommended"). See rs_magic_number.
block_lenChecksum block size to use (0 for "recommended"). Larger values make the signature shorter, and the delta longer.
strong_lenStrongsum length in bytes to use (0 for "maximum", -1 for "minimum"). Smaller values make the signature shorter but increase the risk of corruption from hash collisions.
See also
rs_sig_file()

Definition at line 110 of file mksum.c.

◆ rs_delta_begin()

LIBRSYNC_EXPORT rs_job_t * rs_delta_begin ( rs_signature_t sig)

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 396 of file delta.c.

◆ rs_loadsig_begin()

LIBRSYNC_EXPORT rs_job_t * rs_loadsig_begin ( rs_signature_t **  signature)

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 135 of file readsums.c.

◆ rs_build_hash_table()

LIBRSYNC_EXPORT 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 274 of file sumset.c.

◆ rs_patch_begin()

LIBRSYNC_EXPORT 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 API

Definition at line 221 of file patch.c.

◆ rs_file_open()

LIBRSYNC_EXPORT FILE * rs_file_open ( char const *  filename,
char const *  mode,
int  force 
)

Open a file with special handling for stdin or stdout.

This provides a platform independent way to open large binary files. A filename "" or "-" means use stdin for reading, or stdout for writing.

Parameters
filename- The filename to open.
mode- fopen style mode string.
force- bool to force overwriting of existing files.

Definition at line 81 of file fileutil.c.

◆ rs_file_close()

LIBRSYNC_EXPORT int rs_file_close ( FILE *  file)

Close a file with special handling for stdin or stdout.

This will not actually close the file if it is stdin or stdout.

Parameters
file- the stdio file to close.

Definition at line 120 of file fileutil.c.

◆ rs_file_size()

LIBRSYNC_EXPORT rs_long_t rs_file_size ( FILE *  file)

Get the size of a file.

This provides a platform independent way to get the size of large files. It will return -1 if the size cannot be determined because it is not a regular file.

Parameters
file- the stdio file to get the size of.

Definition at line 127 of file fileutil.c.

◆ rs_file_copy_cb()

LIBRSYNC_EXPORT 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 135 of file fileutil.c.

◆ rs_sig_file()

LIBRSYNC_EXPORT 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.

It's recommended you use rs_sig_args() to get the recommended arguments for this based on the original file size.

Parameters
old_fileStdio readable file whose signature will be generated.
sig_fileWritable stdio file to which the signature will be written./
block_lenChecksum block size to use (0 for "recommended"). Larger values make the signature shorter, and the delta longer.
strong_lenStrongsum length in bytes to use (0 for "maximum", -1 for "minimum"). Smaller values make the signature shorter but increase the risk of corruption from hash collisions.
sig_magicSignature file format to generate (0 for "recommended"). See rs_magic_number.
statsOptional pointer to receive statistics.
See also
Whole-file API

Definition at line 67 of file whole.c.

◆ rs_loadsig_file()

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

Load signatures from a signature file into memory.

Parameters
sig_fileReadable stdio file from which the signature will be read.
sumseton return points to the newly allocated structure.
statsOptional pointer to receive statistics.
See also
Whole-file API

Definition at line 90 of file whole.c.

◆ rs_delta_file()

LIBRSYNC_EXPORT rs_result rs_delta_file ( rs_signature_t sig,
FILE *  new_file,
FILE *  delta_file,
rs_stats_t stats 
)

Generate a delta between a signature and a new file into a delta file.

See also
Whole-file API

Definition at line 108 of file whole.c.

◆ rs_patch_file()

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

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

See also
Whole-file API

Definition at line 124 of file whole.c.

Variable Documentation

◆ rs_librsync_version

LIBRSYNC_EXPORT char const rs_librsync_version[]
extern

Library version string.

See also
Versioning

Definition at line 25 of file version.c.

◆ RS_MD4_SUM_LENGTH

LIBRSYNC_EXPORT const int RS_MD4_SUM_LENGTH
extern

Definition at line 30 of file checksum.c.

◆ RS_BLAKE2_SUM_LENGTH

LIBRSYNC_EXPORT const int RS_BLAKE2_SUM_LENGTH

Definition at line 238 of file librsync.h.

◆ rs_inbuflen

LIBRSYNC_EXPORT int rs_inbuflen
extern

Buffer sizes for file IO.

The default 0 means use the recommended buffer size for the operation being performed, any other value will override the recommended sizes. You probably only need to change these in testing.

Buffer sizes for file IO.

Definition at line 41 of file whole.c.

◆ rs_outbuflen

LIBRSYNC_EXPORT int rs_outbuflen

Definition at line 564 of file librsync.h.