[PATCH/RFC] resolver_r.3: New page documenting res_ninit() et al

[PATCH/RFC] resolver_r.3: New page documenting res_ninit() et al

[Jonathan Nieder]

Readers learning about the glibc resolver implementation might
appreciate some documentation for these basic functions.  They are
reentrant analogues invented by vixie around 1998 (?) for the
traditional BSD res_* functions.

The BIND 8 changelog (item 384) says:

	there is now a nearly-thread-safe resolver API, with
	the old non-thread-safe API being a set of stubs on
	top of this.  it is possible to program without _res.
	note: the documentation has not been updated.  also
	note: IRS is a thread-ready API, get*by*() is not.
	(see ../contrib/manyhosts for an example application.)

Luckily the glibc source tree includes some documentation for these
functions by Mark Kettenis at resolv/README, under the heading "Using
the resolver in multi-threaded code".  Steal that text, and with
minimal changes make it into a manpage.

To avoid requiring yet another license document to be distributed with
man-pages, the new manpage uses GPL-2+ as its license instead of
glibc's LGPL-2.1+.

Signed-off-by: Jonathan Nieder <jrnieder-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
---
Hi,

While looking over the glibc resolver code, I started to wish some
documentation like this existed.  As mentioned above, the text is
mostly stolen from glibc's resolv/README.  What do you think?
Improvements?  Simplifications?

Maybe the license should be something like "LGPL-2.1+ or (at your
option) GPL-2+" instead.

 man3/res_ninit.3        |    1 +
 man3/res_nmkquery.3     |    1 +
 man3/res_nquery.3       |    1 +
 man3/res_nquerydomain.3 |    1 +
 man3/res_nsearch.3      |    1 +
 man3/res_nsend.3        |    1 +
 man3/resolver.3         |    1 +
 man3/resolver_r.3       |  136 +++++++++++++++++++++++++++++++++++++++++++++++
 8 files changed, 143 insertions(+), 0 deletions(-)
 create mode 100644 man3/res_ninit.3
 create mode 100644 man3/res_nmkquery.3
 create mode 100644 man3/res_nquery.3
 create mode 100644 man3/res_nquerydomain.3
 create mode 100644 man3/res_nsearch.3
 create mode 100644 man3/res_nsend.3
 create mode 100644 man3/resolver_r.3

diff --git a/man3/res_ninit.3 b/man3/res_ninit.3
new file mode 100644
index 00000000..9963b525
--- /dev/null
+++ b/man3/res_ninit.3
@@ -0,0 +1 @@
+.so man3/resolver_r.3
diff --git a/man3/res_nmkquery.3 b/man3/res_nmkquery.3
new file mode 100644
index 00000000..9963b525
--- /dev/null
+++ b/man3/res_nmkquery.3
@@ -0,0 +1 @@
+.so man3/resolver_r.3
diff --git a/man3/res_nquery.3 b/man3/res_nquery.3
new file mode 100644
index 00000000..9963b525
--- /dev/null
+++ b/man3/res_nquery.3
@@ -0,0 +1 @@
+.so man3/resolver_r.3
diff --git a/man3/res_nquerydomain.3 b/man3/res_nquerydomain.3
new file mode 100644
index 00000000..9963b525
--- /dev/null
+++ b/man3/res_nquerydomain.3
@@ -0,0 +1 @@
+.so man3/resolver_r.3
diff --git a/man3/res_nsearch.3 b/man3/res_nsearch.3
new file mode 100644
index 00000000..9963b525
--- /dev/null
+++ b/man3/res_nsearch.3
@@ -0,0 +1 @@
+.so man3/resolver_r.3
diff --git a/man3/res_nsend.3 b/man3/res_nsend.3
new file mode 100644
index 00000000..9963b525
--- /dev/null
+++ b/man3/res_nsend.3
@@ -0,0 +1 @@
+.so man3/resolver_r.3
diff --git a/man3/resolver.3 b/man3/resolver.3
index a72dde7b..44f8f902 100644
--- a/man3/resolver.3
+++ b/man3/resolver.3
@@ -261,6 +261,7 @@ of the compressed name, or \-1 if an error occurs.
 .SH "CONFORMING TO"
 4.3BSD.
 .SH "SEE ALSO"
+.BR resolver_r (3),
 .BR gethostbyname (3),
 .BR resolv.conf (5),
 .BR resolver (5),
