aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat
-rw-r--r--src/common/container.h22
-rw-r--r--src/common/crypto.c3
-rw-r--r--src/common/crypto.h3
-rw-r--r--src/common/log.h2
-rw-r--r--src/common/torgzip.h10
-rw-r--r--src/common/util.c28
-rw-r--r--src/common/util.h23
-rw-r--r--src/or/test.c12
8 files changed, 49 insertions, 54 deletions
diff --git a/src/common/container.h b/src/common/container.h
index 8fbc863cb..2756fdeef 100644
--- a/src/common/container.h
+++ b/src/common/container.h
@@ -113,7 +113,12 @@ char *smartlist_join_strings2(smartlist_t *sl, const char *join,
/** Iterate over the items in a smartlist <b>sl</b>, in order. For each item,
* assign it to a new local variable of type <b>type</b> named <b>var</b>, and
* execute the statement <b>cmd</b>. Inside the loop, the loop index can
- * be accessed as <b>var</b>_sl_idx.
+ * be accessed as <b>var</b>_sl_idx and the length of the list can be accessed
+ * as <b>var</b>_sl_len.
+ *
+ * NOTE: Do not change the length of the list while the loop is in progress,
+ * unless you adjust the _sl_len variable correspondingly. See second example
+ * below.
*
* Example use:
* <pre>
@@ -123,7 +128,20 @@ char *smartlist_join_strings2(smartlist_t *sl, const char *join,
* printf("%d: %s\n", cp_sl_idx, cp);
* tor_free(cp);
* });
- * smarlitst_free(list);
+ * smartlist_free(list);
+ * </pre>
+ *
+ * Example use (advanced):
+ * <pre>
+ * SMARTLIST_FOREACH(list, char *, cp,
+ * {
+ * if (!strcmp(cp, "junk")) {
+ * smartlist_del(list, cp_sl_idx);
+ * tor_free(cp);
+ * --cp_sl_len; // decrement length of list so we don't run off the end
+ * --cp_sl_idx; // decrement idx so we consider the item that moved here
+ * }
+ * });
* </pre>
*/
#define SMARTLIST_FOREACH(sl, type, var, cmd) \
diff --git a/src/common/crypto.c b/src/common/crypto.c
index 0af144d23..5f023fa16 100644
--- a/src/common/crypto.c
+++ b/src/common/crypto.c
@@ -1023,8 +1023,7 @@ crypto_pk_get_fingerprint(crypto_pk_env_t *pk, char *fp_out, int add_space)
}
base16_encode(hexdigest,sizeof(hexdigest),digest,DIGEST_LEN);
if (add_space) {
- if (tor_strpartition(fp_out, FINGERPRINT_LEN+1, hexdigest, " ", 4,
- NEVER_TERMINATE)<0)
+ if (tor_strpartition(fp_out, FINGERPRINT_LEN+1, hexdigest, " ", 4)<0)
return -1;
} else {
strncpy(fp_out, hexdigest, HEX_DIGEST_LEN+1);
diff --git a/src/common/crypto.h b/src/common/crypto.h
index f09936ef9..5257fd431 100644
--- a/src/common/crypto.h
+++ b/src/common/crypto.h
@@ -167,7 +167,8 @@ void base32_encode(char *dest, size_t destlen, const char *src, size_t srclen);
int digest_to_base64(char *d64, const char *digest);
int digest_from_base64(char *digest, const char *d64);
-/** DOCDOC */
+/** Length of RFC2440-style S2K specifier: the first 8 bytes are a salt, the
+ * 9th describes how much iteration to do. */
#define S2K_SPECIFIER_LEN 9
void secret_to_key(char *key_out, size_t key_out_len, const char *secret,
size_t secret_len, const char *s2k_specifier);
diff --git a/src/common/log.h b/src/common/log.h
index c6b6a6aa6..b2e957579 100644
--- a/src/common/log.h
+++ b/src/common/log.h
@@ -90,7 +90,7 @@
/** Bandwidth accounting. */
#define LD_ACCT (1u<<17)
-/** DOCDOC */
+/** Callback type used for add_callback_log. */
typedef void (*log_callback)(int severity, uint32_t domain, const char *msg);
int parse_log_level(const char *level);
diff --git a/src/common/torgzip.h b/src/common/torgzip.h
index f8e15d75c..51e870930 100644
--- a/src/common/torgzip.h
+++ b/src/common/torgzip.h
@@ -12,7 +12,10 @@
#define __TORGZIP_H
#define TORGZIP_H_ID "$Id$"
-/** DOCDOC */
+/** Enumeration of what kind of compression to use. Only ZLIB_METHOD is
+ * guaranteed to be supported by the compress/uncompress functions here;
+ * GZIP_METHOD may be supported if we built against zlib version 1.2 or later
+ * and is_gzip_supported() returns true. */
typedef enum {
NO_METHOD=0, GZIP_METHOD=1, ZLIB_METHOD=2, UNKNOWN_METHOD=3
} compress_method_t;
@@ -32,10 +35,11 @@ int is_gzip_supported(void);
compress_method_t detect_compression_method(const char *in, size_t in_len);
-/** DOCDOC */
+/** Return values from tor_zlib_process; see that function's documentation for
+ * details. */
typedef enum {
TOR_ZLIB_OK, TOR_ZLIB_DONE, TOR_ZLIB_BUF_FULL, TOR_ZLIB_ERR
-} tor_zlib_output_t;
+} tor_zlib_output_t;
typedef struct tor_zlib_state_t tor_zlib_state_t;
tor_zlib_state_t *tor_zlib_new(int compress, compress_method_t method);
diff --git a/src/common/util.c b/src/common/util.c
index 6ecb901ea..a5b87c431 100644
--- a/src/common/util.c
+++ b/src/common/util.c
@@ -238,17 +238,12 @@ tor_strstrip(char *s, const char *strip)
* string <b>s</b>, with the string <b>insert</b> inserted after every
* <b>n</b> characters. Return 0 on success, -1 on failure.
*
- * If <b>rule</b> is ALWAYS_TERMINATE, then always end the string with
- * <b>insert</b>, even if its length is not a multiple of <b>n</b>. If
- * <b>rule</b> is NEVER_TERMINATE, then never end the string with
- * <b>insert</b>, even if its length <i>is</i> a multiple of <b>n</b>.
- * If <b>rule</b> is TERMINATE_IF_EVEN, then end the string with <b>insert</b>
- * exactly when its length <i>is</i> a multiple of <b>n</b>.
+ * Never end the string with <b>insert</b>, even if its length <i>is</i> a
+ * multiple of <b>n</b>.
*/
int
tor_strpartition(char *dest, size_t dest_len,
- const char *s, const char *insert, size_t n,
- part_finish_rule_t rule)
+ const char *s, const char *insert, size_t n)
{
char *destp;
size_t len_in, len_out, len_ins;
@@ -264,17 +259,8 @@ tor_strpartition(char *dest, size_t dest_len,
tor_assert(len_in/n < SIZE_T_CEILING/len_ins); /* avoid overflow */
len_out = len_in + (len_in/n)*len_ins;
is_even = (len_in%n) == 0;
- switch (rule)
- {
- case ALWAYS_TERMINATE:
- if (!is_even) len_out += len_ins;
- break;
- case NEVER_TERMINATE:
- if (is_even && len_in) len_out -= len_ins;
- break;
- case TERMINATE_IF_EVEN:
- break;
- }
+ if (is_even && len_in)
+ len_out -= len_ins;
if (dest_len < len_out+1)
return -1;
destp = dest;
@@ -283,10 +269,8 @@ tor_strpartition(char *dest, size_t dest_len,
strncpy(destp, s, n);
remaining -= n;
if (remaining < 0) {
- if (rule == ALWAYS_TERMINATE)
- strncpy(destp+n+remaining,insert,len_ins+1);
break;
- } else if (remaining == 0 && rule == NEVER_TERMINATE) {
+ } else if (remaining == 0) {
*(destp+n) = '\0';
break;
}
diff --git a/src/common/util.h b/src/common/util.h
index 868f4cde2..5b6dafdaa 100644
--- a/src/common/util.h
+++ b/src/common/util.h
@@ -39,13 +39,15 @@
#error "Sorry; we don't support building with NDEBUG."
#else
#ifdef __GNUC__
-/** DOCDOC */
+/** Macro: evaluate the expression x, which we expect to be false.
+ * Used to hint the compiler that a branch won't be taken. */
#define PREDICT_FALSE(x) PREDICT((x) == ((typeof(x)) 0), 0)
#else
#define PREDICT_FALSE(x) !(x)
#endif
-/** DOCDOC */
+/** Like assert(3), but send assertion failures to the log as well as to
+ * stderr. */
#define tor_assert(expr) do { \
if (PREDICT_FALSE(expr)) { \
log(LOG_ERR, LD_BUG, "%s:%d: %s: Assertion %s failed; aborting.", \
@@ -110,7 +112,7 @@ extern int dmalloc_free(const char *file, const int line, void *pnt,
/* String manipulation */
-/** DOCDOC */
+/** Allowable characters in a hexadecimal string. */
#define HEX_CHARACTERS "0123456789ABCDEFabcdef"
void tor_strlower(char *s) ATTR_NONNULL((1));
void tor_strupper(char *s) ATTR_NONNULL((1));
@@ -123,13 +125,8 @@ int strcmpend(const char *s1, const char *s2) ATTR_PURE ATTR_NONNULL((1,2));
int strcasecmpend(const char *s1, const char *s2)
ATTR_PURE ATTR_NONNULL((1,2));
int tor_strstrip(char *s, const char *strip) ATTR_NONNULL((1,2));
-/** DOCDOC */
-typedef enum {
- ALWAYS_TERMINATE, NEVER_TERMINATE, TERMINATE_IF_EVEN
-} part_finish_rule_t;
int tor_strpartition(char *dest, size_t dest_len,
- const char *s, const char *insert, size_t n,
- part_finish_rule_t rule);
+ const char *s, const char *insert, size_t n);
long tor_parse_long(const char *s, int base, long min,
long max, int *ok, char **next);
unsigned long tor_parse_ulong(const char *s, int base, unsigned long min,
@@ -169,11 +166,13 @@ int parse_iso_time(const char *buf, time_t *t);
int write_all(int fd, const char *buf, size_t count, int isSocket);
int read_all(int fd, char *buf, size_t count, int isSocket);
-/** DOCDOC */
-typedef enum { FN_ERROR, FN_NOENT, FN_FILE, FN_DIR} file_status_t;
+/** Return values from file_status(); see that function's documentation
+ * for details. */
+typedef enum { FN_ERROR, FN_NOENT, FN_FILE, FN_DIR } file_status_t;
file_status_t file_status(const char *filename);
-/** DOCDOC */
+/** Possible behaviors for check_private_dir() on encountering a nonexistent
+ * directory; see that function's documentation for details. */
typedef enum { CPD_NONE, CPD_CREATE, CPD_CHECK } cpd_check_t;
int check_private_dir(const char *dirname, cpd_check_t check);
int write_str_to_file(const char *fname, const char *str, int bin);
diff --git a/src/or/test.c b/src/or/test.c
index 77e6e9f2d..6de1ac7f1 100644
--- a/src/or/test.c
+++ b/src/or/test.c
@@ -654,17 +654,7 @@ test_util(void)
test_streq(buf, "Testing123");
/* Test tor_strpartition() */
- test_assert(! tor_strpartition(buf, sizeof(buf), "abcdefg", "##", 3,
- TERMINATE_IF_EVEN));
- test_streq(buf, "abc##def##g");
- test_assert(! tor_strpartition(buf, sizeof(buf), "abcdefg", "##", 3,
- ALWAYS_TERMINATE));
- test_streq(buf, "abc##def##g##");
- test_assert(! tor_strpartition(buf, sizeof(buf), "abcdefghi", "##", 3,
- TERMINATE_IF_EVEN));
- test_streq(buf, "abc##def##ghi##");
- test_assert(! tor_strpartition(buf, sizeof(buf), "abcdefghi", "##", 3,
- NEVER_TERMINATE));
+ test_assert(! tor_strpartition(buf, sizeof(buf), "abcdefghi", "##", 3));
test_streq(buf, "abc##def##ghi");
/* Test parse_addr_port */
generated by cgit v1.2.3 (git 2.45.0) at 2024-12-01 03:00:28 +0000