const is fine on ares__channel_[un]lock (#758)

at https://github.com/c-ares/c-ares/pull/601#issuecomment-1801935063 you
chose not to scatter `const` on the public interface because of the plan
- now realised - to add threading to c-ares, and in the expectation that
even read operations would need to lock the mutex.

But the threading implementation has a _pointer_ to a mutex inside the
ares channel and as I understand it, that means that it is just fine to
mark `ares__channel_lock` (and `ares__channel_unlock`) as taking a
`const` channel. It is the pointed-to mutex that is not constant, but C
does not propagate `const`-ness through pointers.

This PR sprinkles const where appropriate on public interfaces.

Fix By: David Hotham (@dimbleby)

docs/ares_dup.3

@@ -9,7 +9,7 @@ ares_dup \- Duplicate a resolver channel
 .nf
 #include <ares.h>
 
-int ares_dup(ares_channel_t **\fIdest\fP, ares_channel_t *\fIsource\fP)
+int ares_dup(ares_channel_t **\fIdest\fP, const ares_channel_t *\fIsource\fP)
 .fi
 .SH DESCRIPTION
 The \fBares_dup(3)\fP function duplicates an existing communications channel
@@ -23,4 +23,3 @@ handle when the channel is no longer needed.
 .BR ares_library_init (3)
 .SH AVAILABILITY
 \fIares_dup(3)\fP was added in c-ares 1.6.0
-

docs/ares_fds.3

@@ -9,7 +9,7 @@ ares_fds \- return file descriptors to select on (deprecated)
 .nf
 #include <ares.h>
 
-int ares_fds(ares_channel_t *\fIchannel\fP,
+int ares_fds(const ares_channel_t *\fIchannel\fP,
              fd_set *\fIread_fds\fP,
              fd_set *\fIwrite_fds\fP)
 .fi

docs/ares_get_servers.3

@@ -10,10 +10,10 @@ ares_get_servers, ares_get_servers_ports \- Retrieve name servers from an initia
 .nf
 #include <ares.h>
 
-int ares_get_servers(ares_channel_t *\fIchannel\fP,
+int ares_get_servers(const ares_channel_t *\fIchannel\fP,
                      struct ares_addr_node **\fIservers\fP)
 
-int ares_get_servers_ports(ares_channel_t *\fIchannel\fP,
+int ares_get_servers_ports(const ares_channel_t *\fIchannel\fP,
                            struct ares_addr_port_node **\fIservers\fP)
 .fi
 .SH DESCRIPTION

docs/ares_getsock.3

@@ -9,7 +9,7 @@ ares_getsock \- get socket descriptors to wait on (deprecated)
 .nf
 #include <ares.h>
 
-int ares_getsock(ares_channel_t *\fIchannel\fP, ares_socket_t *\fIsocks\fP,
+int ares_getsock(const ares_channel_t *\fIchannel\fP, ares_socket_t *\fIsocks\fP,
                  int \fInumsocks\fP);
 .fi
 .SH DESCRIPTION

docs/ares_queue.3

@@ -10,7 +10,7 @@ c-ares queue status
 .nf
 #include <ares.h>
 
-size_t ares_queue_active_queries(ares_channel_t *channel);
+size_t ares_queue_active_queries(const ares_channel_t *channel);
 
 ares_status_t ares_queue_wait_empty(ares_channel_t *channel,
                                     int timeout_ms);

docs/ares_save_options.3

@@ -9,7 +9,7 @@ ares_save_options \- Save configuration values obtained from initialized ares_ch
 .nf
 #include <ares.h>
 
-int ares_save_options(ares_channel_t *\fIchannel\fP,
+int ares_save_options(const ares_channel_t *\fIchannel\fP,
                       struct ares_options *\fIoptions\fP, int *\fIoptmask\fP)
 .fi
 .SH DESCRIPTION
@@ -36,7 +36,7 @@ The channel data was successfully stored
 The memory was exhausted
 .TP 15
 .B ARES_ENODATA
-The channel data identified by 
+The channel data identified by
 .IR channel
 were invalid.
 .SH NOTE

docs/ares_set_servers_csv.3

@@ -14,7 +14,7 @@ int ares_set_servers_csv(ares_channel_t *\fIchannel\fP, const char* \fIservers\f
 
 int ares_set_servers_ports_csv(ares_channel_t *\fIchannel\fP, const char* \fIservers\fP)
 
-char *ares_get_servers_csv(ares_channel_t *\fIchannel\fP)
+char *ares_get_servers_csv(const ares_channel_t *\fIchannel\fP)
 .fi
 .SH DESCRIPTION
 The \fBares_set_servers_csv\fP and \fBares_set_servers_ports_csv\fP functions set

docs/ares_timeout.3

@@ -9,7 +9,7 @@ ares_timeout \- return maximum time to wait
 .nf
 #include <ares.h>
 
-struct timeval *ares_timeout(ares_channel_t *\fIchannel\fP,
+struct timeval *ares_timeout(const ares_channel_t *\fIchannel\fP,
                              struct timeval *\fImaxtv\fP,
                              struct timeval *\fItv\fP)
 .fi

include/ares.h

@@ -473,16 +473,16 @@ CARES_EXTERN const char *ares_version(int *version);
 CARES_EXTERN             CARES_DEPRECATED_FOR(ares_init_options) int ares_init(
   ares_channel_t **channelptr);
 
-CARES_EXTERN int           ares_init_options(ares_channel_t           **channelptr,
-                                             const struct ares_options *options,
-                                             int                        optmask);
+CARES_EXTERN int  ares_init_options(ares_channel_t           **channelptr,
+                                    const struct ares_options *options,
+                                    int                        optmask);
 
-CARES_EXTERN int           ares_save_options(ares_channel_t      *channel,
-                                             struct ares_options *options, int *optmask);
+CARES_EXTERN int  ares_save_options(const ares_channel_t *channel,
+                                    struct ares_options *options, int *optmask);
 
-CARES_EXTERN void          ares_destroy_options(struct ares_options *options);
+CARES_EXTERN void ares_destroy_options(struct ares_options *options);
 
-CARES_EXTERN int           ares_dup(ares_channel_t **dest, ares_channel_t *src);
+CARES_EXTERN int  ares_dup(ares_channel_t **dest, const ares_channel_t *src);
 
 CARES_EXTERN ares_status_t ares_reinit(ares_channel_t *channel);
 
@@ -512,8 +512,10 @@ CARES_EXTERN void          ares_set_socket_callback(ares_channel_t           *ch
 CARES_EXTERN void          ares_set_socket_configure_callback(
            ares_channel_t *channel, ares_sock_config_callback callback, void *user_data);
 
-CARES_EXTERN void          ares_set_server_state_callback(
-           ares_channel_t *channel, ares_server_state_callback callback, void *user_data);
+CARES_EXTERN void
+                  ares_set_server_state_callback(ares_channel_t            *channel,
+                                                 ares_server_state_callback callback,
+                                                 void                      *user_data);
 
 CARES_EXTERN int  ares_set_sortlist(ares_channel_t *channel,
                                     const char     *sortstr);
@@ -632,17 +634,17 @@ CARES_EXTERN void ares_getnameinfo(ares_channel_t        *channel,
 
 CARES_EXTERN      CARES_DEPRECATED_FOR(
   ARES_OPT_EVENT_THREAD or
-  ARES_OPT_SOCK_STATE_CB) int ares_fds(ares_channel_t *channel,
+  ARES_OPT_SOCK_STATE_CB) int ares_fds(const ares_channel_t *channel,
                                             fd_set *read_fds, fd_set *write_fds);
 
 CARES_EXTERN CARES_DEPRECATED_FOR(
   ARES_OPT_EVENT_THREAD or
-  ARES_OPT_SOCK_STATE_CB) int ares_getsock(ares_channel_t *channel,
+  ARES_OPT_SOCK_STATE_CB) int ares_getsock(const ares_channel_t *channel,
                                            ares_socket_t *socks, int numsocks);
 
-CARES_EXTERN struct timeval *ares_timeout(ares_channel_t *channel,
-                                          struct timeval *maxtv,
-                                          struct timeval *tv);
+CARES_EXTERN struct timeval *ares_timeout(const ares_channel_t *channel,
+                                          struct timeval       *maxtv,
+                                          struct timeval       *tv);
 
 CARES_EXTERN CARES_DEPRECATED_FOR(ares_process_fd) void ares_process(
   ares_channel_t *channel, fd_set *read_fds, fd_set *write_fds);
@@ -866,22 +868,24 @@ CARES_EXTERN CARES_DEPRECATED_FOR(ares_set_servers_csv) int ares_set_servers(
   ares_channel_t *channel, const struct ares_addr_node *servers);
 
 CARES_EXTERN
-  CARES_DEPRECATED_FOR(ares_set_servers_ports_csv) int ares_set_servers_ports(
-    ares_channel_t *channel, const struct ares_addr_port_node *servers);
+CARES_DEPRECATED_FOR(ares_set_servers_ports_csv)
+int                ares_set_servers_ports(ares_channel_t                   *channel,
+                                          const struct ares_addr_port_node *servers);
 
 /* Incoming string format: host[:port][,host[:port]]... */
 CARES_EXTERN int   ares_set_servers_csv(ares_channel_t *channel,
                                         const char     *servers);
 CARES_EXTERN int   ares_set_servers_ports_csv(ares_channel_t *channel,
                                               const char     *servers);
-CARES_EXTERN char *ares_get_servers_csv(ares_channel_t *channel);
+CARES_EXTERN char *ares_get_servers_csv(const ares_channel_t *channel);
 
 CARES_EXTERN CARES_DEPRECATED_FOR(ares_get_servers_csv) int ares_get_servers(
-  ares_channel_t *channel, struct ares_addr_node **servers);
+  const ares_channel_t *channel, struct ares_addr_node **servers);
 
 CARES_EXTERN
-  CARES_DEPRECATED_FOR(ares_get_servers_ports_csv) int ares_get_servers_ports(
-    ares_channel_t *channel, struct ares_addr_port_node **servers);
+CARES_DEPRECATED_FOR(ares_get_servers_ports_csv)
+int                        ares_get_servers_ports(const ares_channel_t        *channel,
+                                                  struct ares_addr_port_node **servers);
 
 CARES_EXTERN const char   *ares_inet_ntop(int af, const void *src, char *dst,
                                           ares_socklen_t size);
@@ -915,7 +919,7 @@ CARES_EXTERN ares_status_t ares_queue_wait_empty(ares_channel_t *channel,
  *  \param[in] channel Initialized ares channel
  *  \return Number of active queries to servers
  */
-CARES_EXTERN size_t        ares_queue_active_queries(ares_channel_t *channel);
+CARES_EXTERN size_t ares_queue_active_queries(const ares_channel_t *channel);
 
 #ifdef __cplusplus
 }

src/lib/ares__threads.c

@@ -537,12 +537,12 @@ void ares__channel_threading_destroy(ares_channel_t *channel)
   channel->cond_empty = NULL;
 }
 
-void ares__channel_lock(ares_channel_t *channel)
+void ares__channel_lock(const ares_channel_t *channel)
 {
   ares__thread_mutex_lock(channel->lock);
 }
 
-void ares__channel_unlock(ares_channel_t *channel)
+void ares__channel_unlock(const ares_channel_t *channel)
 {
   ares__thread_mutex_unlock(channel->lock);
 }

src/lib/ares_fds.c

@@ -30,7 +30,7 @@
 #include "ares.h"
 #include "ares_private.h"
 
-int ares_fds(ares_channel_t *channel, fd_set *read_fds, fd_set *write_fds)
+int ares_fds(const ares_channel_t *channel, fd_set *read_fds, fd_set *write_fds)
 {
   ares_socket_t       nfds;
   ares__slist_node_t *snode;

src/lib/ares_getsock.c

@@ -29,7 +29,7 @@
 #include "ares.h"
 #include "ares_private.h"
 
-int ares_getsock(ares_channel_t *channel, ares_socket_t *socks,
+int ares_getsock(const ares_channel_t *channel, ares_socket_t *socks,
                  int numsocks) /* size of the 'socks' array */
 {
   ares__slist_node_t *snode;

src/lib/ares_init.c

@@ -426,7 +426,7 @@ ares_status_t ares_reinit(ares_channel_t *channel)
 
 /* ares_dup() duplicates a channel handle with all its options and returns a
    new channel handle */
-int ares_dup(ares_channel_t **dest, ares_channel_t *src)
+int ares_dup(ares_channel_t **dest, const ares_channel_t *src)
 {
   struct ares_options opts;
   ares_status_t       rc;

src/lib/ares_options.c

@@ -53,8 +53,8 @@ void ares_destroy_options(struct ares_options *options)
   ares_free(options->hosts_path);
 }
 
-static struct in_addr *ares_save_opt_servers(ares_channel_t *channel,
-                                             int            *nservers)
+static struct in_addr *ares_save_opt_servers(const ares_channel_t *channel,
+                                             int                  *nservers)
 {
   ares__slist_node_t *snode;
   struct in_addr     *out =
@@ -82,8 +82,8 @@ static struct in_addr *ares_save_opt_servers(ares_channel_t *channel,
 }
 
 /* Save options from initialized channel */
-int ares_save_options(ares_channel_t *channel, struct ares_options *options,
-                      int *optmask)
+int ares_save_options(const ares_channel_t *channel,
+                      struct ares_options *options, int *optmask)
 {
   size_t i;
 
@@ -231,10 +231,8 @@ int ares_save_options(ares_channel_t *channel, struct ares_options *options,
 
   /* Set options for server failover behavior */
   if (channel->optmask & ARES_OPT_SERVER_FAILOVER) {
-    options->server_failover_opts.retry_chance =
-      channel->server_retry_chance;
-    options->server_failover_opts.retry_delay =
-      channel->server_retry_delay;
+    options->server_failover_opts.retry_chance = channel->server_retry_chance;
+    options->server_failover_opts.retry_delay  = channel->server_retry_delay;
   }
 
   *optmask = (int)channel->optmask;
@@ -484,10 +482,8 @@ ares_status_t ares__init_by_options(ares_channel_t            *channel,
 
   /* Set fields for server failover behavior */
   if (optmask & ARES_OPT_SERVER_FAILOVER) {
-    channel->server_retry_chance =
-      options->server_failover_opts.retry_chance;
-    channel->server_retry_delay =
-      options->server_failover_opts.retry_delay;
+    channel->server_retry_chance = options->server_failover_opts.retry_chance;
+    channel->server_retry_delay  = options->server_failover_opts.retry_delay;
   }
 
   channel->optmask = (unsigned int)optmask;

src/lib/ares_private.h

@@ -642,8 +642,8 @@ ares_status_t ares_qcache_fetch(ares_channel_t           *channel,
 
 ares_status_t ares__channel_threading_init(ares_channel_t *channel);
 void          ares__channel_threading_destroy(ares_channel_t *channel);
-void          ares__channel_lock(ares_channel_t *channel);
-void          ares__channel_unlock(ares_channel_t *channel);
+void          ares__channel_lock(const ares_channel_t *channel);
+void          ares__channel_unlock(const ares_channel_t *channel);
 
 struct ares_event_thread;
 typedef struct ares_event_thread ares_event_thread_t;

src/lib/ares_send.c

@@ -200,7 +200,7 @@ void ares_send(ares_channel_t *channel, const unsigned char *qbuf, int qlen,
   ares_dns_record_destroy(dnsrec);
 }
 
-size_t ares_queue_active_queries(ares_channel_t *channel)
+size_t ares_queue_active_queries(const ares_channel_t *channel)
 {
   size_t len;
 

src/lib/ares_timeout.c

@@ -55,8 +55,8 @@ void ares__timeval_remaining(struct timeval       *remaining,
   }
 }
 
-struct timeval *ares_timeout(ares_channel_t *channel, struct timeval *maxtv,
-                             struct timeval *tvbuf)
+struct timeval *ares_timeout(const ares_channel_t *channel,
+                             struct timeval *maxtv, struct timeval *tvbuf)
 {
   const struct query *query;
   ares__slist_node_t *node;

src/lib/ares_update_servers.c

@@ -167,13 +167,13 @@ static ares_bool_t ares_server_blacklisted(const struct ares_addr *addr)
     const unsigned char netbase[16];
     unsigned char       netmask;
   } blacklist_v6[] = {
-  /* fec0::/10 was deprecated by [RFC3879] in September 2004. Formerly a
-  * Site-Local scoped address prefix.  These are never valid DNS servers,
-  * but are known to be returned at least sometimes on Windows and Android.
-  */
-    {{ 0xfe, 0xc0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+    /* fec0::/10 was deprecated by [RFC3879] in September 2004. Formerly a
+     * Site-Local scoped address prefix.  These are never valid DNS servers,
+     * but are known to be returned at least sometimes on Windows and Android.
+     */
+    { { 0xfe, 0xc0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
         0x00, 0x00, 0x00, 0x00 },
-     10}
+     10 }
   };
 
   size_t i;
@@ -370,7 +370,6 @@ static ares_status_t ares__sconfig_linklocal(ares_sconfig_t *s,
   return ARES_SUCCESS;
 }
 
-
 ares_status_t ares__sconfig_append(ares__llist_t         **sconfig,
                                    const struct ares_addr *addr,
                                    unsigned short          udp_port,
@@ -594,7 +593,7 @@ static ares_status_t ares__server_create(ares_channel_t       *channel,
   server->udp_port    = ares__sconfig_get_port(channel, sconfig, ARES_FALSE);
   server->tcp_port    = ares__sconfig_get_port(channel, sconfig, ARES_TRUE);
   server->addr.family = sconfig->addr.family;
-  server->next_retry_time.tv_sec = 0;
+  server->next_retry_time.tv_sec  = 0;
   server->next_retry_time.tv_usec = 0;
 
   if (sconfig->addr.family == AF_INET) {
@@ -973,7 +972,8 @@ ares_status_t ares_get_server_addr(const struct server_state *server,
   return ARES_SUCCESS;
 }
 
-int ares_get_servers(ares_channel_t *channel, struct ares_addr_node **servers)
+int ares_get_servers(const ares_channel_t   *channel,
+                     struct ares_addr_node **servers)
 {
   struct ares_addr_node *srvr_head = NULL;
   struct ares_addr_node *srvr_last = NULL;
@@ -1027,7 +1027,7 @@ int ares_get_servers(ares_channel_t *channel, struct ares_addr_node **servers)
   return (int)status;
 }
 
-int ares_get_servers_ports(ares_channel_t              *channel,
+int ares_get_servers_ports(const ares_channel_t        *channel,
                            struct ares_addr_port_node **servers)
 {
   struct ares_addr_port_node *srvr_head = NULL;
@@ -1175,7 +1175,7 @@ int ares_set_servers_ports_csv(ares_channel_t *channel, const char *_csv)
   return (int)set_servers_csv(channel, _csv);
 }
 
-char *ares_get_servers_csv(ares_channel_t *channel)
+char *ares_get_servers_csv(const ares_channel_t *channel)
 {
   ares__buf_t        *buf = NULL;
   char               *out = NULL;
@@ -1216,8 +1216,7 @@ done:
 }
 
 void ares_set_server_state_callback(ares_channel_t            *channel,
-                                    ares_server_state_callback cb,
-                                    void                      *data)
+                                    ares_server_state_callback cb, void *data)
 {
   if (channel == NULL) {
     return;