diff --git a/man3/resolver_r.3 b/man3/resolver_r.3
new file mode 100644
index 00000000..f2ced438
--- /dev/null
+++ b/man3/resolver_r.3
@@ -0,0 +1,136 @@
+.\" Copyright (C) 2000 Free Software Foundation, Inc.
+.\" Copyright (c) 2011 Jonathan Nieder
+.\" License: GPL-2+
+.\"
+.\" Based on glibc's resolv/README which was written by Mark Kettenis,
+.\" 2000-07-29.
+.\"
+.TH RESOLVER_R 3 2011-07-03 "GNU" "Linux Programmer's Manual"
+.SH NAME
+res_ninit, res_nquery, res_nsearch, res_nquerydomain, res_nmkquery,
+res_nsend \- reentrant resolver routines
+.SH SYNOPSIS
+.nf
+.B #include <resolv.h>
+.sp
+.B typedef struct state *res_state;
+.sp
+.BI "int res_ninit(res_state " statep ");"
+.sp
+.BI "int res_nquery(res_state " statep ", const char *" dname ", int " class ,
+.RS
+.BI "int " type ", unsigned char *" answer ", int " anslen );
+.RE
+.sp
+.BI "int res_nsearch(res_state " statep ", const char *" dname ", int " class ,
+.RS
+.BI "int " type ", unsigned char *" answer ", int " anslen );
+.RE
+.sp
+.BI "int res_nquerydomain(res_state " statep ", const char *" name ,
+.RS
+.BI "const char *" domain ", int " class ", int " type ,
+.BI "unsigned char *" answer ", int " anslen );
+.RE
+.sp
+.BI "int res_nmkquery(res_state " statep ", int " op ", const char *" dname ",
+.RS
+.BI "int " class ", int " type ", char *" data ", int " datalen ,
+.BI "struct rrec *" newrr ", char *" buf ", int " buflen );
+.RE
+.sp
+.BI "int res_nsend(res_state " statep ", const char *" msg ", int " msglen ,
+.RS
+.BI "char *" answer ", int " anslen );
+.RE
+.fi
+.sp
+Link with \fI\-lresolv\fP.
+.SH DESCRIPTION
+These functions are the reentrant equivalents of the functions described in
+.BR resolver (3).
+.PP
+The traditional resolver interfaces such as
+.BR res_init ()
+and
+.BR res_query ()
+use some static (global) state stored in the
+.I _res
+structure.
+Therefore, those interfaces are not thread-safe.
+Therefore, BIND 8.2 introduced a set of new interfaces
+.BR res_ninit (),
+.BR res_query (),
+etc that take a
+.B res_state
+as their first argument, so you can use a per-thread resolver state.
+.SH RETURN VALUE
+See
+.BR resolver (3).
+.SH VERSIONS
+First appeared in BIND 8.2-T1A;
+made their way into glibc in version 2.1.3.
+.SH CONFORMING TO
+BIND 8
+.SH NOTES
+.PP
+In glibc, when you link with \fI-lpthread\fP,
+a per-thread resolver state is already present.
+It can be accessed using
+.IR _res ,
+which has been defined as a macro in a similar way to the
+.I errno
+and
+.I h_errno
+variables.
+This per-thread resolver state is also used for the
+.BR gethostby *
+family of functions, which means that for example
+.B gethostbyname_r
+is fully thread-safe and re-entrant.
+.PP
+The traditional
+.BR res_ *
+interfaces, however, use a single resolver state and are
+still thread-unsafe.
+The resolver state is the same resolver state that is used
+for the initial ("main") thread.
+.PP
+This has the following consequences for existing binaries and source
+code:
+.IP * 3
+Single-threaded programs work as they always did.
+.IP *
+Multi-threaded programs that use the traditional resolver interfaces
+in the "main" thread continue to work, except that they no longer see
+any changes in the global resolver state caused by calls to, for example,
+.BR gethostbyname ()
+in other threads.
+.IP *
+Multi-threaded programs built against glibc versions before 2.1.3 that
+use the traditional resolver interfaces in more than one thread will
+be just as buggy as before (there are no problems as long as they use
+proper locking).
+If you recompile these programs, manipulating the
+.I _res
+structure in threads other than the "main" thread will appear to have
+no effect, though.
+.IP *
+In multi-threaded programs that manipulate the _res structure, calls to
+functions like
+.BR gethostbyname ()
+in threads other than the "main" thread won't be influenced by the those
+changes any more.
+So if you set RES_USE_INET6, a call to
+.BR gethostbyname ()
+won't return any IPv6 hosts any more.
+If you recompile such programs, manipulating the _res structure will
+affect the thread in which you do so instead of the "main" thread.
+.PP
+It is recommended to use the thread-safe interfaces in new code
+unless compatibility with older systems is needed.
+.SH SEE ALSO
+.BR resolver (3),
+.BR errno (3),
+.BR gethostbyname (3),
+.BR getaddrinfo (3)
-- 
1.7.6

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH/RFC] resolver_r.3: New page documenting res_ninit() et al

