From d10a714c01762a5ee291230b7531fcfade5121dc Mon Sep 17 00:00:00 2001 From: Nikolaos Chatzikonstantinou Date: Sun, 29 Dec 2024 09:00:58 -0500 Subject: [PATCH] Fix sortlist documentation (#950) Signed-off-by: Nikolaos Chatzikonstantinou (@createyourpersonalaccount) --- docs/ares_set_sortlist.3 | 13 ++++++++++--- src/lib/ares_gethostbyname.c | 10 ++++++++++ src/lib/ares_sysconfig_files.c | 10 +++++++++- 3 files changed, 29 insertions(+), 4 deletions(-) diff --git a/docs/ares_set_sortlist.3 b/docs/ares_set_sortlist.3 index eb7bf6dc..5e225d51 100644 --- a/docs/ares_set_sortlist.3 +++ b/docs/ares_set_sortlist.3 @@ -20,10 +20,17 @@ sortlist. The provided .IR sortstr string that holds a space separated list of IP-address-netmask pairs. The netmask is optional but follows the address after a slash if present. For example, -"130.155.160.0/255.255.240.0 130.155.0.0". +"130.155.160.0/255.255.240.0 130.155.0.0" will sort IPs in ascending +order of appearance in the sortlist subnets, with those IPs that do +not match any subnets coming last. There is no particular order +amongst IPs that tie in this sorting scheme. -This function replaces any potentially previously configured address sortlist -with the ones given in the configuration string. +This function replaces any potentially previously configured address +sortlist with the ones given in the configuration string. It also +overrides the sortlist set in +.B resolv.conf(5). +Note that this function does not affect the order of results from +\fBares_getaddrinfo(3)\fP. .SH RETURN VALUES .B ares_set_sortlist(3) diff --git a/src/lib/ares_gethostbyname.c b/src/lib/ares_gethostbyname.c index d451b468..5e1134b2 100644 --- a/src/lib/ares_gethostbyname.c +++ b/src/lib/ares_gethostbyname.c @@ -140,6 +140,11 @@ static void sort_addresses(const struct hostent *host, * through the address list, with the loop invariant that everything * to the left of i1 is sorted. In the loop body, the value at i1 is moved * back through the list (via i2) until it is in sorted order. + * + * The IPs are sorted in ascending order of corresponding sortlist + * indices, with those that don't match the subnets in the sortlist + * coming last. There is no particular order amongst IPs that tie + * in this sorting scheme. */ for (i1 = 0; host->h_addr_list[i1]; i1++) { memcpy(&a1, host->h_addr_list[i1], sizeof(struct in_addr)); @@ -196,6 +201,11 @@ static void sort6_addresses(const struct hostent *host, * through the address list, with the loop invariant that everything * to the left of i1 is sorted. In the loop body, the value at i1 is moved * back through the list (via i2) until it is in sorted order. + * + * The IPv6s are sorted in ascending order of corresponding sortlist + * indices, with those that don't match the subnets in the sortlist + * coming last. There is no particular order amongst IPs that tie + * in this sorting scheme. */ for (i1 = 0; host->h_addr_list[i1]; i1++) { memcpy(&a1, host->h_addr_list[i1], sizeof(struct ares_in6_addr)); diff --git a/src/lib/ares_sysconfig_files.c b/src/lib/ares_sysconfig_files.c index a6c2a8e6..23f6dc6c 100644 --- a/src/lib/ares_sysconfig_files.c +++ b/src/lib/ares_sysconfig_files.c @@ -235,7 +235,15 @@ ares_status_t ares_parse_sortlist(struct apattern **sortlist, size_t *nsort, goto done; } - /* Split on space or semicolon */ + /* Split on space or semicolon. It's not clear why the split on + semicolon is supported, but the user of this function is + ares_set_sortlist(), whose documentation does not mention + semicolons, only spaces as valid separation characters. It is + therefore unlikely that anyone uses semicolons. + + The old parser behaved this way and this behavior of splitting in + semicolons was preserved in the parser rewrite on + e72ae094855a0aed44afadfb4de462065e144185 (see also #653).*/ status = ares_buf_split(buf, (const unsigned char *)" ;", 2, ARES_BUF_SPLIT_NONE, 0, &arr); if (status != ARES_SUCCESS) {