[01/24] resolv: Deprecate legacy interfaces in libresolv

  Debugging interfaces: p_*, fp_*, and sym_* could conceivably be
used to produce debug out, but these functions have not been
updated to parse more resource records, so they are not very useful
today.  Likewise for ns_sprintrr and ns_sprintrrf.  ns_format_ttl and
ns_parse_ttl are related to these.

Internal implementation details: res_isourserver is probably only
useful in the implementation of a stub resolver, and so is
res_nameinquery.

Unclear semantics and bad performance: ns_samedomain, ns_subdomain,
ns_makecanon, ns_samename do textual converions & copies instead of
checking equivalence of the wire format.

inet_ntoa cannot handle IPv6 addresses.

res_hostalias has been superseded by getaddrinfo with AI_CANONNAME.
hostalias is not thread-safe.

Some functions have int as size arguments instead of size_t, so they
do not follow current coding practices.  However, dn_expand and
b64_ntop are somewhat widely used (to name just two examples), so
deprecating them seems problematic.
---
 NEWS                  | 14 +++++++
 inet/arpa/inet.h      |  3 +-
 resolv/arpa/nameser.h | 33 ++++++++++++-----
 resolv/resolv.h       | 86 +++++++++++++++++++++++++++----------------
 4 files changed, 95 insertions(+), 41 deletions(-)
  

On Jul 15 2021, Florian Weimer via Libc-alpha wrote:

> Debugging interfaces: p_*, fp_*, and sym_* could conceivably be
> used to produce debug out, but these functions have not been
> updated to parse more resource records, so they are not very useful
> today.  Likewise for ns_sprintrr and ns_sprintrrf.  ns_format_ttl and
> ns_parse_ttl are related to these.
>
> Internal implementation details: res_isourserver is probably only
> useful in the implementation of a stub resolver, and so is
> res_nameinquery.
>
> Unclear semantics and bad performance: ns_samedomain, ns_subdomain,
> ns_makecanon, ns_samename do textual converions & copies instead of
> checking equivalence of the wire format.
>
> inet_ntoa cannot handle IPv6 addresses.

ITYM inet_neta.

> res_hostalias has been superseded by getaddrinfo with AI_CANONNAME.
> hostalias is not thread-safe.
>
> Some functions have int as size arguments instead of size_t, so they
> do not follow current coding practices.  However, dn_expand and
> b64_ntop are somewhat widely used (to name just two examples), so
> deprecating them seems problematic.

Ok.

Andreas.
  

* Andreas Schwab:

> On Jul 15 2021, Florian Weimer via Libc-alpha wrote:
>
>> Debugging interfaces: p_*, fp_*, and sym_* could conceivably be
>> used to produce debug out, but these functions have not been
>> updated to parse more resource records, so they are not very useful
>> today.  Likewise for ns_sprintrr and ns_sprintrrf.  ns_format_ttl and
>> ns_parse_ttl are related to these.
>>
>> Internal implementation details: res_isourserver is probably only
>> useful in the implementation of a stub resolver, and so is
>> res_nameinquery.
>>
>> Unclear semantics and bad performance: ns_samedomain, ns_subdomain,
>> ns_makecanon, ns_samename do textual converions & copies instead of
>> checking equivalence of the wire format.
>>
>> inet_ntoa cannot handle IPv6 addresses.
>
> ITYM inet_neta.

Indeed, fixed.

Thanks,
Florian
  

On 7/15/21 5:09 AM, Florian Weimer via Libc-alpha wrote:
> Debugging interfaces: p_*, fp_*, and sym_* could conceivably be
> used to produce debug out, but these functions have not been
> updated to parse more resource records, so they are not very useful
> today.  Likewise for ns_sprintrr and ns_sprintrrf.  ns_format_ttl and
> ns_parse_ttl are related to these.
> 
> Internal implementation details: res_isourserver is probably only
> useful in the implementation of a stub resolver, and so is
> res_nameinquery.
> 
> Unclear semantics and bad performance: ns_samedomain, ns_subdomain,
> ns_makecanon, ns_samename do textual converions & copies instead of
> checking equivalence of the wire format.
> 
> inet_ntoa cannot handle IPv6 addresses.
> 
> res_hostalias has been superseded by getaddrinfo with AI_CANONNAME.
> hostalias is not thread-safe.
> 
> Some functions have int as size arguments instead of size_t, so they
> do not follow current coding practices.  However, dn_expand and
> b64_ntop are somewhat widely used (to name just two examples), so
> deprecating them seems problematic.

