Public header for librsync. More...

Include dependency graph for librsync.h:

This graph shows which files directly or indirectly include 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_t *	rs_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_t *	rs_sig_begin (size_t block_len, size_t strong_len, rs_magic_number sig_magic)
	Start generating a signature. More...

LIBRSYNC_EXPORT rs_job_t *	rs_delta_begin (rs_signature_t *)
	Prepare to compute a streaming delta. More...

LIBRSYNC_EXPORT rs_job_t *	rs_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_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...

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

level	a syslog level.
msg	message 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

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

Enumeration Type Documentation

◆ rs_magic_number

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\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

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

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

md	MD4 accumulator.
in_void	Data to add.
n	Number 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

stats	Statistics from an encoding or decoding operation.
buf	Buffer to receive result.
size	Size 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

job	Description of job state.
buffers	Pointer 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_magic	Signature file format to generate (0 for "recommended"). See rs_magic_number.
block_len	Checksum block size to use (0 for "recommended"). Larger values make the signature shorter, and the delta longer.
strong_len	Strongsum 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_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.

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_file	Stdio readable file whose signature will be generated.
sig_file	Writable stdio file to which the signature will be written./
block_len	Checksum block size to use (0 for "recommended"). Larger values make the signature shorter, and the delta longer.
strong_len	Strongsum 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_magic	Signature file format to generate (0 for "recommended"). See rs_magic_number.
stats	Optional 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_file	Readable stdio file from which the signature will be read.
sumset	on return points to the newly allocated structure.
stats	Optional 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.

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ RS_MAX_STRONG_SUM_LENGTH

◆ RS_DEFAULT_BLOCK_LEN

◆ RS_DEFAULT_MIN_STRONG_LEN

Typedef Documentation

◆ rs_byte_t

◆ rs_long_t

◆ rs_trace_fn_t

◆ rs_result

◆ rs_stats_t

◆ rs_mdfour_t

◆ rs_weak_sum_t

◆ rs_strong_sum_t

◆ rs_signature_t

◆ rs_buffers_t

◆ rs_job_t

◆ rs_driven_cb

◆ rs_copy_cb

Enumeration Type Documentation

◆ rs_magic_number

◆ rs_loglevel

◆ rs_result

Function Documentation

◆ rs_trace_set_level()

◆ rs_trace_to()

◆ rs_trace_stderr()

◆ rs_supports_trace()

◆ rs_hexify()

◆ rs_unbase64()

◆ rs_base64()

◆ rs_strerror()

◆ rs_mdfour()

◆ rs_mdfour_begin()

◆ rs_mdfour_update()

◆ rs_mdfour_result()

◆ rs_format_stats()

◆ rs_log_stats()

◆ rs_signature_log_stats()

◆ rs_free_sumset()

◆ rs_sumset_dump()

◆ rs_job_iter()

◆ rs_job_drive()

◆ rs_job_statistics()

◆ rs_job_free()

◆ rs_sig_args()

◆ rs_sig_begin()

◆ rs_delta_begin()

◆ rs_loadsig_begin()

◆ rs_build_hash_table()

◆ rs_patch_begin()

◆ rs_file_open()

◆ rs_file_close()

◆ rs_file_size()

◆ rs_file_copy_cb()

◆ rs_sig_file()

◆ rs_loadsig_file()

◆ rs_delta_file()

◆ rs_patch_file()

Variable Documentation

◆ rs_librsync_version

◆ RS_MD4_SUM_LENGTH

◆ RS_BLAKE2_SUM_LENGTH

◆ rs_inbuflen

◆ rs_outbuflen