|
» |
|
|
|
NAMEresolver: dn_comp(), dn_expand(), get_resfield(), herror(), res_init(), res_mkquery(), res_query(), res_search(), res_send(), set_resfield() — resolver routines SYNOPSIS#include <sys/types.h>
#include <netinet/in.h>
#include <arpa/nameser.h>
#include <resolv.h>
ssize_t res_query(
char *dname,
int class,
int type,
u_char *answer,
int anslen
);
ssize_t res_search(
char *dname,
int class,
int type,
u_char *answer,
int anslen
);
ssize_t res_mkquery(
int op,
const char *dname,
int class,
int type,
const char *data,
int datalen,
const char *newrr,
char *buf,
int buflen
);
ssize_t res_send(
const char *msg,
ssize_t msglen,
char *answer,
int anslen
);
int res_init();
ssize_t dn_comp(
const char *exp_dn,
u_char *comp_dn,
ssize_t length,
u_char **dnptrs,
u_char **lastdnptr
);
ssize_t dn_expand(
const u_char *msg,
const u_char *eomorig,
const u_char *comp_dn,
u_char *exp_dn,
int length
);
int set_resfield(
int field,
void *value
);
int get_resfield(
int field,
void *value,
sizeof value
); OBSOLESCENT INTERFACEvoid herror(const char *s); DESCRIPTIONThese routines are used for making, sending, and interpreting
query and reply messages with Internet domain name servers. Global configuration and state information
used by the resolver routines are kept in the structure
_res
and are defined in
<resolv.h>.
Most of the fields have reasonable defaults and can be ignored.
The resolver options are stored in the
_res.options
field and are listed below. The options are stored as a simple bit mask
containing the bitwise OR of the options enabled. In a multithreaded environment, a thread specific
_res
structure is allocated for each thread.
- RES_INIT
True if the initial name server address and default domain name are
initialized (i.e.,
res_init()
has been called). - RES_DEBUG
Print debugging messages. - RES_AAONLY
Accept authoritative answers only.
With this option,
res_send()
should continue
until it finds an authoritative answer or finds an error.
Currently this is not implemented. - RES_PRIMARY
Query the primary server only.
Currently this is not implemented. - RES_USEVC
Use
TCP
connections for queries instead of
UDP
datagrams. - RES_STAYOPEN
Used with
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. - RES_IGNTC
The name server will set the truncation bit
if all of the data does not fit into the response datagram packet.
If
RES_IGNTC
is set,
res_send()
will not retry the query with
TCP
(i.e., ignore truncation errors). - RES_RECURSE
Set the recursion-desired bit in queries.
This is the default.
(res_send()
does not do iterative queries
and expects the name server to handle recursion.) - RES_DEFNAMES
If set,
res_search()
appends the default domain name to single-component names
(those that do not contain a dot).
This option is enabled by default. - RES_DNSRCH
If this option is set,
res_search()
searches for host names in the current domain
and in parent domains; see
hostname(5).
This is used by the standard host lookup routine
gethostbyname()
(see
gethostent(3N)).
This option is enabled by default.
Initialization of the resolver structure normally occurs on the first call
to one of the resolver routines below. If there are errors in the
configuration file, they are silently ignored. The values for retransmission timeout and number of retries to be attempted
can be configured. These correspond to the
retrans
and
retry
fields in
the
_res
structure. The following three options, listed in the order
of precedence, have been provided for configuring the retransmission
timeout and retry values. - 1.
Environment Variables, - 2.
Configuration file
/etc/resolv.conf, - 3.
Through calls to API
set_resfield().
retrans
and
retry
can be configured through the
Environmental Variables
RES_RETRANS
and
RES_RETRY
as follows: RES_RETRANS=values in milliseconds
RES_RETRY=number of retries Alternatively in
resolv.conf
the following name-value pairs can be added : retrans value in milliseconds
retry number of retries While the Environmental Variables and entries in the
resolv.conf
file are interpreted when the
res_init()
API is called, the API
set_resfield()
has to be explicitly called from within the code.
Setting the
retrans
and
retry
values through a lower precedence option will
be ignored if these values have been configured through higher precedence
option. A message is flagged in
syslog
when an invalid value is specified in
either
resolv.conf
or Environmental variables. The
retrans
is to be
specified in milliseconds, and its
default value is 5000 milliseconds. The default value for
retry
is 4. Primary Routines- res_init()
Reads the configuration file,
/etc/resolv.conf,
to get the default domain name, search list,
the Internet address of the local name server(s), the values for
retrans
and
retry.
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
LOCALDOMAIN.
This environment variable may contain several blank
separated tokens and overrides the search list
on a per process basis. This is similar to the
search
command in the configuration file. Another environment variable
such as,
RES_OPTIONS
can be set to override certain internal resolver options which are
set by calling some of the configuration routines above, or by using
the configuration file's
options
command. The syntax of the
RES_OPTIONS
environment variable is explained in
resolver(4).
The
resolv.conf
entries for
retrans
and
retry
can be overridden by
RES_RETRANS
and
RES_RETRY
Environmental Variables respectively. - res_query()
Provides an interface to the server query mechanism.
It constructs a query, sends it to the local server,
awaits a response, and makes preliminary checks on the reply.
The query requests information of the specified
type
and
class
for the specified fully-qualified domain name
dname.
The reply message is left in the
answer
buffer with length
anslen
supplied by the caller. - res_search()
Makes a query and awaits a response much like
res_query(),
but in addition, it implements the default
and search rules controlled by the
RES_DEFNAMES
and
RES_DNSRCH
options.
It returns the first successful reply. - set_resfield()
Sets the value for the
retry
and
retrans
fields in the
_res
structure. The value for the
retrans
option must be specified in milliseconds.
This routine also validates the values which the user tries to set for the
retry
and
retrans
options.
set_resfield()
returns
0
on success, and
-1
on failure. Calls to
set_resfield()
fails when values for the field passed as argument is already set by any
higher precedence option like entering name-value pairs in the
resolv.conf
file or setting the Environmental Variables
RES_RETRANS
and
RES_RETRY. - get_resfield()
Get the value for the
retry
and
retrans
fields in the
_res
structure.
get_resfield()
returns the value of the field requested on success
and
-1
if on failure. It fails when the arguments do not refer to
retrans
or
retry.
Other RoutinesRoutines described here are lower-level routines used by
res_query().
- res_mkquery()
Constructs a standard query message and places it in
buf.
It returns the size of the query, or -1 if the query is larger than
buflen.
The query type
op
is usually
QUERY,
but can be any of the query types defined in
<arpa/nameser.h>.
The domain name for the query is given by
dname.
class
can be any of the query classes defined in
<arpa/nameser.h>.
type
can be any of the query types defined in
<arpa/nameser.h>.
data
is the data for an inverse query
(IQUERY).
newrr
is currently unused but is intended for making update messages. - res_send()
Sends a pre-formatted query and returns an answer.
It calls
res_init()
if
RES_INIT
is not set, sends the query to the local name server,
and handles timeouts and retries.
res_send()
returns the length of the reply message, or -1 if there were errors. - dn_comp()
Compresses the domain name
exp_dn
and stores it in
comp_dn.
The size of the compressed name is returned or -1 if there were errors.
length
is the size of the array pointed to by
comp_dn.
The compression uses an array of pointers
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
NULL.
The limit to the array is specified by
lastdnptr.
A side effect of
dn_comp()
is to update the list of pointers for labels
inserted into the message as the name is compressed.
If
dnptr
is
NULL,
names are not compressed.
If
lastdnptr
is
NULL,
the list of labels is not updated. - dn_expand()
Expands the compressed domain name
comp_dn
to a full domain name.
The compressed name is contained in a query or reply message;
msg
is a pointer to the beginning of the message.
The uncompressed name is placed in the buffer indicated by
exp_dn
which is of size
length.
The size of compressed name is returned or -1 if there was an error.
Obsolescent Routine- herror()
herror()
supports existing applications to print an error message describing
a failure.
ANSI applications must specify the following definition for
herror(): void herror(const char *); The argument string
s
is printed first, followed by a colon, a blank, the message, and a new-line.
herror()
may be removed in future releases.
RETURN VALUEError return status from
res_search()
is indicated by a return value of -1.
The external integer
h_errno
can then be checked to see whether this is a temporary failure
or an invalid or unknown host. In a multithreaded application using kernel thread, a thread specific
h_errno
is allocated for each thread. ERRORSh_errno
can have the following values:
- HOST_NOT_FOUND
No such host is known. - TRY_AGAIN
This is usually a temporary error and means that the local server
did not receive a response from an authoritative server.
A retry at some later time may succeed. - NO_RECOVERY
Some unexpected server failure was encountered.
This is a non-recoverable error. - NO_DATA
The name is known to the name server,
but there is no data of the requested type associated with this name;
this is not a temporary error.
Another type of request to the name server using this domain name
will result in an answer.
WARNINGSThe
_res.options
field should be modified only by using
set_resfield()
call, and should not be manipulated directly.
h_errno
is referenced as an
extern int
for non-threaded applications and is defined as function call macro
for multithreaded applications in file
/usr/include/netdb.h.
Applications which reference
h_errno
should include
/usr/include/netdb.h. _res
is referenced as an
extern struct _res_state
for non-threaded applications and is defined as function call macro
for multithreaded application in file
/usr/include/resolv.h.
Applications which reference
_res
should include
/usr/include/resolv.h. AUTHORThese resolver routines were developed
by the University of California, Berkeley. FILES- /etc/resolv.conf
Resolver configuration file.
|