Add comments and asserts regarding rs_build_hash_table()

It is not clear in the header file that rs_build_hash_table() MUST be
called after the signature has been loaded.

4 files changed, 28 insertions, 2 deletions

diff --git a/NEWS b/NEWS
index ba8bfde..4f00f21 100644
--- a/NEWS
+++ b/NEWS
@@ -2,6 +2,11 @@ Changes in librsync 1.0.1-HEAD (not released yet)
 
  * Better performance on large files. (VictorDenisov)
 
+ * Add comment on usage of rs_build_hash_table(), and assert correct use.
+   Callers must call rs_build_hash_table() after loading the signature,
+   and before calling rs_delta_begin().
+   Thanks to Paul Harris <paulharris@computer.org>
+
 Changes in librsync 1.0.0 (2015-01-23)
 
  * SECURITY: CVE-2014-8242: librsync previously used a truncated MD4
diff --git a/delta.c b/delta.c
index d5a5a8d..ccbccc5 100644
--- a/delta.c
+++ b/delta.c
@@ -445,6 +445,10 @@ static rs_result rs_delta_s_header(rs_job_t *job)
  */
 rs_job_t *rs_delta_begin(rs_signature_t *sig)
 {
+    /* Caller must have called rs_build_hash_table() by now */
+    if (!sig->tag_table)
+        rs_fatal("Must call rs_build_hash_table() prior to calling rs_delta_begin()");
+
     rs_job_t *job;
 
     job = rs_job_new("delta", rs_delta_s_header);
diff --git a/librsync.h b/librsync.h
index dd5a958..a872d4a 100644
--- a/librsync.h
+++ b/librsync.h
@@ -373,8 +373,23 @@ rs_job_t *rs_sig_begin(size_t new_block_len,
 
 rs_job_t *rs_delta_begin(rs_signature_t *);
 
+
+/**
+ * \brief Read a signature from a file into an ::rs_signature_t structure
+ * in memory.
+ *
+ * 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
+ * rs_build_hash_table() before you can use them.
+ */
 rs_job_t *rs_loadsig_begin(rs_signature_t **);
 
+rs_result rs_build_hash_table(rs_signature_t* sums);
+
+
+
 /**
  * \brief Callback used to retrieve parts of the basis file.
  *
@@ -395,8 +410,6 @@ typedef rs_result rs_copy_cb(void *opaque, rs_long_t pos,
 rs_job_t *rs_patch_begin(rs_copy_cb *, void *copy_arg);
 
 
-rs_result rs_build_hash_table(rs_signature_t* sums);
-
 
 
 #ifndef RSYNC_NO_STDIO_INTERFACE
diff --git a/search.c b/search.c
index ec5c492..9827592 100644
--- a/search.c
+++ b/search.c
@@ -169,6 +169,10 @@ rs_search_for_block(rs_weak_sum_t weak_sum,
                     rs_signature_t const *sig, rs_stats_t * stats,
                     rs_long_t * match_where)
 {
+    /* Caller must have called rs_build_hash_table() by now */
+    if (!sig->tag_table)
+        rs_fatal("Must have called rs_build_hash_table() by now");
+
     rs_strong_sum_t strong_sum;
     int got_strong = 0;
     int hash_tag = gettag(weak_sum);