$treeview $search $mathjax $extrastylesheet
librsync
2.0.2
$projectbrief
|
$projectbrief
|
$searchbox |
00001 /*= -*- c-basic-offset: 4; indent-tabs-mode: nil; -*- 00002 * 00003 * librsync -- library for network deltas 00004 * 00005 * Copyright 2000, 2001, 2014, 2015 by Martin Pool <mbp@sourcefrog.net> 00006 * Copyright (C) 2003 by Donovan Baarda <abo@minkirri.apana.org.au> 00007 * 00008 * This program is free software; you can redistribute it and/or modify 00009 * it under the terms of the GNU Lesser General Public License as published by 00010 * the Free Software Foundation; either version 2.1 of the License, or 00011 * (at your option) any later version. 00012 * 00013 * This program is distributed in the hope that it will be useful, 00014 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00016 * GNU Lesser General Public License for more details. 00017 * 00018 * You should have received a copy of the GNU Lesser General Public License 00019 * along with this program; if not, write to the Free Software 00020 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 00021 */ 00022 00023 /*= 00024 | You should never wear your best 00025 | trousers when you go out to fight for 00026 | freedom and liberty. 00027 | -- Henrik Ibsen 00028 */ 00029 00030 /** \file librsync.h Public header for librsync. */ 00031 00032 #ifndef _RSYNC_H 00033 # define _RSYNC_H 00034 00035 # include <sys/types.h> 00036 # include <stdio.h> 00037 # include <stdint.h> 00038 # include <time.h> 00039 00040 # ifdef __cplusplus 00041 extern "C" { 00042 # endif 00043 00044 /** Library version string. 00045 * 00046 * \sa \ref versioning */ 00047 extern char const rs_librsync_version[]; 00048 00049 /** Summary of the licence for librsync. */ 00050 extern char const rs_licence_string[]; 00051 00052 typedef uint8_t rs_byte_t; 00053 typedef intmax_t rs_long_t; 00054 00055 /*= 00056 | "The IETF already has more than enough 00057 | RFCs that codify the obvious, make 00058 | stupidity illegal, support truth, 00059 | justice, and the IETF way, and generally 00060 | demonstrate the author is a brilliant and 00061 | valuable Contributor to The Standards 00062 | Process." 00063 | -- Vernon Schryver 00064 */ 00065 00066 /** A uint32 magic number, emitted in bigendian/network order at the start of 00067 * librsync files. */ 00068 typedef enum { 00069 /** A delta file. 00070 * 00071 * At present, there's only one delta format. 00072 * 00073 * The four-byte literal \c "rs\x026". */ 00074 RS_DELTA_MAGIC = 0x72730236, 00075 00076 /** A signature file with MD4 signatures. 00077 * 00078 * Backward compatible with librsync < 1.0, but strongly deprecated because 00079 * it creates a security vulnerability on files containing partly untrusted 00080 * data. See <https://github.com/librsync/librsync/issues/5>. 00081 * 00082 * The four-byte literal \c "rs\x016". 00083 * 00084 * \sa rs_sig_begin() */ 00085 RS_MD4_SIG_MAGIC = 0x72730136, 00086 00087 /** A signature file using the BLAKE2 hash. Supported from librsync 1.0. 00088 * 00089 * The four-byte literal \c "rs\x017". 00090 * 00091 * \sa rs_sig_begin() */ 00092 RS_BLAKE2_SIG_MAGIC = 0x72730137 00093 } rs_magic_number; 00094 00095 /** Log severity levels. 00096 * 00097 * These are the same as syslog, at least in glibc. 00098 * 00099 * \sa rs_trace_set_level() \sa \ref api_trace */ 00100 typedef enum { 00101 RS_LOG_EMERG = 0, /**< System is unusable */ 00102 RS_LOG_ALERT = 1, /**< Action must be taken immediately */ 00103 RS_LOG_CRIT = 2, /**< Critical conditions */ 00104 RS_LOG_ERR = 3, /**< Error conditions */ 00105 RS_LOG_WARNING = 4, /**< Warning conditions */ 00106 RS_LOG_NOTICE = 5, /**< Normal but significant condition */ 00107 RS_LOG_INFO = 6, /**< Informational */ 00108 RS_LOG_DEBUG = 7 /**< Debug-level messages */ 00109 } rs_loglevel; 00110 00111 /** \typedef rs_trace_fn_t Callback to write out log messages. 00112 * 00113 * \param level a syslog level. 00114 * 00115 * \param msg message to be logged. 00116 * 00117 * \sa \ref api_trace */ 00118 typedef void rs_trace_fn_t(rs_loglevel level, char const *msg); 00119 00120 /** Set the least important message severity that will be output. 00121 * 00122 * \sa \ref api_trace */ 00123 void rs_trace_set_level(rs_loglevel level); 00124 00125 /** Set trace callback. 00126 * 00127 * \sa \ref api_trace */ 00128 void rs_trace_to(rs_trace_fn_t *); 00129 00130 /** Default trace callback that writes to stderr. 00131 * 00132 * Implements ::rs_trace_fn_t, and may be passed to rs_trace_to(). 00133 * 00134 * \sa \ref api_trace */ 00135 void rs_trace_stderr(rs_loglevel level, char const *msg); 00136 00137 /** Check whether the library was compiled with debugging trace. 00138 * 00139 * \returns True if the library contains trace code; otherwise false. 00140 * 00141 * If this returns false, then trying to turn trace on will achieve nothing. 00142 * 00143 * \sa \ref api_trace */ 00144 int rs_supports_trace(void); 00145 00146 /** Convert \p from_len bytes at \p from_buf into a hex representation in \p 00147 * to_buf, which must be twice as long plus one byte for the null terminator. */ 00148 void rs_hexify(char *to_buf, void const *from_buf, int from_len); 00149 00150 /** Decode a base64 buffer in place. 00151 * 00152 * \returns The number of binary bytes. */ 00153 size_t rs_unbase64(char *s); 00154 00155 /** Encode a buffer as base64. */ 00156 void rs_base64(unsigned char const *buf, int n, char *out); 00157 00158 /** \enum rs_result Return codes from nonblocking rsync operations. 00159 * 00160 * \sa rs_strerror() \sa api_callbacks */ 00161 typedef enum rs_result { 00162 RS_DONE = 0, /**< Completed successfully. */ 00163 RS_BLOCKED = 1, /**< Blocked waiting for more data. */ 00164 RS_RUNNING = 2, /**< The job is still running, and not yet 00165 * finished or blocked. (This value should 00166 * never be seen by the application.) */ 00167 RS_TEST_SKIPPED = 77, /**< Test neither passed or failed. */ 00168 RS_IO_ERROR = 100, /**< Error in file or network IO. */ 00169 RS_SYNTAX_ERROR = 101, /**< Command line syntax error. */ 00170 RS_MEM_ERROR = 102, /**< Out of memory. */ 00171 RS_INPUT_ENDED = 103, /**< Unexpected end of input file, perhaps due 00172 * to a truncated file or dropped network 00173 * connection. */ 00174 RS_BAD_MAGIC = 104, /**< Bad magic number at start of stream. 00175 * Probably not a librsync file, or possibly 00176 * the wrong kind of file or from an 00177 * incompatible library version. */ 00178 RS_UNIMPLEMENTED = 105, /**< Author is lazy. */ 00179 RS_CORRUPT = 106, /**< Unbelievable value in stream. */ 00180 RS_INTERNAL_ERROR = 107, /**< Probably a library bug. */ 00181 RS_PARAM_ERROR = 108 /**< Bad value passed in to library, probably 00182 * an application bug. */ 00183 } rs_result; 00184 00185 /** Return an English description of a ::rs_result value. */ 00186 char const *rs_strerror(rs_result r); 00187 00188 /** Performance statistics from a librsync encoding or decoding operation. 00189 * 00190 * \sa api_stats \sa rs_format_stats() \sa rs_log_stats() */ 00191 typedef struct rs_stats { 00192 char const *op; /**< Human-readable name of current operation. 00193 * For example, "delta". */ 00194 int lit_cmds; /**< Number of literal commands. */ 00195 rs_long_t lit_bytes; /**< Number of literal bytes. */ 00196 rs_long_t lit_cmdbytes; /**< Number of bytes used in literal command 00197 * headers. */ 00198 00199 rs_long_t copy_cmds, copy_bytes, copy_cmdbytes; 00200 rs_long_t sig_cmds, sig_bytes; 00201 int false_matches; 00202 00203 rs_long_t sig_blocks; /**< Number of blocks described by the 00204 * signature. */ 00205 00206 size_t block_len; 00207 00208 rs_long_t in_bytes; /**< Total bytes read from input. */ 00209 rs_long_t out_bytes; /**< Total bytes written to output. */ 00210 00211 time_t start, end; 00212 } rs_stats_t; 00213 00214 /** \typedef struct rs_mdfour rs_mdfour_t 00215 * 00216 * \brief MD4 message-digest accumulator. 00217 * 00218 * \sa rs_mdfour(), rs_mdfour_begin(), rs_mdfour_update(), rs_mdfour_result() */ 00219 typedef struct rs_mdfour rs_mdfour_t; 00220 00221 extern const int RS_MD4_SUM_LENGTH, RS_BLAKE2_SUM_LENGTH; 00222 00223 # define RS_MAX_STRONG_SUM_LENGTH 32 00224 00225 typedef uint32_t rs_weak_sum_t; 00226 typedef unsigned char rs_strong_sum_t[RS_MAX_STRONG_SUM_LENGTH]; 00227 00228 void rs_mdfour(unsigned char *out, void const *in, size_t); 00229 void rs_mdfour_begin( /* @out@ */ rs_mdfour_t *md); 00230 00231 /** Feed some data into the MD4 accumulator. 00232 * 00233 * \param md MD4 accumulator. 00234 * 00235 * \param in_void Data to add. 00236 * 00237 * \param n Number of bytes fed in. */ 00238 void rs_mdfour_update(rs_mdfour_t *md, void const *in_void, size_t n); 00239 void rs_mdfour_result(rs_mdfour_t *md, unsigned char *out); 00240 00241 /** Return a human-readable representation of statistics. 00242 * 00243 * The string is truncated if it does not fit. 100 characters should be 00244 * sufficient space. 00245 * 00246 * \param stats Statistics from an encoding or decoding operation. 00247 * 00248 * \param buf Buffer to receive result. 00249 * 00250 * \param size Size of buffer. 00251 * 00252 * \return \p buf. 00253 * 00254 * \sa \ref api_stats */ 00255 char *rs_format_stats(rs_stats_t const *stats, char *buf, size_t size); 00256 00257 /** Write statistics into the current log as text. 00258 * 00259 * \sa \ref api_stats \sa \ref api_trace */ 00260 int rs_log_stats(rs_stats_t const *stats); 00261 00262 /** \typedef rs_signature_t */ 00263 typedef struct rs_signature rs_signature_t; 00264 00265 /** Deep deallocation of checksums. */ 00266 void rs_free_sumset(rs_signature_t *); 00267 00268 /** Dump signatures to the log. */ 00269 void rs_sumset_dump(rs_signature_t const *); 00270 00271 /** Description of input and output buffers. 00272 * 00273 * On each call to ::rs_job_iter(), the caller can make available 00274 * 00275 * - #avail_in bytes of input data at #next_in 00276 * 00277 * - #avail_out bytes of output space at #next_out 00278 * 00279 * - or some of both 00280 * 00281 * Buffers must be allocated and passed in by the caller. 00282 * 00283 * On input, the buffers structure must contain the address and length of the 00284 * input and output buffers. The library updates these values to indicate the 00285 * amount of \b remaining buffer. So, on return, #avail_out is not the amount 00286 * of output data produced, but rather the amount of output buffer space still 00287 * available. 00288 * 00289 * This means that the values on return are consistent with the values on 00290 * entry, and suitable to be passed in on a second call, but they don't 00291 * directly tell you how much output data was produced. 00292 * 00293 * Note also that if *#avail_in is nonzero on return, then not all of the input 00294 * data has been consumed. The caller should either provide more output buffer 00295 * space and call ::rs_job_iter() again passing the same #next_in and 00296 * #avail_in, or put the remaining input data into some persistent buffer and 00297 * call rs_job_iter() with it again when there is more output space. 00298 * 00299 * \sa rs_job_iter() */ 00300 struct rs_buffers_s { 00301 /** Next input byte. 00302 * 00303 * References a pointer which on entry should point to the start of the 00304 * data to be encoded. Updated to point to the byte after the last one 00305 * consumed. */ 00306 char *next_in; 00307 00308 /** Number of bytes available at next_in. 00309 * 00310 * References the length of available input. Updated to be the number of 00311 * unused data bytes, which will be zero if all the input was consumed. May 00312 * be zero if there is no new input, but the caller just wants to drain 00313 * output. */ 00314 size_t avail_in; 00315 00316 /** True if there is no more data after this. */ 00317 int eof_in; 00318 00319 /** Next output byte should be put there. 00320 * 00321 * References a pointer which on entry points to the start of the output 00322 * buffer. Updated to point to the byte after the last one filled. */ 00323 char *next_out; 00324 00325 /** Remaining free space at next_out. 00326 * 00327 * References the size of available output buffer. Updated to the size of 00328 * unused output buffer. */ 00329 size_t avail_out; 00330 }; 00331 00332 /** \sa ::rs_buffers_s */ 00333 typedef struct rs_buffers_s rs_buffers_t; 00334 00335 /** Default block length, if not determined by any other factors. */ 00336 # define RS_DEFAULT_BLOCK_LEN 2048 00337 00338 /** Job of work to be done. 00339 * 00340 * Created by functions such as rs_sig_begin(), and then iterated over by 00341 * rs_job_iter(). 00342 * 00343 * The contents are opaque to the application, and instances are always 00344 * allocated by the library. 00345 * 00346 * \sa \ref api_streaming \sa rs_job */ 00347 typedef struct rs_job rs_job_t; 00348 00349 /** Run a ::rs_job state machine until it blocks (::RS_BLOCKED), returns an 00350 * error, or completes (::RS_DONE). 00351 * 00352 * \param job Description of job state. 00353 * 00354 * \param buffers Pointer to structure describing input and output buffers. 00355 * 00356 * \return The ::rs_result that caused iteration to stop. 00357 * 00358 * \c buffers->eof_in should be true if there is no more data after what's in 00359 * the input buffer. The final block checksum will run across whatever's in 00360 * there, without trying to accumulate anything else. 00361 * 00362 * \sa \ref api_streaming */ 00363 rs_result rs_job_iter(rs_job_t *job, rs_buffers_t *buffers); 00364 00365 /** Type of application-supplied function for rs_job_drive(). 00366 * 00367 * \sa \ref api_pull */ 00368 typedef rs_result rs_driven_cb(rs_job_t *job, rs_buffers_t *buf, 00369 void *opaque); 00370 00371 /** Actively process a job, by making callbacks to fill and empty the buffers 00372 * until the job is done. */ 00373 rs_result rs_job_drive(rs_job_t *job, rs_buffers_t *buf, rs_driven_cb in_cb, 00374 void *in_opaque, rs_driven_cb out_cb, void *out_opaque); 00375 00376 /** Return a pointer to the statistics in a job. */ 00377 const rs_stats_t *rs_job_statistics(rs_job_t *job); 00378 00379 /** Deallocate job state. */ 00380 rs_result rs_job_free(rs_job_t *); 00381 00382 /** Start generating a signature. 00383 * 00384 * \return A new rs_job_t into which the old file data can be passed. 00385 * 00386 * \param sig_magic Indicates the version of signature file format to generate. 00387 * See ::rs_magic_number. 00388 * 00389 * \param new_block_len Size of checksum blocks. Larger values make the 00390 * signature shorter, and the delta longer. 00391 * 00392 * \param strong_sum_len If non-zero, truncate the strong signatures to this 00393 * many bytes, to make the signature shorter. It's recommended you leave this 00394 * at zero to get the full strength. 00395 * 00396 * \sa rs_sig_file() */ 00397 rs_job_t *rs_sig_begin(size_t new_block_len, size_t strong_sum_len, 00398 rs_magic_number sig_magic); 00399 00400 /** Prepare to compute a streaming delta. 00401 * 00402 * \todo Add a version of this that takes a ::rs_magic_number controlling the 00403 * delta format. */ 00404 rs_job_t *rs_delta_begin(rs_signature_t *); 00405 00406 /** Read a signature from a file into an ::rs_signature structure in memory. 00407 * 00408 * Once there, it can be used to generate a delta to a newer version of the 00409 * file. 00410 * 00411 * \note After loading the signatures, you must call \ref rs_build_hash_table() 00412 * before you can use them. */ 00413 rs_job_t *rs_loadsig_begin(rs_signature_t **); 00414 00415 /** Call this after loading a signature to index it. 00416 * 00417 * Use rs_free_sumset() to release it after use. */ 00418 rs_result rs_build_hash_table(rs_signature_t *sums); 00419 00420 /** Callback used to retrieve parts of the basis file. 00421 * 00422 * \param pos Position where copying should begin. 00423 * 00424 * \param len On input, the amount of data that should be retrieved. Updated to 00425 * show how much is actually available, but should not be greater than the 00426 * input value. 00427 * 00428 * \param buf On input, a buffer of at least \p *len bytes. May be updated to 00429 * point to a buffer allocated by the callback if it prefers. */ 00430 typedef rs_result rs_copy_cb(void *opaque, rs_long_t pos, size_t *len, 00431 void **buf); 00432 00433 /** Apply a \a delta to a \a basis file to recreate the \a new file. 00434 * 00435 * This gives you back a ::rs_job_t object, which can be cranked by calling 00436 * rs_job_iter() and updating the stream pointers. When finished, call 00437 * rs_job_free() to dispose of it. 00438 * 00439 * \param copy_cb Callback used to retrieve content from the basis file. 00440 * 00441 * \param copy_arg Opaque environment pointer passed through to the callback. 00442 * 00443 * \todo As output is produced, accumulate the MD4 checksum of the output. Then 00444 * if we find a CHECKSUM command we can check it's contents against the output. 00445 * 00446 * \todo Implement COPY commands. 00447 * 00448 * \sa rs_patch_file() \sa \ref api_streaming */ 00449 rs_job_t *rs_patch_begin(rs_copy_cb * copy_cb, void *copy_arg); 00450 00451 # ifndef RSYNC_NO_STDIO_INTERFACE 00452 # include <stdio.h> 00453 00454 /** Buffer sizes for file IO. 00455 * 00456 * The default 0 means use the recommended buffer size for the operation being 00457 * performed, any other value will override the recommended sizes. You probably 00458 * only need to change these in testing. */ 00459 extern int rs_inbuflen, rs_outbuflen; 00460 00461 /** Generate the signature of a basis file, and write it out to another. 00462 * 00463 * \param old_file Stdio readable file whose signature will be generated. 00464 * 00465 * \param sig_file Writable stdio file to which the signature will be written./ 00466 * 00467 * \param block_len block size for signature generation, in bytes 00468 * 00469 * \param strong_len truncated length of strong checksums, in bytes 00470 * 00471 * \param sig_magic A signature magic number indicating what format to use. 00472 * 00473 * \param stats Optional pointer to receive statistics. 00474 * 00475 * \sa \ref api_whole */ 00476 rs_result rs_sig_file(FILE *old_file, FILE *sig_file, size_t block_len, 00477 size_t strong_len, rs_magic_number sig_magic, 00478 rs_stats_t *stats); 00479 00480 /** Load signatures from a signature file into memory. 00481 * 00482 * \param sig_file Readable stdio file from which the signature will be read. 00483 * 00484 * \param sumset on return points to the newly allocated structure. 00485 * 00486 * \param stats Optional pointer to receive statistics. 00487 * 00488 * \sa \ref api_whole */ 00489 rs_result rs_loadsig_file(FILE *sig_file, rs_signature_t **sumset, 00490 rs_stats_t *stats); 00491 00492 /** ::rs_copy_cb that reads from a stdio file. */ 00493 rs_result rs_file_copy_cb(void *arg, rs_long_t pos, size_t *len, void **buf); 00494 00495 /** Generate a delta between a signature and a new file into a delta file. 00496 * 00497 * \sa \ref api_whole */ 00498 rs_result rs_delta_file(rs_signature_t *, FILE *new_file, FILE *delta_file, 00499 rs_stats_t *); 00500 00501 /** Apply a patch, relative to a basis, into a new file. 00502 * 00503 * \sa \ref api_whole */ 00504 rs_result rs_patch_file(FILE *basis_file, FILE *delta_file, FILE *new_file, 00505 rs_stats_t *); 00506 # endif /* !RSYNC_NO_STDIO_INTERFACE */ 00507 00508 # ifdef __cplusplus 00509 } /* extern "C" */ 00510 # endif 00511 00512 #endif /* !_RSYNC_H */