Commit f02be023 authored by Nick Mathewson's avatar Nick Mathewson 🎨
Browse files

r11639@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.


svn:r9483
parent 03ef2156
......@@ -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) \
......
......@@ -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);
......
......@@ -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);
......
......@@ -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);
......
......@@ -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);
......
......@@ -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;
}
......
......@@ -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);
......
......@@ -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 */
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment