Merge branch 'master' into dev/sigparms1

1 files changed, 265 insertions, 385 deletions

diff --git a/src/librsync.h b/src/librsync.h
index e606a79..e7e513b 100644
--- a/src/librsync.h
+++ b/src/librsync.h
@@ -1,4 +1,4 @@
-/*=                    -*- c-basic-offset: 4; indent-tabs-mode: nil; -*-
+/*= -*- c-basic-offset: 4; indent-tabs-mode: nil; -*-
  *
  * librsync -- library for network deltas
  *
@@ -20,45 +20,39 @@
  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  */
 
-                              /*
+                              /*=
                                | You should never wear your best
                                | trousers when you go out to fight for
                                | freedom and liberty.
                                |        -- Henrik Ibsen
                                */
 
-
-/*!
- * \file librsync.h
- * \brief Public header for librsync.
- */
+/** \file librsync.h Public header for librsync. */
 
 #ifndef _RSYNC_H
-#define _RSYNC_H
+#  define _RSYNC_H
 
-#include <sys/types.h>
-#include <stdio.h>
-#include <stdint.h>
-#include <time.h>
+#  include <sys/types.h>
+#  include <stdio.h>
+#  include <stdint.h>
+#  include <time.h>
 
-#ifdef __cplusplus
+#  ifdef __cplusplus
 extern "C" {
-#endif
+#  endif
 
 /** Library version string.
- * \see \ref versioning
- */
+ *
+ * \sa \ref versioning */
 extern char const rs_librsync_version[];
 
-/** Summary of the licence for librsync.
- */
+/** Summary of the licence for librsync. */
 extern char const rs_licence_string[];
 
 typedef uint8_t rs_byte_t;
 typedef intmax_t rs_long_t;
 
-
-                          /*
+                          /*=
                            | "The IETF already has more than enough
                            | RFCs that codify the obvious, make
                            | stupidity illegal, support truth,
@@ -69,338 +63,273 @@ typedef intmax_t rs_long_t;
                            |     -- Vernon Schryver
                            */
 
-
-/**
- * A uint32 magic number, emitted in bigendian/network order at the start of
- * librsync files.
- **/
+/** A uint32 magic number, emitted in bigendian/network order at the start of
+ * librsync files. */
 typedef enum {
-    /**
-     * A delta file.
+    /** A delta file.
      *
      * At present, there's only one delta format.
      *
-     * The four-byte literal \c "rs\x026".
-     **/
-    RS_DELTA_MAGIC          = 0x72730236,
+     * The four-byte literal \c "rs\x026". */
+    RS_DELTA_MAGIC = 0x72730236,
 
-    /**
-     * A signature file with MD4 signatures.
+    /** 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>.
+     * 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 \c "rs\x016".
      *
-     * \see rs_sig_begin()
-     **/
-    RS_MD4_SIG_MAGIC        = 0x72730136,
+     * \sa rs_sig_begin() */
+    RS_MD4_SIG_MAGIC = 0x72730136,
 
-    /**
-     * A signature file using the BLAKE2 hash. Supported from librsync 1.0.
+    /** A signature file using the BLAKE2 hash. Supported from librsync 1.0.
      *
      * The four-byte literal \c "rs\x017".
      *
-     * \see rs_sig_begin()
-     **/
-    RS_BLAKE2_SIG_MAGIC     = 0x72730137
+     * \sa rs_sig_begin() */
+    RS_BLAKE2_SIG_MAGIC = 0x72730137
 } rs_magic_number;
 
-
-/**
- * \brief Log severity levels.
+/** Log severity levels.
  *
  * These are the same as syslog, at least in glibc.
  *
- * \sa rs_trace_set_level()
- * \sa \ref api_trace
- */
+ * \sa rs_trace_set_level() \sa \ref api_trace */
 typedef enum {
-    RS_LOG_EMERG         = 0,   /**< System is unusable */
-    RS_LOG_ALERT         = 1,   /**< Action must be taken immediately */
-    RS_LOG_CRIT          = 2,   /**< Critical conditions */
-    RS_LOG_ERR           = 3,   /**< Error conditions */
-    RS_LOG_WARNING       = 4,   /**< Warning conditions */
-    RS_LOG_NOTICE        = 5,   /**< Normal but significant condition */
-    RS_LOG_INFO          = 6,   /**< Informational */
-    RS_LOG_DEBUG         = 7    /**< Debug-level messages */
+    RS_LOG_EMERG = 0,           /**< System is unusable */
+    RS_LOG_ALERT = 1,           /**< Action must be taken immediately */
+    RS_LOG_CRIT = 2,            /**< Critical conditions */
+    RS_LOG_ERR = 3,             /**< Error conditions */
+    RS_LOG_WARNING = 4,         /**< Warning conditions */
+    RS_LOG_NOTICE = 5,          /**< Normal but significant condition */
+    RS_LOG_INFO = 6,            /**< Informational */
+    RS_LOG_DEBUG = 7            /**< Debug-level messages */
 } rs_loglevel;
 
-
-/**
- * \typedef rs_trace_fn_t
- * \brief Callback to write out log messages.
+/** \typedef rs_trace_fn_t Callback to write out log messages.
+ *
  * \param level a syslog level.
+ *
  * \param msg message to be logged.
- * \sa \ref api_trace
- */
-typedef void    rs_trace_fn_t(rs_loglevel level, char const *msg);
+ *
+ * \sa \ref api_trace */
+typedef void rs_trace_fn_t(rs_loglevel level, char const *msg);
 
-/**
- * Set the least important message severity that will be output.
- * \sa \ref api_trace
- */
-void            rs_trace_set_level(rs_loglevel level);
+/** Set the least important message severity that will be output.
+ *
+ * \sa \ref api_trace */
+void rs_trace_set_level(rs_loglevel level);
 
 /** Set trace callback.
- * \sa \ref api_trace
- */
-void            rs_trace_to(rs_trace_fn_t *);
+ *
+ * \sa \ref api_trace */
+void rs_trace_to(rs_trace_fn_t *);
 
-/** Default trace callback that writes to stderr.  Implements
- * ::rs_trace_fn_t, and may be passed to rs_trace_to().
- * \sa \ref api_trace
- */
-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().
+ *
+ * \sa \ref api_trace */
+void rs_trace_stderr(rs_loglevel level, char const *msg);
 
-/** Check whether the library was compiled with debugging trace
+/** 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.
- * \sa \ref api_trace
- */
-int             rs_supports_trace(void);
+ *
+ * If this returns false, then trying to turn trace on will achieve nothing.
+ *
+ * \sa \ref api_trace */
+int rs_supports_trace(void);
 
-/**
- * Convert \p from_len bytes at \p from_buf into a hex representation in
- * \p to_buf, which must be twice as long plus one byte for the null
- * terminator.
- */
-void     rs_hexify(char *to_buf, void const *from_buf, int from_len);
+/** Convert \p from_len bytes at \p from_buf into a hex representation in \p
+ * to_buf, which must be twice as long plus one byte for the null terminator. */
+void rs_hexify(char *to_buf, void const *from_buf, int from_len);
 
-/**
- * Decode a base64 buffer in place.
+/** Decode a base64 buffer in place.
  *
- * \returns The number of binary bytes.
- */
+ * \returns The number of binary bytes. */
 size_t rs_unbase64(char *s);
 
-
-/**
- * Encode a buffer as base64.
- */
+/** Encode a buffer as base64. */
 void rs_base64(unsigned char const *buf, int n, char *out);
 
-
-/**
- * \enum rs_result
- * \brief Return codes from nonblocking rsync operations.
- * \see rs_strerror()
- * \see api_callbacks
- */
+/** \enum rs_result Return codes from nonblocking rsync operations.
+ *
+ * \sa rs_strerror() \sa api_callbacks */
 typedef enum rs_result {
-    RS_DONE =        0,    /**< Completed successfully. */
-    RS_BLOCKED =    1,     /**< Blocked waiting for more data. */
-
-    /** The job is still running, and not yet finished or blocked.
-     * (This value should never be seen by the application.) */
-    RS_RUNNING  =       2,
-
-    RS_TEST_SKIPPED =   77,     /**< Test neither passed or failed. */
-
-    RS_IO_ERROR =    100,    /**< Error in file or network IO. */
-    RS_SYNTAX_ERROR =   101,    /**< Command line syntax error. */
-    RS_MEM_ERROR =    102,    /**< Out of memory. */
-    /** Unexpected end of input file, perhaps due to a truncated file
-     * or dropped network connection. */
-    RS_INPUT_ENDED =    103,
-    RS_BAD_MAGIC =      104,    /**< 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 =  105,    /**< Author is lazy. */
-    RS_CORRUPT =        106,    /**< Unbelievable value in stream. */
+    RS_DONE = 0,                /**< Completed successfully. */
+    RS_BLOCKED = 1,             /**< Blocked waiting for more data. */
+    RS_RUNNING = 2,             /**< The job is still running, and not yet
+                                 * finished or blocked. (This value should
+                                 * never be seen by the application.) */
+    RS_TEST_SKIPPED = 77,       /**< Test neither passed or failed. */
+    RS_IO_ERROR = 100,          /**< Error in file or network IO. */
+    RS_SYNTAX_ERROR = 101,      /**< Command line syntax error. */
+    RS_MEM_ERROR = 102,         /**< Out of memory. */
+    RS_INPUT_ENDED = 103,       /**< Unexpected end of input file, perhaps due
+                                 * to a truncated file or dropped network
+                                 * connection. */
+    RS_BAD_MAGIC = 104,         /**< 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 = 105,     /**< Author is lazy. */
+    RS_CORRUPT = 106,           /**< Unbelievable value in stream. */
     RS_INTERNAL_ERROR = 107,    /**< Probably a library bug. */
-    RS_PARAM_ERROR =    108     /**< Bad value passed in to library,
-                                 * probably an application bug. */
+    RS_PARAM_ERROR = 108        /**< Bad value passed in to library, probably
+                                 * an application bug. */
 } rs_result;
 
-
-/**
- * Return an English description of a ::rs_result value.
- */
+/** Return an English description of a ::rs_result value. */
 char const *rs_strerror(rs_result r);
 
-
-/**
- * \brief Performance statistics from a librsync encoding or decoding
- * operation.
+/** Performance statistics from a librsync encoding or decoding operation.
  *
- * \sa api_stats
- * \sa rs_format_stats()
- * \sa rs_log_stats()
- */
+ * \sa api_stats \sa rs_format_stats() \sa rs_log_stats() */
 typedef struct rs_stats {
-    char const     *op;     /**< Human-readable name of current
-                             * operation.  For example, "delta". */
-    int             lit_cmds;   /**< Number of literal commands. */
-    rs_long_t       lit_bytes;  /**< Number of literal bytes. */
-    rs_long_t       lit_cmdbytes; /**< Number of bytes used in literal
-                                   * command headers. */
+    char const *op;             /**< Human-readable name of current operation.
+                                 * For example, "delta". */
+    int lit_cmds;               /**< Number of literal commands. */
+    rs_long_t lit_bytes;        /**< Number of literal bytes. */
+    rs_long_t lit_cmdbytes;     /**< Number of bytes used in literal command
+                                 * headers. */
 
-    rs_long_t       copy_cmds, copy_bytes, copy_cmdbytes;
-    rs_long_t       sig_cmds, sig_bytes;
-    int             false_matches;
+    rs_long_t copy_cmds, copy_bytes, copy_cmdbytes;
+    rs_long_t sig_cmds, sig_bytes;
+    int false_matches;
 
-    rs_long_t       sig_blocks; /**< Number of blocks described by the
-                                   signature. */
+    rs_long_t sig_blocks;       /**< Number of blocks described by the
+                                 * signature. */
 
-    size_t          block_len;
+    size_t block_len;
 
-    rs_long_t       in_bytes;   /**< Total bytes read from input. */
-    rs_long_t       out_bytes;  /**< Total bytes written to output. */
+    rs_long_t in_bytes;         /**< Total bytes read from input. */
+    rs_long_t out_bytes;        /**< Total bytes written to output. */
 
-    time_t          start, end;
+    time_t start, end;
 } rs_stats_t;
 
-
 /** \typedef struct rs_mdfour rs_mdfour_t
  *
  * \brief MD4 message-digest accumulator.
  *
- * \sa rs_mdfour(), rs_mdfour_begin(), rs_mdfour_update(),
- * rs_mdfour_result()
- */
+ * \sa rs_mdfour(), rs_mdfour_begin(), rs_mdfour_update(), rs_mdfour_result() */
 typedef struct rs_mdfour rs_mdfour_t;
 
 extern const int RS_MD4_SUM_LENGTH, RS_BLAKE2_SUM_LENGTH;
 
-#define RS_MAX_STRONG_SUM_LENGTH 32
+#  define RS_MAX_STRONG_SUM_LENGTH 32
 
 typedef uint32_t rs_weak_sum_t;
 typedef unsigned char rs_strong_sum_t[RS_MAX_STRONG_SUM_LENGTH];
 
-void            rs_mdfour(unsigned char *out, void const *in, size_t);
-void            rs_mdfour_begin(/* @out@ */ rs_mdfour_t * md);
+void rs_mdfour(unsigned char *out, void const *in, size_t);
+void rs_mdfour_begin( /* @out@ */ rs_mdfour_t *md);
 
-/**
- * Feed some data into the MD4 accumulator.
+/** Feed some data into the MD4 accumulator.
+ *
+ * \param md MD4 accumulator.
  *
- * \param md  MD4 accumulator.
  * \param in_void Data to add.
- * \param n   Number of bytes fed in.
- */
-void            rs_mdfour_update(rs_mdfour_t * md, void const *in_void,
-                 size_t n);
-void rs_mdfour_result(rs_mdfour_t * md, unsigned char *out);
+ *
+ * \param n Number of bytes fed in. */
+void rs_mdfour_update(rs_mdfour_t *md, void const *in_void, size_t n);
+void rs_mdfour_result(rs_mdfour_t *md, unsigned char *out);
 
-/**
- * \brief Return a human-readable representation of statistics.
+/** Return a human-readable representation of statistics.
  *
- * The string is truncated if it does not fit.  100 characters should
- * be sufficient space.
+ * The string is truncated if it does not fit.  100 characters should be
+ * sufficient space.
  *
  * \param stats Statistics from an encoding or decoding operation.
  *
  * \param buf Buffer to receive result.
+ *
  * \param size Size of buffer.
+ *
  * \return \p buf.
- * \see \ref api_stats
- */
+ *
+ * \sa \ref api_stats */
 char *rs_format_stats(rs_stats_t const *stats, char *buf, size_t size);
 
-/**
- * Write statistics into the current log as text.
+/** Write statistics into the current log as text.
  *
- * \see \ref api_stats
- * \see \ref api_trace
- */
+ * \sa \ref api_stats \sa \ref api_trace */
 int rs_log_stats(rs_stats_t const *stats);
 
-
-/**
- * \typedef rs_signature_t
- */
+/** \typedef rs_signature_t */
 typedef struct rs_signature rs_signature_t;
 
-/**
- * Deep deallocation of checksums.
- */
+/** Deep deallocation of checksums. */
 void rs_free_sumset(rs_signature_t *);
 
-/**
- * Dump signatures to the log.
- */
+/** Dump signatures to the log. */
 void rs_sumset_dump(rs_signature_t const *);
 
-
-/**
- * Description of input and output buffers.
+/** Description of input and output buffers.
  *
  * On each call to ::rs_job_iter(), the caller can make available
  *
- *  - #avail_in bytes of input data at #next_in
- *  - #avail_out bytes of output space at #next_out
- *  - or some of both
+ * - #avail_in bytes of input data at #next_in
+ *
+ * - #avail_out bytes of output space at #next_out
+ *
+ * - or some of both
  *
  * Buffers must be allocated and passed in by the caller.
  *
- * On input, the buffers structure must contain the address and length of
- * the input and output buffers.  The library updates these values to
- * indicate the amount of \b remaining buffer.  So, on return,
- * #avail_out is not the amount of output data produced, but rather the
- * amount of output buffer space still available.
- *
- * This means that the values on
- * return are consistent with the values on entry, and suitable to be passed
- * in on a second call, but they don't directly tell you how much output
- * data was produced.
- *
- * Note also that if *#avail_in is nonzero on return, then not all of
- * the input data has been consumed.  The caller should either provide
- * more output buffer space and call ::rs_job_iter() again passing the same
- * #next_in and #avail_in, or put the remaining input data into some
- * persistent buffer and call rs_job_iter() with it again when there is
- * more output space.
- *
- * \sa rs_job_iter()
- */
+ * On input, the buffers structure must contain the address and length of the
+ * input and output buffers.  The library updates these values to indicate the
+ * amount of \b remaining buffer.  So, on return, #avail_out is not the amount
+ * of output data produced, but rather the amount of output buffer space still
+ * available.
+ *
+ * This means that the values on return are consistent with the values on
+ * entry, and suitable to be passed in on a second call, but they don't
+ * directly tell you how much output data was produced.
+ *
+ * Note also that if *#avail_in is nonzero on return, then not all of the input
+ * data has been consumed.  The caller should either provide more output buffer
+ * space and call ::rs_job_iter() again passing the same #next_in and
+ * #avail_in, or put the remaining input data into some persistent buffer and
+ * call rs_job_iter() with it again when there is more output space.
+ *
+ * \sa rs_job_iter() */
 struct rs_buffers_s {
-    /** \brief Next input byte.
-     * References a pointer which on entry should point to
-     * the start of the data to be encoded.  Updated to point to the byte
-     * after the last one consumed.
-     **/
+    /** Next input byte.
+     *
+     * References a pointer which on entry should point to the start of the
+     * data to be encoded.  Updated to point to the byte after the last one
+     * consumed. */
     char *next_in;
 
-    /**
-     * \brief Number of bytes available at next_in
-     * References the length of available input.  Updated to
-     * be the number of unused data bytes, which will be zero if all the
-     * input was consumed.  May be zero if there is no new input, but the
-     * caller just wants to drain output.
-     */
+    /** Number of bytes available at next_in.
+     *
+     * References the length of available input.  Updated to be the number of
+     * unused data bytes, which will be zero if all the input was consumed.
+     * May be zero if there is no new input, but the caller just wants to drain
+     * output. */
     size_t avail_in;
 
-     /**
-      * \brief True if there is no more data after this.
-      */
+    /** True if there is no more data after this. */
     int eof_in;
 
-    /**
-     * \brief Next output byte should be put there
-     * References a pointer which on entry points to the
-     * start of the output buffer.  Updated to point to the byte after the
-     * last one filled.
-     */
+    /** Next output byte should be put there.
+     *
+     * References a pointer which on entry points to the start of the output
+     * buffer.  Updated to point to the byte after the last one filled. */
     char *next_out;
 
-    /**
-     * \brief Remaining free space at next_out
+    /** Remaining free space at next_out.
      *
-     * References the size of available output buffer.
-     * Updated to the size of unused output buffer.
-     */
+     * References the size of available output buffer. Updated to the size of
+     * unused output buffer. */
     size_t avail_out;
 };
 
-/**
- * \see ::rs_buffers_s
- */
+/** \sa ::rs_buffers_s */
 typedef struct rs_buffers_s rs_buffers_t;
 
 /** Default block length, if not determined by any other factors.
@@ -415,24 +344,19 @@ typedef struct rs_buffers_s rs_buffers_t;
  * a 1KB block_len. */
 #define RS_DEFAULT_STRONG_LEN 12
 
-/**
- * \brief Job of work to be done.
+/** Job of work to be done.
  *
- * Created by functions such as rs_sig_begin(), and then iterated
- * over by rs_job_iter().
+ * 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 \ref api_streaming
- * \see rs_job
- */
+ * \sa \ref api_streaming \sa rs_job */
 typedef struct rs_job rs_job_t;
 
-
-/**
- * \brief Run a ::rs_job state machine until it blocks
- * (::RS_BLOCKED), returns an error, or completes (::RS_DONE).
+/** Run a ::rs_job state machine until it blocks (::RS_BLOCKED), returns an
+ * error, or completes (::RS_DONE).
  *
  * \param job Description of job state.
  *
@@ -440,39 +364,29 @@ typedef struct rs_job rs_job_t;
  *
  * \return The ::rs_result that caused iteration to stop.
  *
- * \c 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.
+ * \c 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 \ref api_streaming.
- */
-rs_result       rs_job_iter(rs_job_t *job, rs_buffers_t *buffers);
+ * \sa \ref api_streaming */
+rs_result rs_job_iter(rs_job_t *job, rs_buffers_t *buffers);
 
-/**
- * Type of application-supplied function for rs_job_drive().
+/** Type of application-supplied function for rs_job_drive().
  *
- * \see \ref api_pull.
- **/
+ * \sa \ref api_pull */
 typedef rs_result rs_driven_cb(rs_job_t *job, rs_buffers_t *buf,
                                void *opaque);
 
-/**
- * Actively process a job, by making callbacks to fill and empty the
- * buffers until the job is done.
- */
-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. */
+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);
 
