From 2f200b9170709f0c4e7b60a190d8cf52ed18b9d1 Mon Sep 17 00:00:00 2001 From: David Hotham Date: Wed, 22 May 2024 12:40:26 +0100 Subject: [PATCH] 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 | 3 +-- docs/ares_fds.3 | 2 +- docs/ares_get_servers.3 | 4 +-- docs/ares_getsock.3 | 2 +- docs/ares_queue.3 | 2 +- docs/ares_save_options.3 | 4 +-- docs/ares_set_servers_csv.3 | 2 +- docs/ares_timeout.3 | 2 +- include/ares.h | 46 +++++++++++++++++++---------------- src/lib/ares__threads.c | 4 +-- src/lib/ares_fds.c | 2 +- src/lib/ares_getsock.c | 2 +- src/lib/ares_init.c | 2 +- src/lib/ares_options.c | 20 ++++++--------- src/lib/ares_private.h | 4 +-- src/lib/ares_send.c | 2 +- src/lib/ares_timeout.c | 4 +-- src/lib/ares_update_servers.c | 25 +++++++++---------- 18 files changed, 65 insertions(+), 67 deletions(-) diff --git a/docs/ares_dup.3 b/docs/ares_dup.3 index d75e04eb..8677005f 100644 --- a/docs/ares_dup.3 +++ b/docs/ares_dup.3 @@ -9,7 +9,7 @@ ares_dup \- Duplicate a resolver channel .nf #include -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 - diff --git a/docs/ares_fds.3 b/docs/ares_fds.3 index b05ac10a..6ac116e7 100644 --- a/docs/ares_fds.3 +++ b/docs/ares_fds.3 @@ -9,7 +9,7 @@ ares_fds \- return file descriptors to select on (deprecated) .nf #include -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 diff --git a/docs/ares_get_servers.3 b/docs/ares_get_servers.3 index c1928530..9b960f45 100644 --- a/docs/ares_get_servers.3 +++ b/docs/ares_get_servers.3 @@ -10,10 +10,10 @@ ares_get_servers, ares_get_servers_ports \- Retrieve name servers from an initia .nf #include -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 diff --git a/docs/ares_getsock.3 b/docs/ares_getsock.3 index 126d7de6..b5302a39 100644 --- a/docs/ares_getsock.3 +++ b/docs/ares_getsock.3 @@ -9,7 +9,7 @@ ares_getsock \- get socket descriptors to wait on (deprecated) .nf #include -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 diff --git a/docs/ares_queue.3 b/docs/ares_queue.3 index 55fd2d47..276d31f6 100644 --- a/docs/ares_queue.3 +++ b/docs/ares_queue.3 @@ -10,7 +10,7 @@ c-ares queue status .nf #include -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); diff --git a/docs/ares_save_options.3 b/docs/ares_save_options.3 index 58e7a6b6..1a1fbfdc 100644 --- a/docs/ares_save_options.3 +++ b/docs/ares_save_options.3 @@ -9,7 +9,7 @@ ares_save_options \- Save configuration values obtained from initialized ares_ch .nf #include -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 diff --git a/docs/ares_set_servers_csv.3 b/docs/ares_set_servers_csv.3 index 8aedd6fc..875a156b 100644 --- a/docs/ares_set_servers_csv.3 +++ b/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 diff --git a/docs/ares_timeout.3 b/docs/ares_timeout.3 index 4a76da95..bdcd6916 100644 --- a/docs/ares_timeout.3 +++ b/docs/ares_timeout.3 @@ -9,7 +9,7 @@ ares_timeout \- return maximum time to wait .nf #include -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 diff --git a/include/ares.h b/include/ares.h index 12621761..a30e6fb5 100644 --- a/include/ares.h +++ b/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 } diff --git a/src/lib/ares__threads.c b/src/lib/ares__threads.c index f748b578..39d98d22 100644 --- a/src/lib/ares__threads.c +++ b/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); } diff --git a/src/lib/ares_fds.c b/src/lib/ares_fds.c index e726d4f0..e3982330 100644 --- a/src/lib/ares_fds.c +++ b/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; diff --git a/src/lib/ares_getsock.c b/src/lib/ares_getsock.c index 0353bad6..b64c0755 100644 --- a/src/lib/ares_getsock.c +++ b/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; diff --git a/src/lib/ares_init.c b/src/lib/ares_init.c index 33120ac9..71cdf582 100644 --- a/src/lib/ares_init.c +++ b/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; diff --git a/src/lib/ares_options.c b/src/lib/ares_options.c index 4306242c..6f50f2e4 100644 --- a/src/lib/ares_options.c +++ b/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; diff --git a/src/lib/ares_private.h b/src/lib/ares_private.h index 47a70124..e60c41ea 100644 --- a/src/lib/ares_private.h +++ b/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; diff --git a/src/lib/ares_send.c b/src/lib/ares_send.c index 54f2b504..d15a9b95 100644 --- a/src/lib/ares_send.c +++ b/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; diff --git a/src/lib/ares_timeout.c b/src/lib/ares_timeout.c index 4e80580b..7e60acb2 100644 --- a/src/lib/ares_timeout.c +++ b/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; diff --git a/src/lib/ares_update_servers.c b/src/lib/ares_update_servers.c index 1d279a3b..847a78a6 100644 --- a/src/lib/ares_update_servers.c +++ b/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;