diff options
| -rw-r--r-- | src/buf.c | 13 | ||||
| -rw-r--r-- | src/buf.h | 13 | ||||
| -rw-r--r-- | src/checksum.h | 3 | ||||
| -rw-r--r-- | src/emit.c | 13 | ||||
| -rw-r--r-- | src/emit.h | 17 | ||||
| -rw-r--r-- | src/isprefix.c | 1 | ||||
| -rw-r--r-- | src/isprefix.h | 3 | ||||
| -rw-r--r-- | src/job.c | 8 | ||||
| -rw-r--r-- | src/job.h | 8 | ||||
| -rw-r--r-- | src/mdfour.c | 18 | ||||
| -rw-r--r-- | src/mdfour.h | 20 | ||||
| -rw-r--r-- | src/netint.c | 19 | ||||
| -rw-r--r-- | src/netint.h | 23 | ||||
| -rw-r--r-- | src/patch.c | 3 | ||||
| -rw-r--r-- | src/prototab.c | 7 | ||||
| -rw-r--r-- | src/prototab.h | 6 | ||||
| -rw-r--r-- | src/rabinkarp.h | 5 | ||||
| -rw-r--r-- | src/rollsum.h | 13 | ||||
| -rw-r--r-- | src/sumset.h | 3 | ||||
| -rw-r--r-- | src/trace.c | 6 | ||||
| -rw-r--r-- | src/util.h | 3 | ||||
| -rw-r--r-- | src/whole.c | 15 | ||||
| -rw-r--r-- | src/whole.h | 20 |
23 files changed, 130 insertions, 110 deletions
@@ -23,19 +23,6 @@ | Pick a window, Jimmy, you're leaving. */ -/** \file buf.c - * Buffers that map between stdio file streams and librsync streams. - * - * As the stream consumes input and produces output, it is refilled from - * appropriate input and output FILEs. A dynamically allocated buffer of - * configurable size is used as an intermediary. - * - * \todo Perhaps be more efficient by filling the buffer on every call even if - * not yet completely empty. Check that it's really our buffer, and shuffle - * remaining data down to the front. - * - * \todo Perhaps expose a routine for shuffling the buffers. */ - #include <assert.h> #include <stdlib.h> #include <errno.h> @@ -18,6 +18,19 @@ * License along with this program; if not, write to the Free Software * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ + +/** \file buf.h + * Buffers that map between stdio file streams and librsync streams. + * + * As the stream consumes input and produces output, it is refilled from + * appropriate input and output FILEs. A dynamically allocated buffer of + * configurable size is used as an intermediary. + * + * \todo Perhaps be more efficient by filling the buffer on every call even if + * not yet completely empty. Check that it's really our buffer, and shuffle + * remaining data down to the front. + * + * \todo Perhaps expose a routine for shuffling the buffers. */ #ifndef BUF_H # define BUF_H diff --git a/src/checksum.h b/src/checksum.h index e2162b0..46ed9a4 100644 --- a/src/checksum.h +++ b/src/checksum.h @@ -18,6 +18,9 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ + +/** \file checksum.h + * Abstract wrappers around different weaksum and strongsum implementations. */ #ifndef CHECKSUM_H # define CHECKSUM_H @@ -19,12 +19,6 @@ * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ -/** \file emit.c - * encoding output routines. - * - * \todo Pluggable encoding formats: gdiff-style, rsync 24, ed (text), Delta - * HTTP. */ - #include <assert.h> #include "librsync.h" #include "emit.h" @@ -33,14 +27,12 @@ #include "prototab.h" #include "trace.h" -/** Write the magic for the start of a delta. */ void rs_emit_delta_header(rs_job_t *job) { rs_trace("emit DELTA magic"); rs_squirt_n4(job, RS_DELTA_MAGIC); } -/** Write a LITERAL command. */ void rs_emit_literal_cmd(rs_job_t *job, int len) { int cmd; @@ -70,10 +62,6 @@ void rs_emit_literal_cmd(rs_job_t *job, int len) job->stats.lit_cmdbytes += 1 + param_len; } -/** Write a COPY command for given offset and length. - * - * There is a choice of variable-length encodings, depending on the size of - * representation for the parameters. */ void rs_emit_copy_cmd(rs_job_t *job, rs_long_t where, rs_long_t len) { int cmd; @@ -113,7 +101,6 @@ void rs_emit_copy_cmd(rs_job_t *job, rs_long_t where, rs_long_t len) stats->copy_cmdbytes += 1 + where_bytes + len_bytes; } -/** Write an END command. */ void rs_emit_end_cmd(rs_job_t *job) { int cmd = RS_OP_END; @@ -20,15 +20,28 @@ */ /** \file emit.h - * How to emit commands to the client. */ + * encoding output routines. + * + * \todo Pluggable encoding formats: gdiff-style, rsync 24, ed (text), Delta + * HTTP. */ #ifndef EMIT_H # define EMIT_H # include "librsync.h" +/** Write the magic for the start of a delta. */ void rs_emit_delta_header(rs_job_t *); + +/** Write a LITERAL command. */ void rs_emit_literal_cmd(rs_job_t *, int len); -void rs_emit_end_cmd(rs_job_t *); + +/** Write a COPY command for given offset and length. + * + * There is a choice of variable-length encodings, depending on the size of + * representation for the parameters. */ void rs_emit_copy_cmd(rs_job_t *job, rs_long_t where, rs_long_t len); +/** Write an END command. */ +void rs_emit_end_cmd(rs_job_t *); + #endif /* !EMIT_H */ diff --git a/src/isprefix.c b/src/isprefix.c index e0fd2b0..aa879e7 100644 --- a/src/isprefix.c +++ b/src/isprefix.c @@ -20,7 +20,6 @@ #include "isprefix.h" -/** Return true if TIP is a prefix of ICEBERG. */ int isprefix(char const *tip, char const *iceberg) { while (*tip) { diff --git a/src/isprefix.h b/src/isprefix.h index 287a23a..9ad2499 100644 --- a/src/isprefix.h +++ b/src/isprefix.h @@ -17,6 +17,9 @@ * License along with this program; if not, write to the Free Software * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ + +/** \file isprefix.h + * String prefix text function. */ #ifndef ISPREFIX_H # define ISPREFIX_H @@ -25,14 +25,6 @@ | sheltering. */ -/** \file job.c - * Generic state-machine interface. - * - * The point of this is that we need to be able to suspend and resume - * processing at any point at which the buffers may block. - * - * \sa \ref api_streaming \sa rs_job_iter() \sa ::rs_job */ - #include <assert.h> #include <stdlib.h> #include <time.h> @@ -18,6 +18,14 @@ * License along with this program; if not, write to the Free Software * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ + +/** \file job.h + * Generic state-machine interface. + * + * The point of this is that we need to be able to suspend and resume + * processing at any point at which the buffers may block. + * + * \sa \ref api_streaming \sa rs_job_iter() \sa ::rs_job */ #ifndef JOB_H # define JOB_H diff --git a/src/mdfour.c b/src/mdfour.c index 1e9c39e..a32728b 100644 --- a/src/mdfour.c +++ b/src/mdfour.c @@ -21,24 +21,6 @@ * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ -/** \file mdfour.c - * MD4 message digest algorithm. - * - * \todo Perhaps use the MD4 routine from OpenSSL if it's installed. It's - * probably not worth the trouble. - * - * This was originally written by Andrew Tridgell for use in Samba. It was then - * modified by; - * - * 2002-06-xx: Robert Weber <robert.weber@Colorado.edu> optimisations and fixed - * >512M support. - * - * 2002-06-27: Donovan Baarda <abo@minkirri.apana.org.au> further optimisations - * and cleanups. - * - * 2004-09-09: Simon Law <sfllaw@debian.org> handle little-endian machines that - * can't do unaligned access (e.g. ia64, pa-risc). */ - #include <stdint.h> #include <string.h> #include "librsync.h" diff --git a/src/mdfour.h b/src/mdfour.h index a8e35b1..2c11d73 100644 --- a/src/mdfour.h +++ b/src/mdfour.h @@ -19,12 +19,30 @@ * License along with this program; if not, write to the Free Software * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ + +/** \file mdfour.h + * MD4 message digest algorithm. + * + * \todo Perhaps use the MD4 routine from OpenSSL if it's installed. It's + * probably not worth the trouble. + * + * This was originally written by Andrew Tridgell for use in Samba. It was then + * modified by; + * + * 2002-06-xx: Robert Weber <robert.weber@Colorado.edu> optimisations and fixed + * >512M support. + * + * 2002-06-27: Donovan Baarda <abo@minkirri.apana.org.au> further optimisations + * and cleanups. + * + * 2004-09-09: Simon Law <sfllaw@debian.org> handle little-endian machines that + * can't do unaligned access (e.g. ia64, pa-risc). */ #ifndef MDFOUR_H # define MDFOUR_H # include <stdint.h> -/** \private Internal state while computing an MD4 hash. */ +/** The rs_mdfour state type. */ struct rs_mdfour { unsigned int A, B, C, D; # ifdef UINT64_MAX diff --git a/src/netint.c b/src/netint.c index af28d89..e533b19 100644 --- a/src/netint.c +++ b/src/netint.c @@ -27,17 +27,6 @@ | -- Sun Microsystems */ -/** \file netint.c - * Network-byte-order output to the tube. - * - * All the `suck' routines return a result code. The most common values are - * RS_DONE if they have enough data, or RS_BLOCKED if there is not enough input - * to proceed. - * - * The `squirt` routines also return a result code which in theory could be - * RS_BLOCKED if there is not enough output space to proceed, but in practice - * is always RS_DONE. */ - #include <assert.h> #include "librsync.h" #include "netint.h" @@ -45,20 +34,12 @@ #define RS_MAX_INT_BYTES 8 -/** Write a single byte to a stream output. */ rs_result rs_squirt_byte(rs_job_t *job, rs_byte_t val) { rs_tube_write(job, &val, 1); return RS_DONE; } -/** Write a variable-length integer to a stream. - * - * \param job - Job of data. - * - * \param val - Value to write out. - * - * \param len - Length of integer, in bytes. */ rs_result rs_squirt_netint(rs_job_t *job, rs_long_t val, int len) { rs_byte_t buf[RS_MAX_INT_BYTES]; diff --git a/src/netint.h b/src/netint.h index 90bd508..a89021b 100644 --- a/src/netint.h +++ b/src/netint.h @@ -19,17 +19,40 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ + +/** \file netint.h + * Network-byte-order output to the tube. + * + * All the `suck' routines return a result code. The most common values are + * RS_DONE if they have enough data, or RS_BLOCKED if there is not enough input + * to proceed. + * + * The `squirt` routines also return a result code which in theory could be + * RS_BLOCKED if there is not enough output space to proceed, but in practice + * is always RS_DONE. */ #ifndef NETINT_H # define NETINT_H # include "librsync.h" +/** Write a single byte to a stream output. */ rs_result rs_squirt_byte(rs_job_t *job, rs_byte_t val); + +/** Write a variable-length integer to a stream. + * + * \param job - Job of data. + * + * \param val - Value to write out. + * + * \param len - Length of integer, in bytes. */ rs_result rs_squirt_netint(rs_job_t *job, rs_long_t val, int len); + rs_result rs_squirt_n4(rs_job_t *job, int val); rs_result rs_suck_byte(rs_job_t *job, rs_byte_t *val); + rs_result rs_suck_netint(rs_job_t *job, rs_long_t *val, int len); + rs_result rs_suck_n4(rs_job_t *job, int *val); int rs_int_len(rs_long_t val); diff --git a/src/patch.c b/src/patch.c index d4e2f8f..5fae2bb 100644 --- a/src/patch.c +++ b/src/patch.c @@ -23,6 +23,9 @@ | This is Tranquility Base. */ +/** \file patch.c + * Apply a delta to an old file to generate a new file. */ + #include <assert.h> #include <stdlib.h> #include <string.h> diff --git a/src/prototab.c b/src/prototab.c index 9d1e4b1..92a4256 100644 --- a/src/prototab.c +++ b/src/prototab.c @@ -20,13 +20,6 @@ * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ -/** \file prototab.c - * Delta file commands. - * - * This file defines an array mapping command IDs to the operation kind, - * implied literal value, and length of the first and second parameters. The - * implied value is only used if the first parameter length is zero. */ - #include "command.h" #include "prototab.h" diff --git a/src/prototab.h b/src/prototab.h index 0270700..f430e56 100644 --- a/src/prototab.h +++ b/src/prototab.h @@ -29,7 +29,11 @@ */ /** \file prototab.h - * Delta file commands. */ + * Delta file commands. + * + * This file defines an array mapping command IDs to the operation kind, + * implied literal value, and length of the first and second parameters. The + * implied value is only used if the first parameter length is zero. */ #ifndef PROTOTAB_H # define PROTOTAB_H diff --git a/src/rabinkarp.h b/src/rabinkarp.h index b97db86..dfd87f1 100644 --- a/src/rabinkarp.h +++ b/src/rabinkarp.h @@ -18,6 +18,9 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ + +/** \file rabinkarp.h + * The rabinkarp class implementation of the RabinKarp rollsum. */ #ifndef RABINKARP_H # define RABINKARP_H @@ -50,7 +53,7 @@ # define RABINKARP_ADJ 0x08104224U /** The rabinkarp_t state type. */ -typedef struct _rabinkarp { +typedef struct rabinkarp { size_t count; /**< Count of bytes included in sum. */ uint32_t hash; /**< The accumulated hash value. */ uint32_t mult; /**< The value of RABINKARP_MULT^count. */ diff --git a/src/rollsum.h b/src/rollsum.h index 07c30cc..9f33dd0 100644 --- a/src/rollsum.h +++ b/src/rollsum.h @@ -19,6 +19,9 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ + +/** \file rollsum.h + * The Rollsum class implementation of the original rsync rollsum. */ #ifndef ROLLSUM_H # define ROLLSUM_H @@ -29,11 +32,11 @@ algorithm: tridge suggests a prime number. */ # define ROLLSUM_CHAR_OFFSET 31 -/** The Rollsum struct type \private. */ -typedef struct _Rollsum { - size_t count; /* count of bytes included in sum */ - uint_fast16_t s1; /* s1 part of sum */ - uint_fast16_t s2; /* s2 part of sum */ +/** The Rollsum state type. */ +typedef struct Rollsum { + size_t count; /**< count of bytes included in sum */ + uint_fast16_t s1; /**< s1 part of sum */ + uint_fast16_t s2; /**< s2 part of sum */ } Rollsum; void RollsumUpdate(Rollsum *sum, const unsigned char *buf, size_t len); diff --git a/src/sumset.h b/src/sumset.h index 3ac2a5c..3ae1fcb 100644 --- a/src/sumset.h +++ b/src/sumset.h @@ -19,6 +19,9 @@ * License along with this program; if not, write to the Free Software * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ + +/** \file sumset.h + * The rs_signature class implementation of a file signature. */ #ifndef SUMSET_H # define SUMSET_H diff --git a/src/trace.c b/src/trace.c index 53e48b2..426e1be 100644 --- a/src/trace.c +++ b/src/trace.c @@ -26,12 +26,6 @@ | There are lumps in it. */ -/** \file trace.c - * logging and debugging output. - * - * \todo Have a bit set in the log level that says not to include the function - * name. */ - #include <stdio.h> #include <stdarg.h> #include "config.h" @@ -19,6 +19,9 @@ * License along with this program; if not, write to the Free Software * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ + +/** \file util.h + * Misc utility functions used by librsync. */ #ifndef UTIL_H # define UTIL_H diff --git a/src/whole.c b/src/whole.c index ff58155..04777f8 100644 --- a/src/whole.c +++ b/src/whole.c @@ -39,21 +39,6 @@ /** Whole file IO buffer sizes. */ LIBRSYNC_EXPORT int rs_inbuflen = 0, rs_outbuflen = 0; -/** Run a job continuously, with input to/from the two specified files. - * - * The job should already be set up, and must be freed by the caller after - * return. If rs_inbuflen or rs_outbuflen are set, they will override the - * inbuflen and outbuflen arguments. - * - * \param in_file - input file, or NULL if there is no input. - * - * \param out_file - output file, or NULL if there is no output. - * - * \param inbuflen - recommended input buffer size to use. - * - * \param outbuflen - recommended output buffer size to use. - * - * \return RS_DONE if the job completed, or otherwise an error result. */ rs_result rs_whole_run(rs_job_t *job, FILE *in_file, FILE *out_file, int inbuflen, int outbuflen) { diff --git a/src/whole.h b/src/whole.h index 98e082c..e872bc1 100644 --- a/src/whole.h +++ b/src/whole.h @@ -18,12 +18,32 @@ * License along with this program; if not, write to the Free Software * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ + +/** \file whole.h + * Whole-file API driver functions. */ #ifndef WHOLE_H # define WHOLE_H # include <stdio.h> # include "librsync.h" +/** Run a job continuously, with input to/from the two specified files. + * + * The job should already be set up, and must be freed by the caller after + * return. If rs_inbuflen or rs_outbuflen are set, they will override the + * inbuflen and outbuflen arguments. + * + * \param job - the job instance to run. + * + * \param in_file - input file, or NULL if there is no input. + * + * \param out_file - output file, or NULL if there is no output. + * + * \param inbuflen - recommended input buffer size to use. + * + * \param outbuflen - recommended output buffer size to use. + * + * \return RS_DONE if the job completed, or otherwise an error result. */ rs_result rs_whole_run(rs_job_t *job, FILE *in_file, FILE *out_file, int inbuflen, int outbuflen); |