.\" $OpenBSD: resolver.3,v 1.15 2001/04/03 20:09:08 aaron Exp $
|
.\" $OpenBSD: resolver.3,v 1.15 2001/04/03 20:09:08 aaron Exp $
|
.\"
|
.\"
|
.\" Copyright (c) 1985, 1991, 1993
|
.\" Copyright (c) 1985, 1991, 1993
|
.\" The Regents of the University of California. All rights reserved.
|
.\" The Regents of the University of California. All rights reserved.
|
.\"
|
.\"
|
.\" Redistribution and use in source and binary forms, with or without
|
.\" Redistribution and use in source and binary forms, with or without
|
.\" modification, are permitted provided that the following conditions
|
.\" modification, are permitted provided that the following conditions
|
.\" are met:
|
.\" are met:
|
.\" 1. Redistributions of source code must retain the above copyright
|
.\" 1. Redistributions of source code must retain the above copyright
|
.\" notice, this list of conditions and the following disclaimer.
|
.\" notice, this list of conditions and the following disclaimer.
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
.\" notice, this list of conditions and the following disclaimer in the
|
.\" notice, this list of conditions and the following disclaimer in the
|
.\" documentation and/or other materials provided with the distribution.
|
.\" documentation and/or other materials provided with the distribution.
|
.\" 3. All advertising materials mentioning features or use of this software
|
.\" 3. All advertising materials mentioning features or use of this software
|
.\" must display the following acknowledgement:
|
.\" must display the following acknowledgement:
|
.\" This product includes software developed by the University of
|
.\" This product includes software developed by the University of
|
.\" California, Berkeley and its contributors.
|
.\" California, Berkeley and its contributors.
|
.\" 4. Neither the name of the University nor the names of its contributors
|
.\" 4. Neither the name of the University nor the names of its contributors
|
.\" may be used to endorse or promote products derived from this software
|
.\" may be used to endorse or promote products derived from this software
|
.\" without specific prior written permission.
|
.\" without specific prior written permission.
|
.\"
|
.\"
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
.\" SUCH DAMAGE.
|
.\" SUCH DAMAGE.
|
.\"
|
.\"
|
.Dd June 4, 1993
|
.Dd June 4, 1993
|
.Dt RESOLVER 3
|
.Dt RESOLVER 3
|
.Os
|
.Os
|
.Sh NAME
|
.Sh NAME
|
.Nm res_query ,
|
.Nm res_query ,
|
.Nm res_search ,
|
.Nm res_search ,
|
.Nm res_mkquery ,
|
.Nm res_mkquery ,
|
.Nm res_send ,
|
.Nm res_send ,
|
.Nm res_init ,
|
.Nm res_init ,
|
.Nm dn_comp ,
|
.Nm dn_comp ,
|
.Nm dn_expand
|
.Nm dn_expand
|
.Nd resolver routines
|
.Nd resolver routines
|
.Sh SYNOPSIS
|
.Sh SYNOPSIS
|
.Fd #include
|
.Fd #include
|
.Fd #include
|
.Fd #include
|
.Fd #include
|
.Fd #include
|
.Fd #include
|
.Fd #include
|
.Ft int
|
.Ft int
|
.Fo res_query
|
.Fo res_query
|
.Fa "char *dname"
|
.Fa "char *dname"
|
.Fa "int class"
|
.Fa "int class"
|
.Fa "int type"
|
.Fa "int type"
|
.Fa "u_char *answer"
|
.Fa "u_char *answer"
|
.Fa "int anslen"
|
.Fa "int anslen"
|
.Fc
|
.Fc
|
.Ft int
|
.Ft int
|
.Fo res_search
|
.Fo res_search
|
.Fa "char *dname"
|
.Fa "char *dname"
|
.Fa "int class"
|
.Fa "int class"
|
.Fa "int type"
|
.Fa "int type"
|
.Fa "u_char *answer"
|
.Fa "u_char *answer"
|
.Fa "int anslen"
|
.Fa "int anslen"
|
.Fc
|
.Fc
|
.Ft int
|
.Ft int
|
.Fo res_mkquery
|
.Fo res_mkquery
|
.Fa "int op"
|
.Fa "int op"
|
.Fa "char *dname"
|
.Fa "char *dname"
|
.Fa "int class"
|
.Fa "int class"
|
.Fa "int type"
|
.Fa "int type"
|
.Fa "char *data"
|
.Fa "char *data"
|
.Fa "int datalen"
|
.Fa "int datalen"
|
.Fa "struct rrec *newrr"
|
.Fa "struct rrec *newrr"
|
.Fa "char *buf"
|
.Fa "char *buf"
|
.Fa "int buflen"
|
.Fa "int buflen"
|
.Fc
|
.Fc
|
.Ft int
|
.Ft int
|
.Fo res_send
|
.Fo res_send
|
.Fa "char *msg"
|
.Fa "char *msg"
|
.Fa "int msglen"
|
.Fa "int msglen"
|
.Fa "char *answer"
|
.Fa "char *answer"
|
.Fa "int anslen"
|
.Fa "int anslen"
|
.Fc
|
.Fc
|
.Ft int
|
.Ft int
|
.Fn res_init "void"
|
.Fn res_init "void"
|
.Ft int
|
.Ft int
|
.Fo dn_comp
|
.Fo dn_comp
|
.Fa "char *exp_dn"
|
.Fa "char *exp_dn"
|
.Fa "char *comp_dn"
|
.Fa "char *comp_dn"
|
.Fa "int length"
|
.Fa "int length"
|
.Fa "char **dnptrs"
|
.Fa "char **dnptrs"
|
.Fa "char **lastdnptr"
|
.Fa "char **lastdnptr"
|
.Fc
|
.Fc
|
.Ft int
|
.Ft int
|
.Fo dn_expand
|
.Fo dn_expand
|
.Fa "u_char *msg"
|
.Fa "u_char *msg"
|
.Fa "u_char *eomorig"
|
.Fa "u_char *eomorig"
|
.Fa "u_char *comp_dn"
|
.Fa "u_char *comp_dn"
|
.Fa "u_char *exp_dn"
|
.Fa "u_char *exp_dn"
|
.Fa "int length"
|
.Fa "int length"
|
.Fc
|
.Fc
|
.Sh DESCRIPTION
|
.Sh DESCRIPTION
|
These routines are used for making, sending, and interpreting
|
These routines are used for making, sending, and interpreting
|
query and reply messages with Internet domain name servers.
|
query and reply messages with Internet domain name servers.
|
.Pp
|
.Pp
|
Global configuration and state information that is used by the
|
Global configuration and state information that is used by the
|
resolver routines is kept in the structure
|
resolver routines is kept in the structure
|
.Li _res .
|
.Li _res .
|
Most of the values have reasonable defaults and can be ignored.
|
Most of the values have reasonable defaults and can be ignored.
|
Options stored in
|
Options stored in
|
.Li _res.options
|
.Li _res.options
|
are defined in
|
are defined in
|
.Aq Pa resolv.h
|
.Aq Pa resolv.h
|
and are as follows.
|
and are as follows.
|
Options are stored as a simple bit mask containing the bitwise
|
Options are stored as a simple bit mask containing the bitwise
|
.Tn OR
|
.Tn OR
|
of the options enabled.
|
of the options enabled.
|
.Bl -tag -width RES_USE_INET6
|
.Bl -tag -width RES_USE_INET6
|
.It Dv RES_INIT
|
.It Dv RES_INIT
|
True if the initial name server address and default domain name are
|
True if the initial name server address and default domain name are
|
initialized (i.e.,
|
initialized (i.e.,
|
.Fn res_init
|
.Fn res_init
|
has been called).
|
has been called).
|
.It Dv RES_DEBUG
|
.It Dv RES_DEBUG
|
Print debugging messages.
|
Print debugging messages.
|
.It Dv RES_AAONLY
|
.It Dv RES_AAONLY
|
Accept authoritative answers only.
|
Accept authoritative answers only.
|
With this option,
|
With this option,
|
.Fn res_send
|
.Fn res_send
|
should continue until it finds an authoritative answer or finds an error.
|
should continue until it finds an authoritative answer or finds an error.
|
Currently this is not implemented.
|
Currently this is not implemented.
|
.It Dv RES_USEVC
|
.It Dv RES_USEVC
|
Use
|
Use
|
.Tn TCP
|
.Tn TCP
|
connections for queries instead of
|
connections for queries instead of
|
.Tn UDP
|
.Tn UDP
|
datagrams.
|
datagrams.
|
.It Dv RES_STAYOPEN
|
.It Dv RES_STAYOPEN
|
Used with
|
Used with
|
.Dv RES_USEVC
|
.Dv RES_USEVC
|
to keep the
|
to keep the
|
.Tn TCP
|
.Tn TCP
|
connection open between queries.
|
connection open between queries.
|
This is useful only in programs that regularly do many queries.
|
This is useful only in programs that regularly do many queries.
|
.Tn UDP
|
.Tn UDP
|
should be the normal mode used.
|
should be the normal mode used.
|
.It Dv RES_IGNTC
|
.It Dv RES_IGNTC
|
Unused currently (ignore truncation errors, i.e., don't retry with
|
Unused currently (ignore truncation errors, i.e., don't retry with
|
.Tn TCP ) .
|
.Tn TCP ) .
|
.It Dv RES_RECURSE
|
.It Dv RES_RECURSE
|
Set the recursion-desired bit in queries.
|
Set the recursion-desired bit in queries.
|
This is the default.
|
This is the default.
|
.Pf ( Fn res_send
|
.Pf ( Fn res_send
|
does not do iterative queries and expects the name server
|
does not do iterative queries and expects the name server
|
to handle recursion.)
|
to handle recursion.)
|
.It Dv RES_DEFNAMES
|
.It Dv RES_DEFNAMES
|
If set,
|
If set,
|
.Fn res_search
|
.Fn res_search
|
will append the default domain name to single-component names
|
will append the default domain name to single-component names
|
(those that do not contain a dot).
|
(those that do not contain a dot).
|
This option is enabled by default.
|
This option is enabled by default.
|
.It Dv RES_DNSRCH
|
.It Dv RES_DNSRCH
|
If this option is set,
|
If this option is set,
|
.Fn res_search
|
.Fn res_search
|
will search for host names in the current domain and in parent domains; see
|
will search for host names in the current domain and in parent domains; see
|
.Xr hostname 7 .
|
.Xr hostname 7 .
|
This is used by the standard host lookup routine
|
This is used by the standard host lookup routine
|
.Xr gethostbyname 3 .
|
.Xr gethostbyname 3 .
|
This option is enabled by default.
|
This option is enabled by default.
|
.It Dv RES_USE_INET6
|
.It Dv RES_USE_INET6
|
Enables support for IPv6-only applications.
|
Enables support for IPv6-only applications.
|
This causes IPv4 addresses to be returned as an IPv4 mapped address.
|
This causes IPv4 addresses to be returned as an IPv4 mapped address.
|
For example, 10.1.1.1 will be returned as ::ffff:10.1.1.1.
|
For example, 10.1.1.1 will be returned as ::ffff:10.1.1.1.
|
The option is not meaningful on
|
The option is not meaningful on
|
.Ox .
|
.Ox .
|
.El
|
.El
|
.Pp
|
.Pp
|
The
|
The
|
.Fn res_init
|
.Fn res_init
|
routine reads the configuration file (if any; see
|
routine reads the configuration file (if any; see
|
.Xr resolv.conf 5 )
|
.Xr resolv.conf 5 )
|
to get the default domain name, search list, and the Internet address
|
to get the default domain name, search list, and the Internet address
|
of the local name server(s).
|
of the local name server(s).
|
If no server is configured, the host running
|
If no server is configured, the host running
|
the resolver is tried.
|
the resolver is tried.
|
The current domain name is defined by the hostname
|
The current domain name is defined by the hostname
|
if not specified in the configuration file;
|
if not specified in the configuration file;
|
it can be overridden by the environment variable
|
it can be overridden by the environment variable
|
.Ev LOCALDOMAIN .
|
.Ev LOCALDOMAIN .
|
This environment variable may contain several blank-separated
|
This environment variable may contain several blank-separated
|
tokens if you wish to override the
|
tokens if you wish to override the
|
.Fa search list
|
.Fa search list
|
on a per-process basis.
|
on a per-process basis.
|
This is similar to the
|
This is similar to the
|
.Fa search
|
.Fa search
|
command in the configuration file.
|
command in the configuration file.
|
Another environment variable
|
Another environment variable
|
.Ev RES_OPTIONS
|
.Ev RES_OPTIONS
|
can be set to override certain internal resolver options which
|
can be set to override certain internal resolver options which
|
are otherwise set by changing fields in the
|
are otherwise set by changing fields in the
|
.Fa _res
|
.Fa _res
|
structure or are inherited from the configuration file's
|
structure or are inherited from the configuration file's
|
.Fa options
|
.Fa options
|
command.
|
command.
|
The syntax of the
|
The syntax of the
|
.Ev RES_OPTIONS
|
.Ev RES_OPTIONS
|
environment variable is explained in
|
environment variable is explained in
|
.Xr resolv.conf 5 .
|
.Xr resolv.conf 5 .
|
Initialization normally occurs on the first call
|
Initialization normally occurs on the first call
|
to one of the following routines.
|
to one of the following routines.
|
.Pp
|
.Pp
|
The
|
The
|
.Fn res_query
|
.Fn res_query
|
function provides an interface to the server query mechanism.
|
function provides an interface to the server query mechanism.
|
It constructs a query, sends it to the local server,
|
It constructs a query, sends it to the local server,
|
awaits a response, and makes preliminary checks on the reply.
|
awaits a response, and makes preliminary checks on the reply.
|
The query requests information of the specified
|
The query requests information of the specified
|
.Fa type
|
.Fa type
|
and
|
and
|
.Fa class
|
.Fa class
|
for the specified fully qualified domain name
|
for the specified fully qualified domain name
|
.Fa dname .
|
.Fa dname .
|
The reply message is left in the
|
The reply message is left in the
|
.Fa answer
|
.Fa answer
|
buffer with length
|
buffer with length
|
.Fa anslen
|
.Fa anslen
|
supplied by the caller.
|
supplied by the caller.
|
.Pp
|
.Pp
|
The
|
The
|
.Fn res_search
|
.Fn res_search
|
routine makes a query and awaits a response like
|
routine makes a query and awaits a response like
|
.Fn res_query ,
|
.Fn res_query ,
|
but in addition, it implements the default and search rules controlled by the
|
but in addition, it implements the default and search rules controlled by the
|
.Dv RES_DEFNAMES
|
.Dv RES_DEFNAMES
|
and
|
and
|
.Dv RES_DNSRCH
|
.Dv RES_DNSRCH
|
options.
|
options.
|
It returns the first successful reply.
|
It returns the first successful reply.
|
.Pp
|
.Pp
|
The remaining routines are lower-level routines used by
|
The remaining routines are lower-level routines used by
|
.Fn res_query .
|
.Fn res_query .
|
The
|
The
|
.Fn res_mkquery
|
.Fn res_mkquery
|
function constructs a standard query message and places it in
|
function constructs a standard query message and places it in
|
.Fa buf .
|
.Fa buf .
|
It returns the size of the query, or \-1 if the query is larger than
|
It returns the size of the query, or \-1 if the query is larger than
|
.Fa buflen .
|
.Fa buflen .
|
The query type
|
The query type
|
.Fa op
|
.Fa op
|
is usually
|
is usually
|
.Dv QUERY ,
|
.Dv QUERY ,
|
but can be any of the query types defined in
|
but can be any of the query types defined in
|
.Aq Pa arpa/nameser.h .
|
.Aq Pa arpa/nameser.h .
|
The domain name for the query is given by
|
The domain name for the query is given by
|
.Fa dname .
|
.Fa dname .
|
.Fa newrr
|
.Fa newrr
|
is currently unused but is intended for making update messages.
|
is currently unused but is intended for making update messages.
|
.Pp
|
.Pp
|
The
|
The
|
.Fn res_send
|
.Fn res_send
|
routine sends a pre-formatted query and returns an answer.
|
routine sends a pre-formatted query and returns an answer.
|
It will call
|
It will call
|
.Fn res_init
|
.Fn res_init
|
if
|
if
|
.Dv RES_INIT
|
.Dv RES_INIT
|
is not set, send the query to the local name server, and
|
is not set, send the query to the local name server, and
|
handle timeouts and retries.
|
handle timeouts and retries.
|
The length of the reply message is returned, or \-1 if there were errors.
|
The length of the reply message is returned, or \-1 if there were errors.
|
.Pp
|
.Pp
|
The
|
The
|
.Fn dn_comp
|
.Fn dn_comp
|
function compresses the domain name
|
function compresses the domain name
|
.Fa exp_dn
|
.Fa exp_dn
|
and stores it in
|
and stores it in
|
.Fa comp_dn .
|
.Fa comp_dn .
|
The size of the compressed name is returned or \-1 if there were errors.
|
The size of the compressed name is returned or \-1 if there were errors.
|
The size of the array pointed to by
|
The size of the array pointed to by
|
.Fa comp_dn
|
.Fa comp_dn
|
is given by
|
is given by
|
.Fa length .
|
.Fa length .
|
The compression uses an array of pointers
|
The compression uses an array of pointers
|
.Fa dnptrs
|
.Fa dnptrs
|
to previously compressed names in the current message.
|
to previously compressed names in the current message.
|
The first pointer points
|
The first pointer points
|
to the beginning of the message and the list ends with
|
to the beginning of the message and the list ends with
|
.Dv NULL .
|
.Dv NULL .
|
The limit to the array is specified by
|
The limit to the array is specified by
|
.Fa lastdnptr .
|
.Fa lastdnptr .
|
A side effect of
|
A side effect of
|
.Fn dn_comp
|
.Fn dn_comp
|
is to update the list of pointers for labels inserted into the message
|
is to update the list of pointers for labels inserted into the message
|
as the name is compressed.
|
as the name is compressed.
|
If
|
If
|
.Em dnptr
|
.Em dnptr
|
is
|
is
|
.Dv NULL ,
|
.Dv NULL ,
|
names are not compressed.
|
names are not compressed.
|
If
|
If
|
.Fa lastdnptr
|
.Fa lastdnptr
|
is
|
is
|
.Dv NULL ,
|
.Dv NULL ,
|
the list of labels is not updated.
|
the list of labels is not updated.
|
.Pp
|
.Pp
|
The
|
The
|
.Fn dn_expand
|
.Fn dn_expand
|
entry expands the compressed domain name
|
entry expands the compressed domain name
|
.Fa comp_dn
|
.Fa comp_dn
|
to a full domain name
|
to a full domain name
|
The compressed name is contained in a query or reply message;
|
The compressed name is contained in a query or reply message;
|
.Fa msg
|
.Fa msg
|
is a pointer to the beginning of the message.
|
is a pointer to the beginning of the message.
|
The uncompressed name is placed in the buffer indicated by
|
The uncompressed name is placed in the buffer indicated by
|
.Fa exp_dn
|
.Fa exp_dn
|
which is of size
|
which is of size
|
.Fa length .
|
.Fa length .
|
The size of compressed name is returned or \-1 if there was an error.
|
The size of compressed name is returned or \-1 if there was an error.
|
.Sh FILES
|
.Sh FILES
|
.Bl -tag -width Pa
|
.Bl -tag -width Pa
|
/etc/resolv.conf
|
/etc/resolv.conf
|
configuration file
|
configuration file
|
see
|
see
|
.Xr resolv.conf 5 .
|
.Xr resolv.conf 5 .
|
.El
|
.El
|
.Sh SEE ALSO
|
.Sh SEE ALSO
|
.Xr gethostbyname 3 ,
|
.Xr gethostbyname 3 ,
|
.Xr resolv.conf 5 ,
|
.Xr resolv.conf 5 ,
|
.Xr hostname 7 ,
|
.Xr hostname 7 ,
|
.Xr named 8
|
.Xr named 8
|
.Pp
|
.Pp
|
.%T RFC1032 ,
|
.%T RFC1032 ,
|
.%T RFC1033 ,
|
.%T RFC1033 ,
|
.%T RFC1034 ,
|
.%T RFC1034 ,
|
.%T RFC1035 ,
|
.%T RFC1035 ,
|
.%T RFC1535 ,
|
.%T RFC1535 ,
|
.%T RFC974
|
.%T RFC974
|
.Rs
|
.Rs
|
.%T "Name Server Operations Guide for BIND"
|
.%T "Name Server Operations Guide for BIND"
|
.Re
|
.Re
|
.Sh HISTORY
|
.Sh HISTORY
|
The
|
The
|
.Nm
|
.Nm
|
function appeared in
|
function appeared in
|
.Bx 4.3 .
|
.Bx 4.3 .
|
|
|
