Martin Ferrari wrote[1]:

He's right --- these functions are useful and a longstanding API, and
it is not very rare to find programs that use them.

They became part of the libresolv ABI in glibc 2.9, which provides us
with a convenient list[2]:

	ns_msg_getflag
	ns_get16, ns_get32, ns_put16, ns_put32
	ns_initparse, ns_skiprr, ns_parserr
	ns_sprintrr, ns_sprintrrf
	ns_format_ttl, ns_parse_ttl
	ns_datetosecs
	ns_name_ntol, ns_name_ntop, ns_name_pton
	ns_name_unpack, ns_name_pack
	ns_name_uncompress, ns_name_compress
	ns_name_skip, ns_name_rollback
	ns_samedomain, ns_subdomain, ns_makecanon, ns_samename

The code comes from Bind 8.2.2-P5 originally.  The BIND documentation
says[3]:

	As of this writing, there is no formal "manual" of the
	libraries, except this document, header files (some of them
	provide pretty detailed explanations), and sample application
	programs.

Alas.  But we can be trailblazers; filing to coordinate.  Pointers to
relevant references (such as mailing list archives or source trees
from the time these functions were invented, which could help document
their rationale) would be especially helpful.

Thanks.
Jonathan

[1] http://bugs.debian.org/291609
[2] from resolv/Versions
[3] http://ftp.isc.org/isc/bind9/cur/9.8/doc/arm/Bv9ARM.ch09.html#id2609111

Jonathan Nieder wrote:

the only documentation i know of for some of these functions is in the
DNS & BIND book starting around p. 447 (5th edition).

it would probably be best if documentation for these functions were not
readily available in order to discourage their use in new projects, as
there are much better modern DNS message parsing libraries available.

the BIND9 9.8 documentation is totally irrelevant in this case, as BIND9
9.8 lacks the BIND4/BIND8 resolver library.  the relevant ISC product
would be libbind, but i don't believe those functions are documented in
libbind either.

(side note: i will probably request the removal of the libbind package
from debian before the next stable release, now that glibc's libresolv
has finally been fixed.)

Robert Edmonds wrote:

Here's a good starting point:

https://lists.isc.org/pipermail/bind-users/2008-July/070847.html
(message-id <g3prpq7nn1.fsf@nsa.vix.com>, "Developing against libbind",
2008-07-06)

The resolv.h API (res_init, dn_expand, etc) seems to have been
introduced in Net/2 and slowly expanded from there.  The ns_ functions
did not appear until BIND 8.