librsync  2.3.1
librsync.md
1 # API Overview {#page_api}
2 
3 The library supports four basic operations:
4 
5 -# \b sig: Generating the signature S of a file A .
6 -# \b loadsig: Read a signature from a file into memory.
7 -# \b delta: Calculating a delta D from S and a new file B.
8 -# \b patch: Applying D to A to reconstruct B.
9 
10 These are all available in three different modes:
11 
12 - \ref api_whole - for applications that just
13  want to make and use signatures and deltas on whole files
14  with a single function call.
15 
16 - \ref api_streaming - a "push" mode where the caller provides input and
17  output space, and rs_job_iter() makes as much progress as it can.
18 
19 - \ref api_pull - a "pull" mode where librsync will call application-provided
20  callbacks to fill and empty buffers.
21 
22 Other documentation pages:
23 
24 - \ref api_trace - aid debugging by showing messages about librsync's state.
25 - \ref api_callbacks
26 - \ref api_stats
27 - \ref api_utility
28 - \ref versioning
29 
30 The public interface to librsync is librsync.h, and other headers are internal.
31 
32 The librsync tree also provides the \ref page_rdiff, which makes this
33 functionality available to users and scripting languages.
34 
35 ## Naming conventions
36 
37 All external symbols have the prefix \c rs_, or
38 \c RS_ in the case of preprocessor symbols.
39 (There are some private symbols that currently don't match this, but these
40 are considered to be bugs.)
41 
42 Symbols beginning with \c rs__ (double underscore) are private and should
43 not be called from outside the library.
44 
45 ## Threaded IO
46 
47 librsync may be used from threaded programs. librsync does no
48 synchronization itself. Each job should be guarded by a monitor or used
49 by only a single thread.
50 
51 Be careful that the trace functions are safe to call from multiple threads.