[Jonathan Nieder]

Hi again,

Jonathan Nieder wrote:

> --- /dev/null
> +++ b/man3/resolver_r.3
> @@ -0,0 +1,136 @@
[...]
> +.B typedef struct state *res_state;

Looking over [1], it occurs to me that treating "res_state" as an
opaque type doesn't work if this API is to be actually usable.  A
typical program will look like this:

	struct __res_state res;

	if (res_ninit(&res))
		die_errno("cannot initialize resolver");
	...

Is "struct __res_state" really supposed to be part of the public
API?  I guess it is.

So I'd suggest squashing in the mini-patch below to reflect that.
Sorry for the noise.

[1] https://lists.isc.org/pipermail/bind-users/2008-July/070847.html

Signed-off-by: Jonathan Nieder <jrnieder-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
---
 man3/resolver_r.3 |    3 ++-
 1 files changed, 2 insertions(+), 1 deletions(-)

diff --git a/man3/resolver_r.3 b/man3/resolver_r.3
index f2ced438..a70834b4 100644
--- a/man3/resolver_r.3
+++ b/man3/resolver_r.3
@@ -13,7 +13,8 @@ res_nsend \- reentrant resolver routines
 .nf
 .B #include <resolv.h>
 .sp
-.B typedef struct state *res_state;
+.B struct __res_state;
+.B typedef struct __res_state *res_state;
 .sp
 .BI "int res_ninit(res_state " statep ");"
 .sp
-- 
1.7.6

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH/RFC] resolver_r.3: New page documenting res_ninit() et al

[Stefan Puiu]

Hi,

IIRC bind 8 (or libbind) also comes with its own manpages. Ages ago I
stole the info from their resolver.3 page and merged it with the page
distributed with glibc (the current version is taken from there as
well, IIRC). The patch got somehow lost through the cracks, I think...

Or do you see any licensing issues with doing that?

OTOH, if you want to keep your approach and add another page for the
reentrant functions, you might want to add a pointer in resolver.3 so
people know there's another page as well :).

Just my 2 cents,
Stefan.

On Mon, Jul 4, 2011 at 8:33 AM, Jonathan Nieder <jrnieder-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> Hi again,
>
> Jonathan Nieder wrote:
>
>> --- /dev/null
>> +++ b/man3/resolver_r.3
>> @@ -0,0 +1,136 @@
> [...]
>> +.B typedef struct state *res_state;
>
> Looking over [1], it occurs to me that treating "res_state" as an
> opaque type doesn't work if this API is to be actually usable.  A
> typical program will look like this:
>
>        struct __res_state res;
>
>        if (res_ninit(&res))
>                die_errno("cannot initialize resolver");
>        ...
>
> Is "struct __res_state" really supposed to be part of the public
> API?  I guess it is.
>
> So I'd suggest squashing in the mini-patch below to reflect that.
> Sorry for the noise.
>
> [1] https://lists.isc.org/pipermail/bind-users/2008-July/070847.html
>
> Signed-off-by: Jonathan Nieder <jrnieder-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
> ---
>  man3/resolver_r.3 |    3 ++-
>  1 files changed, 2 insertions(+), 1 deletions(-)
>
> diff --git a/man3/resolver_r.3 b/man3/resolver_r.3
> index f2ced438..a70834b4 100644
> --- a/man3/resolver_r.3
> +++ b/man3/resolver_r.3
> @@ -13,7 +13,8 @@ res_nsend \- reentrant resolver routines
>  .nf
>  .B #include <resolv.h>
>  .sp
> -.B typedef struct state *res_state;
> +.B struct __res_state;
> +.B typedef struct __res_state *res_state;
>  .sp
>  .BI "int res_ninit(res_state " statep ");"
>  .sp
> --
> 1.7.6
>
> --
> To unsubscribe from this list: send the line "unsubscribe linux-man" in
> the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH/RFC] resolver_r.3: New page documenting res_ninit() et al

