From 23a345b3c2e7877d3cc4821ec1764f885fa01b2f Mon Sep 17 00:00:00 2001 From: Nick Mathewson Date: Mon, 30 Jul 2007 17:46:12 +0000 Subject: [PATCH] r14015@catbus: nickm | 2007-07-30 13:18:05 -0400 Add missing code documentation in src/common svn:r10991 --- src/common/compat.c | 7 +++++-- src/common/container.c | 3 ++- src/common/util.c | 30 ++++++++++++++++++++++-------- 3 files changed, 29 insertions(+), 11 deletions(-) diff --git a/src/common/compat.c b/src/common/compat.c index eee9b87b09..710854b1f3 100644 --- a/src/common/compat.c +++ b/src/common/compat.c @@ -1023,9 +1023,12 @@ tor_lookup_hostname(const char *name, uint32_t *addr) } /** Similar behavior to Unix gethostbyname: resolve name, and set - * *addr to the proper IP address and family. + * *addr to the proper IP address and family. The family + * argument (which must be AF_INET, AF_INET6, or AF_UNSPEC) declares a + * preferred family, though another one may be returned if only one + * family is implemented for this address. + * * Return 0 on success, -1 on failure; 1 on transient failure. - * DOCDOC family argument. */ int tor_addr_lookup(const char *name, uint16_t family, tor_addr_t *addr) diff --git a/src/common/container.c b/src/common/container.c index 4cac686147..c31a4d2713 100644 --- a/src/common/container.c +++ b/src/common/container.c @@ -196,7 +196,8 @@ smartlist_string_isin(const smartlist_t *sl, const char *element) return 0; } -/** DOCDOC */ +/** If element is equal to an element of sl, return that + * element's index. Otherwise, return -1. */ int smartlist_string_pos(const smartlist_t *sl, const char *element) { diff --git a/src/common/util.c b/src/common/util.c index a2ac9b934e..991cda1a97 100644 --- a/src/common/util.c +++ b/src/common/util.c @@ -2170,9 +2170,14 @@ parse_addr_and_port_range(const char *s, uint32_t *addr_out, * addr_out, a mask (if any) in mask_out, and port(s) (if any) * in port_min_out and port_max_out. * - * DOCDOC exact syntax. + * The syntax is: + * Address OptMask OptPortRange + * Address ::= IPv4Address / "[" IPv6Address "]" / "*" + * OptMask ::= "/" Integer / + * OptPortRange ::= ":*" / ":" Integer / ":" Integer "-" Integer / * - * - If mask, minport, or maxport are NULL, avoid storing those elements. + * - If mask, minport, or maxport are NULL, we do not want these + * options to be set; treat them as an error if present. * - If the string has no mask, the mask is set to /32 (IPv4) or /128 (IPv6). * - If the string has one port, it is placed in both min and max port * variables. @@ -2439,17 +2444,20 @@ tor_addr_copy(tor_addr_t *dest, const tor_addr_t *src) memcpy(dest, src, sizeof(tor_addr_t)); } -/** DOCDOC */ +/** Given two addresses addr1 and addr2, return 0 if the two + * addresses are equivalent under the mask mbits, less than 0 if addr1 + * preceeds addr2, and greater than 0 otherwise. + * + * Different address families (IPv4 vs IPv6) are always considered unequal. + */ int tor_addr_compare(const tor_addr_t *addr1, const tor_addr_t *addr2) { return tor_addr_compare_masked(addr1, addr2, 128); } -/** Given two addresses addr1 and addr2, return 0 if the two - * addresses are equivalent under the mask mbits, or nonzero if not. - * - * Different address families (IPv4 vs IPv6) are always considered unequal. +/** As tor_addr_compare(), but only looks at the first mask bits of + * the address. * * Reduce over-specific masks (>128 for ipv6, >32 for ipv4) to 128 or 32. */ @@ -2464,6 +2472,11 @@ tor_addr_compare_masked(const tor_addr_t *addr1, const tor_addr_t *addr2, tor_assert(addr1 && addr2); + /* XXXX020 this code doesn't handle mask bits right it's using v4-mapped v6 + * addresses. If I ask whether ::ffff:1.2.3.4 and ::ffff:1.2.7.8 are the + * same in the first 16 bits, it will say "yes." That's not so intuitive. + */ + v_family[0] = IN_FAMILY(addr1); v_family[1] = IN_FAMILY(addr2); @@ -2548,7 +2561,8 @@ tor_dup_addr(uint32_t addr) } /** Convert the tor_addr_t *addr into string form and store it in - * dest (no more than len bytes). DOCDOC return value. + * dest, which can hold at least len bytes. Returns dest + * on success, NULL on failure. */ const char * tor_addr_to_str(char *dest, const tor_addr_t *addr, int len)