[or-cvs] r9483: Add documentation to src/common/*.h; improve documentation f (in tor/trunk: . src/common src/or)
nickm at seul.org
nickm at seul.org
Mon Feb 5 18:33:56 UTC 2007
Author: nickm
Date: 2007-02-05 13:33:52 -0500 (Mon, 05 Feb 2007)
New Revision: 9483
Modified:
tor/trunk/
tor/trunk/src/common/container.h
tor/trunk/src/common/crypto.c
tor/trunk/src/common/crypto.h
tor/trunk/src/common/log.h
tor/trunk/src/common/torgzip.h
tor/trunk/src/common/util.c
tor/trunk/src/common/util.h
tor/trunk/src/or/test.c
Log:
r11639 at catbus: nickm | 2007-02-05 13:33:38 -0500
Add documentation to src/common/*.h; improve documentation for SMARTLIST_FOREACH; remove never-used options and corresponding tests from tor_strpartition.
Property changes on: tor/trunk
___________________________________________________________________
svk:merge ticket from /tor/trunk [r11639] on 8246c3cf-6607-4228-993b-4d95d33730f1
Modified: tor/trunk/src/common/container.h
===================================================================
--- tor/trunk/src/common/container.h 2007-02-05 17:42:40 UTC (rev 9482)
+++ tor/trunk/src/common/container.h 2007-02-05 18:33:52 UTC (rev 9483)
@@ -113,8 +113,13 @@
/** 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>
* smartlist_t *list = smartlist_split("A:B:C", ":", 0, 0);
@@ -123,8 +128,21 @@
* 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) \
do { \
Modified: tor/trunk/src/common/crypto.c
===================================================================
--- tor/trunk/src/common/crypto.c 2007-02-05 17:42:40 UTC (rev 9482)
+++ tor/trunk/src/common/crypto.c 2007-02-05 18:33:52 UTC (rev 9483)
@@ -1023,8 +1023,7 @@
}
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);
Modified: tor/trunk/src/common/crypto.h
===================================================================
--- tor/trunk/src/common/crypto.h 2007-02-05 17:42:40 UTC (rev 9482)
+++ tor/trunk/src/common/crypto.h 2007-02-05 18:33:52 UTC (rev 9483)
@@ -167,7 +167,8 @@
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);
Modified: tor/trunk/src/common/log.h
===================================================================
--- tor/trunk/src/common/log.h 2007-02-05 17:42:40 UTC (rev 9482)
+++ tor/trunk/src/common/log.h 2007-02-05 18:33:52 UTC (rev 9483)
@@ -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);
Modified: tor/trunk/src/common/torgzip.h
===================================================================
--- tor/trunk/src/common/torgzip.h 2007-02-05 17:42:40 UTC (rev 9482)
+++ tor/trunk/src/common/torgzip.h 2007-02-05 18:33:52 UTC (rev 9483)
@@ -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 @@
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);
Modified: tor/trunk/src/common/util.c
===================================================================
--- tor/trunk/src/common/util.c 2007-02-05 17:42:40 UTC (rev 9482)
+++ tor/trunk/src/common/util.c 2007-02-05 18:33:52 UTC (rev 9483)
@@ -238,17 +238,12 @@
* 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_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 @@
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;
}
Modified: tor/trunk/src/common/util.h
===================================================================
--- tor/trunk/src/common/util.h 2007-02-05 17:42:40 UTC (rev 9482)
+++ tor/trunk/src/common/util.h 2007-02-05 18:33:52 UTC (rev 9483)
@@ -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 @@
/* 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 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 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);
Modified: tor/trunk/src/or/test.c
===================================================================
--- tor/trunk/src/or/test.c 2007-02-05 17:42:40 UTC (rev 9482)
+++ tor/trunk/src/or/test.c 2007-02-05 18:33:52 UTC (rev 9483)
@@ -654,17 +654,7 @@
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 */
More information about the tor-commits
mailing list