[Jonathan Nieder]

Hi,

Stefan Puiu wrote:

> IIRC bind 8 (or libbind) also comes with its own manpages.

libbind does.  Good find; not sure how I missed that.

> Ages ago I
> stole the info from their resolver.3 page and merged it with the page
> distributed with glibc (the current version is taken from there as
> well, IIRC). The patch got somehow lost through the cracks, I think...
>
> Or do you see any licensing issues with doing that?

libbind's manpages are permissively (ISC) licensed and so pretty much
hassle-free to reuse.  Could you send a link or other pointer (e.g.,
message-id) to your patch?

> OTOH, if you want to keep your approach and add another page for the
> reentrant functions, you might want to add a pointer in resolver.3 so
> people know there's another page as well :).

I snuck in a link in the SEE ALSO section.  If you have ideas for
where to broach the subject elsewhere (maybe in the paragraph
discussing _res?), I'd be happy to take them. :)

Thanks for looking it over.
Jonathan
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH/RFC] resolver_r.3: New page documenting res_ninit() et al

[Stefan Puiu]

Hi,

On Mon, Jul 4, 2011 at 12:37 PM, Jonathan Nieder <jrnieder-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
[...]
>> Ages ago I
>> stole the info from their resolver.3 page and merged it with the page
>> distributed with glibc (the current version is taken from there as
>> well, IIRC). The patch got somehow lost through the cracks, I think...
>>
>> Or do you see any licensing issues with doing that?
>
> libbind's manpages are permissively (ISC) licensed and so pretty much
> hassle-free to reuse.  Could you send a link or other pointer (e.g.,
> message-id) to your patch?

That was before there was a linux-man mailing list; I still have
Michael's replies, but apparently I don't the one I sent. I will check
my home computer, maybe I have a copy of it there. I'll get back with
a reply if I manage to find it.

On re-reading Michael's replies, I see there was a problem with the
format of the man pages - the one from libbind is using mdoc, while
the one in man-pages uses the newer man(7) format. Just a heads up.

>
>> OTOH, if you want to keep your approach and add another page for the
>> reentrant functions, you might want to add a pointer in resolver.3 so
>> people know there's another page as well :).
>
> I snuck in a link in the SEE ALSO section.  If you have ideas for
> where to broach the subject elsewhere (maybe in the paragraph
> discussing _res?), I'd be happy to take them. :)

Maybe at the beginning you could say that the man page documents only
the non-reentrant functions? OTOH, as far as I can make of the old
email exchange, the current man page is based on what BIND
4.9.something was shipping, probably before anybody started thinking
about multithreading :).

>
> Thanks for looking it over.
> Jonathan
>
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH/RFC] resolver_r.3: New page documenting res_ninit() et al

[Stefan Puiu]

[-- Attachment #1: Type: text/plain, Size: 2348 bytes --]

Hi,

I believe the attached file is the page I converted from libbind docs
for resolver.3; I had to spend some time looking for it. It's been 5
years, so I don't remember too many details, so please don't be too
harsh :). I lifted and converted the man page from BIND 8.2.3, which
was quite recent at the time (and I don't think the API changed much
until 8.4.x).

Thanks,
Stefan.