OK for 2.34.

Reviewed-by: Carlos O'Donell <carlos@systemhalted.org>

> ---
>  NEWS                  | 14 +++++++
>  inet/arpa/inet.h      |  3 +-
>  resolv/arpa/nameser.h | 33 ++++++++++++-----
>  resolv/resolv.h       | 86 +++++++++++++++++++++++++++----------------
>  4 files changed, 95 insertions(+), 41 deletions(-)
> 
> diff --git a/NEWS b/NEWS
> index 13ffe627da..4df348cce5 100644
> --- a/NEWS
> +++ b/NEWS
> @@ -93,6 +93,20 @@ Deprecated and removed features, and other changes affecting compatibility:
>  * The function pthread_yield has been deprecated; programs should use
>    the equivalent standard function sched_yield instead.
>  
> +* The function inet_neta declared in <arpa/inet.h> has been deprecated.
> +
> +* Various rarely-used functions declared in <resolv.h> and
> +  <arpa/nameser.h> have been deprecated.  Applications are encouraged to
> +  use dedicated DNS processing libraries if applicable.  For <resolv.h>,
> +  this affects the functions dn_count_labels, fp_nquery, fp_query,
> +  fp_resstat, hostalias, loc_aton, loc_ntoa, p_cdname, p_cdnname,
> +  p_class, p_fqname, p_fqnname, p_option, p_query, p_rcode, p_time,
> +  p_type, putlong, putshort, res_hostalias, res_isourserver,
> +  res_nameinquery, res_queriesmatch, res_randomid, sym_ntop, sym_ntos,
> +  sym_ston.  For <arpa/nameser.h>, the functions ns_datetosecs,
> +  ns_format_ttl, ns_makecanon, ns_parse_ttl, ns_samedomain, ns_samename,
> +  ns_sprintrr, ns_sprintrrf, ns_subdomain have been deprecated.

OK.

> +
>  * The pthread cancellation handler is now installed with SA_RESTART and
>    pthread_cancel will always send the internal SIGCANCEL on a cancellation
>    request.  It should not be visible to application since the cancellation
> diff --git a/inet/arpa/inet.h b/inet/arpa/inet.h
> index 3a99dbfa5a..54c9c6d468 100644
> --- a/inet/arpa/inet.h
> +++ b/inet/arpa/inet.h
> @@ -74,7 +74,8 @@ extern int inet_aton (const char *__cp, struct in_addr *__inp) __THROW;
>  
>  /* Format a network number NET into presentation format and place result
>     in buffer starting at BUF with length of LEN bytes.  */
> -extern char *inet_neta (in_addr_t __net, char *__buf, size_t __len) __THROW;
> +extern char *inet_neta (in_addr_t __net, char *__buf, size_t __len) __THROW
> +  __attribute_deprecated_msg__ ("Use inet_ntop instead");

OK.

