summaryrefslogtreecommitdiff
path: root/rsync/rsync.h
authorkergoth <kergoth>2002-01-25 22:14:26 (UTC)
committer kergoth <kergoth>2002-01-25 22:14:26 (UTC)
commit15318cad33835e4e2dc620d033e43cd930676cdd (patch) (unidiff)
treec2fa0399a2c47fda8e2cd0092c73a809d17f68eb /rsync/rsync.h
downloadopie-15318cad33835e4e2dc620d033e43cd930676cdd.zip
opie-15318cad33835e4e2dc620d033e43cd930676cdd.tar.gz
opie-15318cad33835e4e2dc620d033e43cd930676cdd.tar.bz2
Initial revision
Diffstat (limited to 'rsync/rsync.h') (more/less context) (ignore whitespace changes)
-rw-r--r--rsync/rsync.h388
1 files changed, 388 insertions, 0 deletions
diff --git a/rsync/rsync.h b/rsync/rsync.h
new file mode 100644
index 0000000..a80a368
--- a/dev/null
+++ b/rsync/rsync.h
@@ -0,0 +1,388 @@
1/*= -*- c-basic-offset: 4; indent-tabs-mode: nil; -*-
2 *
3 * librsync -- library for network deltas
4 * $Id$
5 *
6 * Copyright (C) 2000, 2001 by Martin Pool <mbp@samba.org>
7 *
8 * This program is free software; you can redistribute it and/or modify
9 * it under the terms of the GNU Lesser General Public License as published by
10 * the Free Software Foundation; either version 2.1 of the License, or
11 * (at your option) any later version.
12 *
13 * This program is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 * GNU Lesser General Public License for more details.
17 *
18 * You should have received a copy of the GNU Lesser General Public License
19 * along with this program; if not, write to the Free Software
20 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
21 */
22
23 /*
24 | You should never wear your best
25 | trousers when you go out to fight for
26 | freedom and liberty.
27 | -- Henrik Ibsen
28 */
29
30
31/** \file rsync.h
32 *
33 * \brief Main public interface to librsync.
34 * \author Martin Pool <mbp@samba.org>
35 * \version librsync-0.9.1
36 *
37 * $Id$
38 *
39 * See \ref intro for an introduction to use of this library.
40 */
41
42#include <sys/types.h>
43
44extern char const rs_librsync_version[];
45extern char const rs_licence_string[];
46
47
48/**
49 * \brief A long integer type that can handle the largest file
50 * offsets.
51 *
52 * Perhaps this might have to be configured to be 'long long', 'long',
53 * or something else depending on the platform.
54 */
55#if SIZEOF_LONG_LONG
56typedef signed long long rs_long_t;
57#else
58typedef long rs_long_t;
59#endif
60
61
62/**
63 * \brief Log severity levels.
64 *
65 * These are the same as syslog, at least in glibc.
66 *
67 * \sa rs_trace_set_level()
68 */
69typedef enum {
70 RS_LOG_EMERG = 0, /**< System is unusable */
71 RS_LOG_ALERT = 1, /**< Action must be taken immediately */
72 RS_LOG_CRIT = 2, /**< Critical conditions */
73 RS_LOG_ERR = 3, /**< Error conditions */
74 RS_LOG_WARNING = 4, /**< Warning conditions */
75 RS_LOG_NOTICE = 5, /**< Normal but significant condition */
76 RS_LOG_INFO = 6, /**< Informational */
77 RS_LOG_DEBUG = 7 /**< Debug-level messages */
78} rs_loglevel;
79
80
81
82/**
83 * \typedef rs_trace_fn_t
84 * \brief Callback to write out log messages.
85 * \param level a syslog level.
86 * \param msg message to be logged.
87 */
88typedef void rs_trace_fn_t(int level, char const *msg);
89
90void rs_trace_set_level(rs_loglevel level);
91
92/** Set trace callback. */
93void rs_trace_to(rs_trace_fn_t *);
94
95/** Default trace callback that writes to stderr. Implements
96 * ::rs_trace_fn_t, and may be passed to rs_trace_to(). */
97void rs_trace_stderr(int level, char const *msg);
98
99/** Check whether the library was compiled with debugging trace
100 * suport. */
101int rs_supports_trace(void);
102
103
104
105/**
106 * Convert FROM_LEN bytes at FROM_BUF into a hex representation in
107 * TO_BUF, which must be twice as long plus one byte for the null
108 * terminator.
109 */
110void rs_hexify(char *to_buf, void const *from_buf, int from_len);
111
112/**
113 * Decode a base64 buffer in place. \return the number of binary
114 * bytes.
115 */
116size_t rs_unbase64(char *s);
117
118
119/**
120 * Encode a buffer as base64.
121 */
122void rs_base64(unsigned char const *buf, int n, char *out);
123
124
125/**
126 * \brief Return codes from nonblocking rsync operations.
127 */
128typedef enum {
129 RS_DONE = 0,/**< Completed successfully. */
130 RS_BLOCKED = 1, /**< Blocked waiting for more data. */
131 RS_RUNNING = 2, /**< Not yet finished or blocked.
132 * This value should never be returned
133 * to the caller. */
134
135 RS_TEST_SKIPPED = 77, /**< Test neither passed or failed. */
136
137 RS_IO_ERROR =100, /**< Error in file or network IO. */
138 RS_SYNTAX_ERROR = 101, /**< Command line syntax error. */
139 RS_MEM_ERROR =102, /**< Out of memory. */
140 RS_INPUT_ENDED = 103,/**< End of input file, possibly
141 unexpected. */
142 RS_BAD_MAGIC = 104, /**< Bad magic number at start of
143 stream. Probably not a librsync
144 file, or possibly the wrong kind of
145 file or from an incompatible
146 library version. */
147 RS_UNIMPLEMENTED = 105, /**< Author is lazy. */
148 RS_CORRUPT = 106, /**< Unbelievable value in stream. */
149 RS_INTERNAL_ERROR = 107, /**< Probably a library bug. */
150 RS_PARAM_ERROR = 108 /**< Bad value passed in to library,
151 * probably an application bug. */
152} rs_result;
153
154
155
156/**
157 * Return an English description of a ::rs_result value.
158 */
159char const *rs_strerror(rs_result r);
160
161
162/**
163 * \brief Performance statistics from a librsync encoding or decoding
164 * operation.
165 *
166 * \sa rs_format_stats(), rs_log_stats()
167 */
168typedef struct rs_stats {
169 char const *op; /**< Human-readable name of current
170 * operation. For example, "delta". */
171 int lit_cmds; /**< Number of literal commands. */
172 rs_long_t lit_bytes; /**< Number of literal bytes. */
173 rs_long_t lit_cmdbytes; /**< Number of bytes used in literal
174 * command headers. */
175
176 rs_long_t copy_cmds, copy_bytes, copy_cmdbytes;
177 rs_long_t sig_cmds, sig_bytes;
178 int false_matches;
179
180 rs_long_t sig_blocks; /**< Number of blocks described by the
181 signature. */
182
183 size_t block_len;
184
185 rs_long_t in_bytes; /**< Total bytes read from input. */
186 rs_long_t out_bytes; /**< Total bytes written to output. */
187} rs_stats_t;
188
189
190/** \typedef struct rs_mdfour rs_mdfour_t
191 *
192 * \brief MD4 message-digest accumulator.
193 *
194 * \sa rs_mdfour(), rs_mdfour_begin(), rs_mdfour_update(),
195 * rs_mdfour_result()
196 */
197typedef struct rs_mdfour {
198 int A, B, C, D;
199 int totalN;
200 int tail_len;
201 unsigned char tail[64];
202} rs_mdfour_t;
203
204#define RS_MD4_LENGTH 16
205
206typedef unsigned int rs_weak_sum_t;
207typedef unsigned char rs_strong_sum_t[RS_MD4_LENGTH];
208
209void rs_mdfour(unsigned char *out, void const *in, size_t);
210void rs_mdfour_begin(/* @out@ */ rs_mdfour_t * md);
211void rs_mdfour_update(rs_mdfour_t * md, void const *,
212 size_t n);
213void rs_mdfour_result(rs_mdfour_t * md, unsigned char *out);
214
215char *rs_format_stats(rs_stats_t const *, char *, size_t);
216
217int rs_log_stats(rs_stats_t const *stats);
218
219
220typedef struct rs_signature rs_signature_t;
221
222void rs_free_sumset(rs_signature_t *);
223void rs_sumset_dump(rs_signature_t const *);
224
225
226/**
227 * Stream through which the calling application feeds data to and from the
228 * library.
229 *
230 * On each call to rs_job_iter, the caller can make available
231 *
232 * - avail_in bytes of input data at next_in
233 * - avail_out bytes of output space at next_out
234 * - some of both
235 *
236 * Buffers must be allocated and passed in by the caller. This
237 * routine never allocates, reallocates or frees buffers.
238 *
239 * Pay attention to the meaning of the returned pointer and length
240 * values. They do \b not indicate the location and amount of
241 * returned data. Rather, if \p *out_ptr was originally set to \p
242 * out_buf, then the output data begins at \p out_buf, and has length
243 * \p *out_ptr - \p out_buf.
244 *
245 * Note also that if \p *avail_in is nonzero on return, then not all of
246 * the input data has been consumed. The caller should either provide
247 * more output buffer space and call rs_work() again passing the same
248 * \p next_in and \p avail_in, or put the remaining input data into some
249 * persistent buffer and call rs_work() with it again when there is
250 * more output space.
251 *
252 * \param next_in References a pointer which on entry should point to
253 * the start of the data to be encoded. Updated to point to the byte
254 * after the last one consumed.
255 *
256 * \param avail_in References the length of available input. Updated to
257 * be the number of unused data bytes, which will be zero if all the
258 * input was consumed. May be zero if there is no new input, but the
259 * caller just wants to drain output.
260 *
261 * \param next_out References a pointer which on entry points to the
262 * start of the output buffer. Updated to point to the byte after the
263 * last one filled.
264 *
265 * \param avail_out References the size of available output buffer.
266 * Updated to the size of unused output buffer.
267 *
268 * \return The ::rs_result that caused iteration to stop.
269 *
270 * \sa rs_buffers_t
271 * \sa \ref api_buffers
272 */
273struct rs_buffers_s {
274 char *next_in; /**< Next input byte */
275 size_t avail_in; /**< Number of bytes available at next_in */
276 int eof_in; /**< True if there is no more data
277 * after this. */
278
279 char *next_out; /**< Next output byte should be put there */
280 size_t avail_out; /**< Remaining free space at next_out */
281};
282
283/**
284 * Stream through which the calling application feeds data to and from the
285 * library.
286 *
287 * \sa struct rs_buffers_s
288 * \sa \ref api_buffers
289 */
290typedef struct rs_buffers_s rs_buffers_t;
291
292/** Default length of strong signatures, in bytes. The MD4 checksum
293 * is truncated to this size. */
294#define RS_DEFAULT_STRONG_LEN 8
295
296/** Default block length, if not determined by any other factors. */
297#define RS_DEFAULT_BLOCK_LEN 2048
298
299
300/** \typedef struct rs_job rs_job_t
301 *
302 * \brief Job of work to be done.
303 *
304 * Created by functions such as rs_sig_begin(), and then iterated
305 * over by rs_job_iter(). */
306typedef struct rs_job rs_job_t;
307
308/**
309 * Bitmask values that may be passed to the options parameter of
310 * rs_work().
311 */
312typedef enum rs_work_options {
313 RS_END = 0x01 /**< End of input file; please finish
314 * up. */
315} rs_work_options;
316
317
318rs_result rs_job_iter(rs_job_t *, rs_buffers_t *);
319
320typedef rs_result rs_driven_cb(rs_job_t *job, rs_buffers_t *buf,
321 void *opaque);
322
323rs_result rs_job_drive(rs_job_t *job, rs_buffers_t *buf,
324 rs_driven_cb in_cb, void *in_opaque,
325 rs_driven_cb out_cb, void *out_opaque);
326
327rs_result rs_job_free(rs_job_t *);
328
329int rs_accum_value(rs_job_t *, char *sum, size_t sum_len);
330
331rs_job_t *rs_sig_begin(size_t new_block_len, size_t strong_sum_len);
332
333rs_job_t *rs_delta_begin(rs_signature_t *);
334
335rs_job_t *rs_loadsig_begin(rs_signature_t **);
336
337/**
338 * \brief Callback used to retrieve parts of the basis file.
339 *
340 * \param pos Position where copying should begin.
341 *
342 * \param len On input, the amount of data that should be retrieved.
343 * Updated to show how much is actually available.
344 *
345 * \param buf On input, a buffer of at least \p *len bytes. May be
346 * updated to point to a buffer allocated by the callback if it
347 * prefers.
348 */
349typedef rs_result rs_copy_cb(void *opaque, off_t pos,
350 size_t *len, void **buf);
351
352
353
354rs_job_t *rs_patch_begin(rs_copy_cb *, void *copy_arg);
355
356
357rs_result rs_build_hash_table(rs_signature_t* sums);
358
359
360
361#ifndef RSYNC_NO_STDIO_INTERFACE
362/**
363 * Buffer sizes for file IO.
364 *
365 * You probably only need to change these in testing.
366 */
367extern int rs_inbuflen, rs_outbuflen;
368
369
370/**
371 * Calculate the MD4 sum of a file.
372 *
373 * \param result Binary (not hex) MD4 of the whole contents of the
374 * file.
375 */
376void rs_mdfour_file(FILE *in_file, char *result);
377
378rs_result rs_sig_file(FILE *old_file, FILE *sig_file,
379 size_t block_len, size_t strong_len, rs_stats_t *);
380
381rs_result rs_loadsig_file(FILE *, rs_signature_t **, rs_stats_t *);
382
383rs_result rs_file_copy_cb(void *arg, off_t pos, size_t *len, void **buf);
384
385rs_result rs_delta_file(rs_signature_t *, FILE *new_file, FILE *delta_file, rs_stats_t *);
386
387rs_result rs_patch_file(FILE *basis_file, FILE *delta_file, FILE *new_file, rs_stats_t *);
388#endif