Debian Bug report logs - #629260
ns_initparse(3), ns_msg_count(3), etc: please document resolver library routines

Reply or subscribe to this bug.

Display info messages

Message #5 received at [email protected] (full text, mbox, reply):

From: Jonathan Nieder <[email protected]>

To: [email protected]

Subject: [WANTED] ns_initparse(3), ns_msg_count(3), etc (please document resolver library routines)

Date: Sat, 4 Jun 2011 19:47:47 -0500

Package: manpages-dev
Version: 3.27-1
Severity: wishlist
Tags: upstream

Martin Ferrari wrote[1]:

> I'm using functions defined in arpa/nameser.h, undocumented in libc, but
> explained in chapter 12 of O'Reilly's DNS & BIND (ISBN: 0-596-00158-4).
> I do think that this lack of documentation is also a bug.

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

Message #10 received at [email protected] (full text, mbox, reply):

From: Robert Edmonds <[email protected]>

To: Jonathan Nieder <[email protected]>, [email protected]

Subject: Re: Bug#629260: [WANTED] ns_initparse(3), ns_msg_count(3), etc (please document resolver library routines)

Date: Sat, 4 Jun 2011 21:26:19 -0400

Jonathan Nieder wrote:
> Package: manpages-dev
> Version: 3.27-1
> Severity: wishlist
> Tags: upstream
> 
> Martin Ferrari wrote[1]:
> 
> > I'm using functions defined in arpa/nameser.h, undocumented in libc, but
> > explained in chapter 12 of O'Reilly's DNS & BIND (ISBN: 0-596-00158-4).
> > I do think that this lack of documentation is also a bug.
> 
> 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 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 code comes from Bind 8.2.2-P5 originally.  The BIND documentation
> says[3]:
> [3] http://ftp.isc.org/isc/bind9/cur/9.8/doc/arm/Bv9ARM.ch09.html#id2609111

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
[email protected]

Message #15 received at [email protected] (full text, mbox, reply):

From: Jonathan Nieder <[email protected]>

To: [email protected]

Subject: Re: [WANTED] ns_initparse(3), ns_msg_count(3), etc (please document resolver library routines)

Date: Sun, 19 Jun 2011 07:14:53 -0500

Robert Edmonds wrote:

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

Here's a good starting point:

https://lists.isc.org/pipermail/bind-users/2008-July/070847.html
(message-id <[email protected]>, "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.

Send a report that this bug log contains spam.