-/**
- * Return a pointer to the statistics in a job.
- */
-const rs_stats_t * rs_job_statistics(rs_job_t *job);
+/** Return a pointer to the statistics in a job. */
+const rs_stats_t *rs_job_statistics(rs_job_t *job);
 
-/** Deallocate job state.
- */
-rs_result       rs_job_free(rs_job_t *);
+/** Deallocate job state. */
+rs_result rs_job_free(rs_job_t *);
 
 /** Get or check signature arguments for a given file size.
  *
@@ -497,7 +411,6 @@ rs_result rs_sig_args(rs_long_t old_fsize,
                       size_t *block_len,
                       size_t *strong_len);
 
-
 /** Start generating a signature.
  *
  * It's recommended you use rs_sig_args() to get the recommended arguments for
@@ -515,102 +428,73 @@ rs_result rs_sig_args(rs_long_t old_fsize,
  * many bytes, to make the signature shorter.  It's recommended you leave this
  * at zero to get the full strength.
  *
- * \sa rs_sig_file()
- */
-rs_job_t *rs_sig_begin(size_t new_block_len,
-                       size_t strong_sum_len,
+ * \sa rs_sig_file() */
+rs_job_t *rs_sig_begin(size_t new_block_len, size_t strong_sum_len,
                        rs_magic_number sig_magic);
 
-/**
- * Prepare to compute a streaming delta.
+/** Prepare to compute a streaming delta.
  *
  * \todo Add a version of this that takes a ::rs_magic_number controlling the
- * delta format.
- **/
+ * delta format. */
 rs_job_t *rs_delta_begin(rs_signature_t *);
 
-
-/**
- * \brief Read a signature from a file into an ::rs_signature structure
- * in memory.
+/** 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.
+ * 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
- * \ref rs_build_hash_table() before you can use them.
- */
+ * \note After loading the signatures, you must call \ref rs_build_hash_table()
+ * before you can use them. */
 rs_job_t *rs_loadsig_begin(rs_signature_t **);
 
-
-/**
- * Call this after loading a signature to index it.
+/** Call this after loading a signature to index it.
  *
- * Use rs_free_sumset() to release it after use.
- */
-rs_result rs_build_hash_table(rs_signature_t* sums);
-
+ * Use rs_free_sumset() to release it after use. */
+rs_result rs_build_hash_table(rs_signature_t *sums);
 
-/**
- * \brief Callback used to retrieve parts of the basis file.
+/** Callback used to retrieve parts of the basis file.
  *
  * \param pos Position where copying should begin.
  *
- * \param 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.
+ * \param 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.
  *
- * \param buf On input, a buffer of at least \p *len bytes.  May be
- * updated to point to a buffer allocated by the callback if it
- * prefers.
- */
-typedef rs_result rs_copy_cb(void *opaque, rs_long_t pos,
-                             size_t *len, void **buf);
+ * \param buf On input, a buffer of at least \p *len bytes.  May be updated to
+ * point to a buffer allocated by the callback if it prefers. */
+typedef rs_result rs_copy_cb(void *opaque, rs_long_t pos, size_t *len,
+                             void **buf);
 
-
-
-/**
- * \brief Apply a \a delta to a \a basis file to recreate
- * the \a new file.
+/** Apply a \a delta to a \a basis file to recreate the \a 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.
+ * 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.
  *
- * \param copy_cb Callback used to retrieve content from the basis
- * file.
+ * \param copy_cb Callback used to retrieve content from the basis file.
  *
- * \param copy_arg Opaque environment pointer passed through to the
- * callback.
+ * \param 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 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.
  *
- * \sa rs_patch_file()
- * \sa \ref api_streaming
- */
-rs_job_t *rs_patch_begin(rs_copy_cb *copy_cb, void *copy_arg);
-
+ * \sa rs_patch_file() \sa \ref api_streaming */
+rs_job_t *rs_patch_begin(rs_copy_cb * copy_cb, void *copy_arg);
 
-#ifndef RSYNC_NO_STDIO_INTERFACE
-#include <stdio.h>
+#  ifndef RSYNC_NO_STDIO_INTERFACE
+#    include <stdio.h>
 
-/**
- * Buffer sizes for file IO.
+/** 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. */
+ * 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. */
 extern int rs_inbuflen, rs_outbuflen;
 
-
-/**
- * Generate the signature of a basis file, and write it out to
- * another.
+/** Generate the signature of a basis file, and write it out to another.
  *
  * \param old_file Stdio readable file whose signature will be generated.
  *
@@ -620,49 +504,45 @@ extern int rs_inbuflen, rs_outbuflen;
  *
  * \param strong_len truncated length of strong checksums, in bytes
  *
- * \param sig_magic A signature magic number indicating
- * what format to use.
+ * \param sig_magic A signature magic number indicating what format to use.
  *
  * \param stats Optional pointer to receive statistics.
  *
- * \sa \ref api_whole
- */
-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);
+ * \sa \ref api_whole */
+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);
 