On Mon, Jul 4, 2011 at 12:48 PM, Stefan Puiu <stefan.puiu-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> Hi,
>
> On Mon, Jul 4, 2011 at 12:37 PM, Jonathan Nieder <jrnieder-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> [...]
>>> Ages ago I
>>> stole the info from their resolver.3 page and merged it with the page
>>> distributed with glibc (the current version is taken from there as
>>> well, IIRC). The patch got somehow lost through the cracks, I think...
>>>
>>> Or do you see any licensing issues with doing that?
>>
>> libbind's manpages are permissively (ISC) licensed and so pretty much
>> hassle-free to reuse.  Could you send a link or other pointer (e.g.,
>> message-id) to your patch?
>
> That was before there was a linux-man mailing list; I still have
> Michael's replies, but apparently I don't the one I sent. I will check
> my home computer, maybe I have a copy of it there. I'll get back with
> a reply if I manage to find it.
>
> On re-reading Michael's replies, I see there was a problem with the
> format of the man pages - the one from libbind is using mdoc, while
> the one in man-pages uses the newer man(7) format. Just a heads up.
>
>>
>>> OTOH, if you want to keep your approach and add another page for the
>>> reentrant functions, you might want to add a pointer in resolver.3 so
>>> people know there's another page as well :).
>>
>> I snuck in a link in the SEE ALSO section.  If you have ideas for
>> where to broach the subject elsewhere (maybe in the paragraph
>> discussing _res?), I'd be happy to take them. :)
>
> Maybe at the beginning you could say that the man page documents only
> the non-reentrant functions? OTOH, as far as I can make of the old
> email exchange, the current man page is based on what BIND
> 4.9.something was shipping, probably before anybody started thinking
> about multithreading :).
>
>>
>> Thanks for looking it over.
>> Jonathan
>>
>

