Explain the dual use of struct prefix for CIDR prefixes and
address/netmask pairs, and clarify the two comparison functions.
diff --git a/lib/prefix.c b/lib/prefix.c
index 61e0f19..5a3e71b 100644
--- a/lib/prefix.c
+++ b/lib/prefix.c
@@ -118,7 +118,14 @@
}
}
-/* If both prefix structure is same then return 1 else return 0. */
+/*
+ * Return 1 if the address/netmask contained in the prefix structure
+ * is the same, and else return 0. For this routine, 'same' requires
+ * that not only the prefix length and the network part be the same,
+ * but also the host part. Thus, 10.0.0.1/8 and 10.0.0.2/8 are not
+ * the same. Note that this routine has the same return value sense
+ * as '==' (which is different from prefix_cmp).
+ */
int
prefix_same (struct prefix *p1, struct prefix *p2)
{
@@ -136,8 +143,16 @@
return 0;
}
-/* When both prefix structure is not same, but will be same after
- applying mask, return 0. otherwise, return 1 */
+/*
+ * Return 0 if the network prefixes represented by the struct prefix
+ * arguments are the same prefix, and 1 otherwise. Network prefixes
+ * are considered the same if the prefix lengths are equal and the
+ * network parts are the same. Host bits (which are considered masked
+ * by the prefix length) are not significant. Thus, 10.0.0.1/8 and
+ * 10.0.0.2/8 are considered equivalent by this routine. Note that
+ * this routine has the same return sense as strcmp (which is different
+ * from prefix_same).
+ */
int
prefix_cmp (struct prefix *p1, struct prefix *p2)
{
diff --git a/lib/prefix.h b/lib/prefix.h
index 7d7cde6..5884640 100644
--- a/lib/prefix.h
+++ b/lib/prefix.h
@@ -23,6 +23,15 @@
#ifndef _ZEBRA_PREFIX_H
#define _ZEBRA_PREFIX_H
+/*
+ * A struct prefix contains an address family, a prefix length, and an
+ * address. This can represent either a 'network prefix' as defined
+ * by CIDR, where the 'host bits' of the prefix are 0
+ * (e.g. AF_INET:10.0.0.0/8), or an address and netmask
+ * (e.g. AF_INET:10.0.0.9/8), such as might be configured on an
+ * interface.
+ */
+
/* IPv4 and IPv6 unified prefix structure. */
struct prefix
{