Fix sortlist documentation (c-ares#950)

Signed-off-by: Nikolaos Chatzikonstantinou (@createyourpersonalaccount)

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)

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));

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) {