[-- Attachment #2: resolver.3 --]
[-- Type: application/octet-stream, Size: 15391 bytes --]

.\" Copyright (c) 1985, 1995 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms are permitted provided
.\" that: (1) source distributions retain this entire copyright notice and
.\" comment, and (2) distributions including binaries display the following
.\" acknowledgement:  ``This product includes software developed by the
.\" University of California, Berkeley and its contributors'' in the
.\" documentation or other materials provided with the distribution and in
.\" all advertising materials mentioning features or use of this software.
.\" Neither the name of the University nor the names of its contributors may
.\" be used to endorse or promote products derived from this software without
.\" specific prior written permission.
.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
.\"
.\"	@(#)resolver.3	6.5 (Berkeley) 6/23/90
.\"	$Id: resolver.3,v 8.13 2000/12/05 02:37:33 vixie Exp $
.\"
.TH RESOLVER 3 2006-01-21 "BSD" "Linux Programmer's Manual"
.SH NAME
 res_ninit , res_ourserver_p , fp_resstat , res_hostalias , res_pquery
, res_nquery , res_nsearch , res_nquerydomain , res_nmkquery ,
res_nsend , res_nclose , dn_comp , dn_expand , hstrerror , res_init ,
res_isourserver , fp_nquery , p_query , hostalias , res_query ,
res_search , res_querydomain , res_mkquery , res_send , res_close , herror \- resolver routines
.SH SYNOPSIS
.nf
.B #include <sys/types.h>
.B #include <netinet/in.h>
.B #include <arpa/nameser.h>
.B #include <resolv.h>
.B typedef struct __res_state *res_state;
.sp
.BI "int res_ninit (res_state " statp );
.sp
.BI "int res_ourserver_p(const res_state " statp ", const struct sockaddr_in *" addr );
.sp
.BI "void fp_resstat(const res_state " statp ", FILE *" fp );
.sp
.BI "res_hostalias(const res_state " statp ", const char *" name , 
.RS
.BI "char *" buf ", size_t " buflen );
.RE
.sp
.BI "int res_pquery(const res_state " statp ", const u_char *"msg , 
.RS
.BI "int " msglen ", FILE *"fp );
.RE
.sp
.BI "int res_nquery(res_state " statp ", const char *" dname,
.RS 
.BI "int " class ", int " type ", u_char *"answer ", int " anslen );
.RE
.sp
.BI "int res_nsearch(res_state " statp ", const char *"dname,
.RS 
.BI "int "class ", int " type ", u_char *" answer ", int " anslen );
.RE
.sp
.BI "int res_nquerydomain(res_state "statp ", const char *"name ,
.RS
.BI "const char *"domain ", int " class ", int " type ", u_char *"answer, 
.BI "int " anslen );
.RE
.sp
.BI "int res_nmkquery(res_state " statp " , int " op , 
.RS
.BI "const char *"dname ", int " class ", int " type ,
.BI "const u_char*"data ", int " datalen ", const u_char *"newrr,
.BI "u_char *"buf ", int "buflen );
.RE
.sp
.BI "int res_nsend(res_state "statp ", const u_char *"msg, 
.RS
.BI "int "msglen ", u_char *"answer ", int "anslen );
.RE
.sp
.BI "int res_nclose(res_state " statp );
.sp
.B "int dn_comp(const char "*exp_dn ", u_char *"comp_dn , 
.RS
.BI "int " length ",  u_char **"dnptrs ", u_char**"lastdnptr );
.RE
.sp
.BI "int dn_expand(const u_char *"msg ", const u_char *"eomorig, 
.RS
.BI "const u_char*" comp_dn ", char *"exp_dn ", int " length );
.RE
.sp
.BI "const char *hstrerror(int "err );
.fi
.sp
You also need to link with \-lresolv.
.SH DEPRECATED
.nf
.B #include <sys/types.h>
.B #include <netinet/in.h>
.B #include <arpa/nameser.h>
.B #include <resolv.h>
.sp
.B int res_init (void);
.sp
.BI "int res_isourserver(const struct sockaddr_in *"addr );
.sp
.BI "int fp_nquery(const u_char *"msg ", int "msglen, 
.RS
.BI "FILE *"fp );
.RE
.sp
.BI "void p_query(const u_char *"msg ", FILE *"fp );
.sp
.BI "const char *hostalias(const char *"name );
.sp
.BI "int res_query(const char "*dname ", int "class ", int " type, 
.RS
.BI "u_char *"answer ", int" anslen );
.RE
.sp
.BI "int res_search(const char *"dname ", int "class ", int " type, 
.RS
.BI "u_char *"answer ", int "anslen );
.RE
.sp
.BI "int res_querydomain(const char *"name ", const char *"domain, 
.RS
.BI "int "class ", int "type ", u_char *"answer ", int "anslen );
.RE
.sp
.BI "int res_mkquery(int "op", const char *"dname ", int "class, 
.RS 
.BI "int "type ", const char *"data ", int "datalen,
.BI "struct rrec *"newrr ", u_char *"buf ", int "buflen );
.RE
.sp
.BI "int res_send(const u_char *"msg ", int "msglen,
.RS
.BI "u_char *"answer ", int "anslen );
.RE
.B int res_close(void);
.sp
.BI "void herror(const char *"s );
.fi
.sp
.SH DESCRIPTION
These routines are used for making, sending and interpreting
query and reply messages with Internet domain name servers.
.PP
State information is kept in
.I statp
and is used to control the behavior of these functions.
.I statp
should be set to all zeros prior to the first call to any of these functions.
.PP
The functions
.BR res_init ,
.BR res_isourserver ,
.BR fp_nquery ,
.BR p_query ,
.BR hostalias ,
.BR res_query ,
.BR res_search ,
.BR res_querydomain ,
.BR res_mkquery ,
.BR res_send ,
.B res_close
and
.B herror
are deprecated and are supplied for compatibility with old source
code.
They use global configuration and state information that is
kept in the structure
.I _res
rather than that referenced through
.IR statp .
.PP
Most of the values in 
.I statp
and
.I _res
are initialized on the first call to
.B res_ninit
/
.B res_init
to reasonable defaults and can be ignored.
Options
stored in
.I statp->options
/
.I _res.options
are defined in
.I resolv.h
and are as follows.
Options are stored as a simple bit mask containing the bitwise 
\`\`OR''
of the options enabled.
.TP 
.B RES_INIT
True if the initial name server address and default domain name are
initialized (i.e.,
.B res_ninit
/
.B res_init
has been called).
.TP 
.B RES_AAONLY
Accept authoritative answers only.
should continue until it finds an authoritative answer or finds an error.
Currently this is not implemented.
.TP 
.B RES_USEVC
Use TCP connections for queries instead of UDP datagrams.
.TP 
.B RES_STAYOPEN
Used with 
.B RES_USEVC 
to keep the TCP connection open between queries.
This is useful only in programs that regularly do many queries.
UDP should be the normal mode used.
.TP 
.B RES_IGNTC
Ignore truncation errors, i.e., don't retry with TCP.
.TP 
.B RES_RECURSE
Set the recursion-desired bit in queries.
This is the default.
(\c
.B res_nsend
/
.B res_send
does not do iterative queries and expects the name server
to handle recursion.)
.TP 
.B RES_DEFNAMES
If set,
.B res_nsearch
/
.B res_search
will append the default domain name to single-component names
(those that do not contain a dot).
This option is enabled by default.
.TP 
.B RES_DNSRCH
If this option is set,
.B res_nsearch
/
.B res_search
will search for host names in the current domain and in parent domains.
This is used by the standard host lookup routine
.BR gethostbyname (3) .
This option is enabled by default.
.TP 
.B RES_NOALIASES
This option turns off the user level aliasing feature controlled by
the 
.B HOSTALIASES 
environment variable.
Network daemons should set this option.
.TP 
.B RES_USE_INET6
This option causes 
.BR gethostbyname (3)
to look for AAAA records before looking for A records if none are found.
.TP 
.B RES_ROTATE
This options causes the
.B res_nsend
/
.B res_send
to rotate the list of nameservers in
.I statp->nsaddr_list
/
.I _res.nsaddr_list
.
.PP
The
.B res_ninit
/
.B res_init
routine
reads the configuration file (if any; see
.BR resolver (5)
) to get the default domain name, search list and
the Internet address of the local name server(s).
If no server is configured, the host running the resolver is tried.
The current domain name is defined by the hostname
if not specified in the configuration file;
it can be overridden by the environment variable 
.B LOCALDOMAIN
.
This environment variable may contain several blank-separated
tokens if you wish to override the
\`\`search list''
on a per-process basis.  This is similar to the
.B search
command in the configuration file.
Another environment variable 
(
.B RES_OPTIONS
) can be set to override certain internal resolver options which are
otherwise set by changing fields in the
.I statp
/
.I _res
structure or are inherited from the configuration file's
.B options
command.  The syntax of the 
.B RES_OPTIONS 
environment variable is explained in
.BR resolver (5)
.
Initialization normally occurs on the first call
to one of the other resolver routines.
.PP
The
.B res_nquery
/
.B res_query
functions provide interfaces to the server query mechanism.
They construct a query, send it to the local server,
await a response, and make preliminary checks on the reply.
The query requests information of the specified
.I type
and
.I class
for the specified fully-qualified domain name
.I dname
.
The reply message is left in the
.I answer
buffer with length
.I anslen
supplied by the caller.
.B res_nquery
/
.B res_query
return -1 on error or the length of the answer.
.PP
The
.B res_nsearch
/
.B res_search
routines make a query and await a response like
.B res_nquery
/
.B res_query
, but in addition, they implement the default and search rules
controlled by the 
.B RES_DEFNAMES 
and 
.B RES_DNSRCH 
options.
They return the length of the first successful reply which is stored in
.I answer
or -1 on error.
.PP
The remaining routines are lower-level routines used by
.B res_nquery
/
.BR res_query .
The
.B res_nmkquery
/
.B res_mkquery
functions
construct a standard query message and place it in
.IR buf .
They return the size of the query, or \-1 if the query is
larger than
.IR buflen .
The query type
.I op
is usually
.BR QUERY ,
but can be any of the query types defined in
.IR <arpa/nameser.h>  .
The domain name for the query is given by
.IR dname .
.I Newrr
is currently unused but is intended for making update messages.
.PP
The
.B res_nsend
/
.B res_send
routines
send a pre-formatted query and return an answer.
They will call
.B res_ninit
/
.B res_init
if 
.B RES_INIT 
is not set, send the query to the local name server, and
handle timeouts and retries.  
.PP
.BR res_nquery
/
.BR res_query ,
.B res_nsearch
/
.B res_search
and
.B res_nsend
/
.B res_send
return a length that may be bigger than
.IR anslen .
In that case the query should be retried with a bigger buffer.
NOTE the answer to the second query may be larger still so supplying
a buffer that bigger that the answer returned by the previous
query is recommended.
.PP
.I answer
MUST be big enough to receive a maximum UDP response from the server or 
parts of the answer will be silently discarded.
The default maximum UDP response size is 512 bytes.
.PP
The function
.B res_ourserver_p
returns true when 
.I inp
is one of the servers in
.I statp->nsaddr_list
/
.IR _res.nsaddr_list .
.PP
The functions
.B fp_nquery
/
.B p_query
print out the query and any answer in
.I msg
on
.I fp
.
.B p_query
is equivalent to
.B fp_nquery
with
.I msglen
set to 512.
.PP
The function
.B fp_resstat
prints out the active flag bits in
.I statp->options
preceeded by the text ";; res options:" on 
.IR file .
.PP
The functions
.B res_hostalias
/
.B hostalias
lookup up name in the file referred to by the
.B HOSTALIASES files return a fully qualified hostname if found or NULL if
not found or an error occurred.
.B res_hostalias
uses
.I buf
to store the result in,
.B hostalias
uses a static buffer.
.PP
.PP
The functions
.B res_nclose
/
.B res_close
close any open files referenced through
.I statp
/
.IR _res .
.PP
The
.B dn_comp
function
compresses the domain name
.I exp_dn
and stores it in
.IR comp_dn .
The size of the compressed name is returned or \-1 if there were errors.
The size of the array pointed to by
.I comp_dn
is given by
.IR length .
The compression uses
an array of pointers
.I dnptrs
to previously-compressed names in the current message.
The first pointer points to
to the beginning of the message and the list ends with 
.BR NULL .
The limit to the array is specified by
.IR lastdnptr .
A side effect of
.B dn_comp
is to update the list of pointers for labels inserted into the message
as the name is compressed.  If
.I dnptr
is 
.B NULL 
, names are not compressed.  If
.I lastdnptr
is 
.B NULL
, the list of labels is not updated.
.PP
The
.B dn_expand
entry
expands the compressed domain name
.I comp_dn
to a full domain name.
The compressed name is contained in a query or reply message;
.I msg
is a pointer to the beginning of the message.
The uncompressed name is placed in the buffer indicated by
.I exp_dn
which is of size
.IR length .
The size of compressed name is returned or \-1 if there was an error.
.PP
The variables
.I statp->res_h_errno
/
.I _res.res_h_errno
and external variable
.I h_errno
is set whenever an error occurs during resolver operation.  The following
definitions are given in
.IR <netdb.h> :

.nf
#define NETDB_INTERNAL -1  /* see errno */
#define NETDB_SUCCESS  0   /* no problem */
#define HOST_NOT_FOUND 1   /* Authoritative Answer Host not found */
#define TRY_AGAIN      2   /* Non-Authoritative not found, or SERVFAIL */
#define NO_RECOVERY    3   /* Non-Recoverable: FORMERR, REFUSED, NOTIMP */
#define NO_DATA        4   /* Valid name, no data for requested type */
.fi
.PP
The
.B herror
function writes a message to the diagnostic output consisting of the string
parameter
.I s
, the constant string ": ", and a message corresponding to the value of
.IR h_errno .
.PP
The
.B hstrerror
function returns a string which is the message text corresponding to the
value of the
.I err
parameter.
.SH FILES
.IR /etc/resolv.conf	
See 
.BR resolver (5) .
.SH GLIBC NOTES
This manual page is taken straight from BIND 8.2.3. The parts that
apply to functionality which hasn't been merged into glibc (DDNS
update code, TSIG and dependencies) were removed. The following
functions aren't supported in glibc: \fBres_sendsigned\fP(),
\fBres_update\fP(), \fBres_mkupdate\fP(), \fBres_nupdate\fP() and
\fBres_findzonecut\fP(). This information is based on 
.I resolv/README
in the glibc distribution.
.LP 
Other differences (also taken from there): 
.PP
- The resolver in glibc strictly adheres to the recommendations in RFC
1535.  BIND 8.2.3-T5B seems to relax those rules a bit (see the code
that's wrapped in `\fB#ifndef RFC1535\fP').