>  
>  /* Convert network number for interface type AF in buffer starting at
>     CP to presentation format.  The result will specifiy BITS bits of
> diff --git a/resolv/arpa/nameser.h b/resolv/arpa/nameser.h
> index a99d5ec508..017d7b194a 100644
> --- a/resolv/arpa/nameser.h
> +++ b/resolv/arpa/nameser.h
> @@ -52,6 +52,12 @@
>  #include <sys/types.h>
>  #include <stdint.h>
>  
> +#ifdef _LIBC
> +# define __NAMESER_DEPRECATED
> +#else
> +# define __NAMESER_DEPRECATED __attribute_deprecated__
> +#endif
> +
>  /*
>   * Define constants based on RFC 883, RFC 1034, RFC 1035
>   */
> @@ -401,14 +407,18 @@ int		ns_skiprr (const unsigned char *, const unsigned char *,
>  int		ns_parserr (ns_msg *, ns_sect, int, ns_rr *) __THROW;
>  int		ns_sprintrr (const ns_msg *, const ns_rr *,
>  			     const char *, const char *, char *, size_t)
> -     __THROW;
> +  __THROW __NAMESER_DEPRECATED;
>  int		ns_sprintrrf (const unsigned char *, size_t, const char *,
>  			      ns_class, ns_type, unsigned long,
>  			      const unsigned char *, size_t, const char *,
> -			      const char *, char *, size_t) __THROW;
> -int		ns_format_ttl (unsigned long, char *, size_t) __THROW;
> -int		ns_parse_ttl (const char *, unsigned long *) __THROW;
> -uint32_t	ns_datetosecs (const char *, int *) __THROW;
> +			      const char *, char *, size_t)
> +  __THROW __NAMESER_DEPRECATED;
> +int		ns_format_ttl (unsigned long, char *, size_t)
> +  __THROW __NAMESER_DEPRECATED;
> +int		ns_parse_ttl (const char *, unsigned long *)
> +  __THROW __NAMESER_DEPRECATED;
> +uint32_t	ns_datetosecs (const char *, int *)
> +  __THROW __NAMESER_DEPRECATED;
>  int		ns_name_ntol (const unsigned char *, unsigned char *, size_t)
>       __THROW;
>  int		ns_name_ntop (const unsigned char *, char *, size_t) __THROW;
> @@ -431,10 +441,15 @@ int		ns_name_skip (const unsigned char **, const unsigned char *)
>  void		ns_name_rollback (const unsigned char *,
>  				  const unsigned char **,
>  				  const unsigned char **) __THROW;
> -int		ns_samedomain (const char *, const char *) __THROW;
> -int		ns_subdomain (const char *, const char *) __THROW;
> -int		ns_makecanon (const char *, char *, size_t) __THROW;
> -int		ns_samename (const char *, const char *) __THROW;
> +
> +int		ns_samedomain (const char *, const char *) __THROW
> +  __NAMESER_DEPRECATED;
> +int		ns_subdomain (const char *, const char *) __THROW
> +  __NAMESER_DEPRECATED;
> +int		ns_makecanon (const char *, char *, size_t) __THROW
> +  __NAMESER_DEPRECATED;
> +int		ns_samename (const char *, const char *) __THROW
> +  __NAMESER_DEPRECATED;
>  __END_DECLS
>  
>  #include <arpa/nameser_compat.h>
> diff --git a/resolv/resolv.h b/resolv/resolv.h
> index a039a9e636..02a35173e9 100644
> --- a/resolv/resolv.h
> +++ b/resolv/resolv.h
> @@ -174,14 +174,27 @@ __END_DECLS
>  #define res_search		__res_search
>  #define res_send		__res_send
>  
> +#ifdef _LIBC
> +# define __RESOLV_DEPRECATED
> +# define __RESOLV_DEPRECATED_MSG(msg)
> +#else
> +# define __RESOLV_DEPRECATED __attribute_deprecated__
> +# define __RESOLV_DEPRECATED_MSG(msg) __attribute_deprecated_msg__ (msg)
> +#endif
> +
>  __BEGIN_DECLS
> -void		fp_nquery (const unsigned char *, int, FILE *) __THROW;
> -void		fp_query (const unsigned char *, FILE *) __THROW;
> -const char *	hostalias (const char *) __THROW;
> -void		p_query (const unsigned char *) __THROW;
> +void		fp_nquery (const unsigned char *, int, FILE *) __THROW
> +  __RESOLV_DEPRECATED;
> +void		fp_query (const unsigned char *, FILE *) __THROW
> +  __RESOLV_DEPRECATED;
> +const char *	hostalias (const char *) __THROW
> +  __RESOLV_DEPRECATED_MSG ("use getaddrinfo instead");
> +void		p_query (const unsigned char *) __THROW
> +  __RESOLV_DEPRECATED;
>  void		res_close (void) __THROW;
>  int		res_init (void) __THROW;
> -int		res_isourserver (const struct sockaddr_in *) __THROW;
> +int		res_isourserver (const struct sockaddr_in *) __THROW
> +  __RESOLV_DEPRECATED;
>  int		res_mkquery (int, const char *, int, int,
>  			     const unsigned char *, int, const unsigned char *,
>  			     unsigned char *, int) __THROW;
> @@ -238,50 +251,61 @@ int		res_hnok (const char *) __THROW;
>  int		res_ownok (const char *) __THROW;
>  int		res_mailok (const char *) __THROW;
>  int		res_dnok (const char *) __THROW;
> -int		sym_ston (const struct res_sym *, const char *, int *) __THROW;
> -const char *	sym_ntos (const struct res_sym *, int, int *) __THROW;
> -const char *	sym_ntop (const struct res_sym *, int, int *) __THROW;
> +int		sym_ston (const struct res_sym *, const char *, int *) __THROW
> +  __RESOLV_DEPRECATED;
> +const char *	sym_ntos (const struct res_sym *, int, int *) __THROW
> +  __RESOLV_DEPRECATED;
> +const char *	sym_ntop (const struct res_sym *, int, int *) __THROW
> +  __RESOLV_DEPRECATED;
>  int		b64_ntop (const unsigned char *, size_t, char *, size_t)
> -     __THROW;
> +  __THROW;
>  int		b64_pton (char const *, unsigned char *, size_t) __THROW;
> -int		loc_aton (const char *__ascii, unsigned char *__binary) __THROW;
> -const char *	loc_ntoa (const unsigned char *__binary, char *__ascii) __THROW;
> +int		loc_aton (const char *__ascii, unsigned char *__binary) __THROW
> +  __RESOLV_DEPRECATED;
> +const char *	loc_ntoa (const unsigned char *__binary, char *__ascii) __THROW
> +  __RESOLV_DEPRECATED;
>  int		dn_skipname (const unsigned char *, const unsigned char *)
> -     __THROW;
> -void		putlong (uint32_t, unsigned char *) __THROW;
> -void		putshort (uint16_t, unsigned char *) __THROW;
> -const char *	p_class (int) __THROW;
> -const char *	p_time (uint32_t) __THROW;
> -const char *	p_type (int) __THROW;
> -const char *	p_rcode (int) __THROW;
> -const unsigned char * p_cdnname (const unsigned char *,
> -				 const unsigned char *, int, FILE *) __THROW;
> +  __THROW;
> +void		putlong (uint32_t, unsigned char *) __THROW
> +  __RESOLV_DEPRECATED_MSG ("use NS_PUT16 instead");
> +void		putshort (uint16_t, unsigned char *) __THROW
> +  __RESOLV_DEPRECATED_MSG ("use NS_PUT32 instead");
> +const char *	p_class (int) __THROW __RESOLV_DEPRECATED;
> +const char *	p_time (uint32_t) __THROW __RESOLV_DEPRECATED;
> +const char *	p_type (int) __THROW __RESOLV_DEPRECATED;
> +const char *	p_rcode (int) __THROW __RESOLV_DEPRECATED;
> +const unsigned char * p_cdnname (const unsigned char *, const unsigned char *,
> +				 int, FILE *) __THROW __RESOLV_DEPRECATED;
>  const unsigned char * p_cdname (const unsigned char *, const unsigned char *,
> -				FILE *) __THROW;
> +				FILE *) __THROW __RESOLV_DEPRECATED;
>  const unsigned char * p_fqnname (const unsigned char *__cp,
>  				 const unsigned char *__msg,
> -				 int, char *, int) __THROW;
> -const unsigned char * p_fqname (const unsigned char *,
> -				const unsigned char *, FILE *) __THROW;
> -const char *	p_option (unsigned long __option) __THROW;
> -int		dn_count_labels (const char *) __THROW;
> +				 int, char *, int) __THROW __RESOLV_DEPRECATED;
> +const unsigned char * p_fqname (const unsigned char *, const unsigned char *,
> +				FILE *) __THROW __RESOLV_DEPRECATED;
> +const char *	p_option (unsigned long __option) __THROW __RESOLV_DEPRECATED;
> +int		dn_count_labels (const char *) __THROW __RESOLV_DEPRECATED;
>  int		dn_comp (const char *, unsigned char *, int, unsigned char **,
>  			 unsigned char **) __THROW;
>  int		dn_expand (const unsigned char *, const unsigned char *,
>  			   const unsigned char *, char *, int) __THROW;
> -unsigned int	res_randomid (void) __THROW;
> +unsigned int	res_randomid (void) __THROW
> +  __RESOLV_DEPRECATED_MSG ("use getentropy instead");
>  int		res_nameinquery (const char *, int, int,
>  				 const unsigned char *,
> -				 const unsigned char *) __THROW;
> +				 const unsigned char *) __THROW
> +  __RESOLV_DEPRECATED;
>  int		res_queriesmatch (const unsigned char *,
>  				  const unsigned char *,
>  				  const unsigned char *,
> -				  const unsigned char *) __THROW;
> +				  const unsigned char *) __THROW
> +  __RESOLV_DEPRECATED;
>  /* Things involving a resolver context. */
>  int		res_ninit (res_state) __THROW;
> -void		fp_resstat (const res_state, FILE *) __THROW;
> +void		fp_resstat (const res_state, FILE *) __THROW
> +  __RESOLV_DEPRECATED;
>  const char *	res_hostalias (const res_state, const char *, char *, size_t)
> -     __THROW;
> +     __THROW __RESOLV_DEPRECATED_MSG ("use getaddrinfo instead");
>  int		res_nquery (res_state, const char *, int, int,
>  			    unsigned char *, int) __THROW;
>  int		res_nsearch (res_state, const char *, int, int,
> 

OK.