-/**
- * Load signatures from a signature file into memory.  Return a
- * pointer to the newly allocated structure in \p sumset.
+/** Load signatures from a signature file into memory.
  *
- * \sa \ref api_whole
- */
+ * \param sig_file Readable stdio file from which the signature will be read.
+ *
+ * \param sumset on return points to the newly allocated structure.
+ *
+ * \param stats Optional pointer to receive statistics.
+ *
+ * \sa \ref api_whole */
 rs_result rs_loadsig_file(FILE *sig_file, rs_signature_t **sumset,
-    rs_stats_t *stats);
+                          rs_stats_t *stats);
 
-/**
- * ::rs_copy_cb that reads from a stdio file.
- **/
+/** ::rs_copy_cb that reads from a stdio file. */
 rs_result rs_file_copy_cb(void *arg, rs_long_t pos, size_t *len, void **buf);
 
+/** Generate a delta between a signature and a new file into a delta file.
+ *
+ * \sa \ref api_whole */
+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, int a delta file.
- * \sa \ref api_whole
- **/
-rs_result rs_delta_file(rs_signature_t *, FILE *new_file, FILE *delta_file, rs_stats_t *);
-
-
-/**
- * Apply a patch, relative to a basis, into a new file.
- * \sa \ref api_whole
- */
-rs_result rs_patch_file(FILE *basis_file, FILE *delta_file, FILE *new_file, rs_stats_t *);
-#endif /* ! RSYNC_NO_STDIO_INTERFACE */
+/** Apply a patch, relative to a basis, into a new file.
+ *
+ * \sa \ref api_whole */
+rs_result rs_patch_file(FILE *basis_file, FILE *delta_file, FILE *new_file,
+                        rs_stats_t *);
+#  endif                        /* !RSYNC_NO_STDIO_INTERFACE */
 
-#ifdef __cplusplus
-}
-#endif
+#  ifdef __cplusplus
+}                               /* extern "C" */
+#  endif
 
-#endif /* ! _RSYNC_H */
+#endif                          /* !_RSYNC_H */