- The \fBRES_DEBUG\fP option (`options debug' in
\fI/etc/resolv.conf\fP) has been disabled.

- The resolver in glibc allows underscores in domain names.

- The \fB<resolv.h>\fP header in glibc includes \fB<netinet/in.h>\fP and
\fB<arpa/nameser.h>\fP to make it self-contained.

- The `\fBres_close\fP' function in glibc only tries to close open
files referenced through `\fI_res\fP' if the \fBRES_INIT\fP bit is set
in \fI_res.options\fP'.  This fixes a potential security bug with programs
that bogusly call `\fBres_close\fP' without initialising the resolver state
first.  Note that the thread-safe `\fBres_nclose\fP' still doesn't check the
\fBRES_INIT\fP bit.  By the way, you're not really supposed to call
`\fBres_close\fP/\fBres_nclose\fP' directly.

- The resolver in glibc can connect to a nameserver over IPv6.  Just
specify the IPv6 address in \fI/etc/resolv.conf\fP.  You cannot change the
address of an IPv6 nameserver dynamically in your program though.
.SH SEE ALSO
.BR gethostbyname (3) , 
.BR resolver (5) ;
RFC1032, RFC1033, RFC1034, RFC1035, RFC974;
SMM:11, 
\`\`Name Server Operations Guide for Sy BIND''