NAME
res_ninit,
res_ourserver_p,
fp_resstat,
res_hostalias,
res_pquery,
res_nquery,
res_nsearch,
res_nquerydomain,
res_nmkquery,
res_nsend,
res_nupdate,
res_nmkupdate,
res_nclose,
res_nsendsigned,
res_findzonecut,
res_getservers,
res_setservers,
res_ndestroy,
dn_comp,
dn_expand,
res_init,
res_isourserver,
fp_nquery,
p_query,
hostalias,
res_query,
res_search,
res_querydomain,
res_mkquery,
res_send,
res_update,
res_close, —
resolver routines
LIBRARY
Standard C Library (libc, -lc)
DNS Resolver Library (libresolv, -lresolv)
SYNOPSIS
#include <resolv.h>
#include <res_update.h>
typedef struct __res_state *res_state;
int
res_ninit(
res_state
statp);
int
res_ourserver_p(
const
res_state statp,
const
struct sockaddr_in *addr);
void
fp_resstat(
const
res_state statp,
FILE
*fp);
const char *
res_hostalias(
const
res_state statp,
const char
*name,
char *buf,
size_t buflen);
int
res_pquery(
const
res_state statp,
const
u_char *msg,
int
msglen,
FILE *fp);
int
res_nquery(
res_state
statp,
const char
*dname,
int class,
int type,
u_char *answer,
int anslen);
int
res_nsearch(
res_state
statp,
const char
*dname,
int class,
int type,
u_char * answer,
int anslen);
int
res_nquerydomain(
res_state
statp,
const char
*name,
const char
*domain,
int class,
int type,
u_char *answer,
int anslen);
int
res_nmkquery(
res_state statp,
int op,
const char *dname,
int class,
int type,
const u_char *data,
int datalen,
const u_char *newrr,
u_char *buf,
int buflen);
int
res_nsend(
res_state
statp,
const u_char
*msg,
int msglen,
u_char *answer,
int anslen);
int
res_nupdate(
res_state
statp,
ns_updrec
*rrecp_in);
int
res_nmkupdate(
res_state
statp,
ns_updrec
*rrecp_in,
u_char
*buf,
int buflen);
void
res_nclose(
res_state
statp);
int
res_nsendsigned(
res_state
statp,
const u_char
*msg,
int msglen,
ns_tsig_key *key,
u_char *answer,
int anslen);
int
res_findzonecut(
res_state
statp,
const char
*dname,
ns_class
class,
int options,
char *zname,
size_t zsize,
struct in_addr *addrs,
int naddrs);
int
res_getservers(
res_state
statp,
union
res_sockaddr_union *set,
int cnt);
void
res_setservers(
res_state
statp,
const union
res_sockaddr_union *set,
int cnt);
void
res_ndestroy(
res_state
statp);
int
dn_comp(
const
char *exp_dn,
u_char
*comp_dn,
int length,
u_char **dnptrs,
u_char **lastdnptr);
int
dn_expand(
const
u_char *msg,
const u_char
*eomorig,
const u_char
*comp_dn,
char
*exp_dn,
int length);
DEPRECATED
#include <sys/types.h>
#include <netinet/in.h>
#include <arpa/nameser.h>
#include <resolv.h>
#include <res_update.h>
int
res_init(
void);
int
res_isourserver(
const
struct sockaddr_in *addr);
int
fp_nquery(
const
u_char *msg,
int
msglen,
FILE *fp);
void
p_query(
const
u_char *msg,
FILE
*fp);
const char *
hostalias(
const
char *name);
int
res_query(
const
char *dname,
int
class,
int type,
u_char *answer,
int anslen);
int
res_search(
const
char *dname,
int
class,
int type,
u_char *answer,
int anslen);
int
res_querydomain(
const
char *name,
const char
*domain,
int class,
int type,
u_char *answer,
int anslen);
int
res_mkquery(
int op,
const char *dname,
int class,
int type,
const char *data,
int datalen,
struct rrec *newrr,
u_char *buf,
int buflen);
int
res_send(
const
u_char *msg,
int
msglen,
u_char
*answer,
int anslen);
int
res_update(
ns_updrec
*rrecp_in);
void
res_close(
void);
DESCRIPTION
These routines are used for making, sending and interpreting query and reply
messages with Internet domain name servers.
State information is kept in
statp and is used to control
the behavior of these functions.
statp should be set to
all zeros prior to the first call to any of these functions.
The functions
res_init(),
res_isourserver(),
fp_nquery(),
p_query(),
hostalias(),
res_query(),
res_search(),
res_querydomain(),
res_mkquery(),
res_send(),
res_update(),
res_close() are deprecated
and are supplied for compatability with old source code. They use global
configuration and state information that is kept in the structure
_res rather than that referenced through
statp.
Most of the values in
statp and
_res
are initialized on the first call to
res_ninit() /
res_init() to reasonable defaults and can be ignored.
Options stored in
statp->options /
_res.options are defined in
resolv.h
and are as follows. Options are stored as a simple bit mask containing the
bitwise “OR” of the options enabled.
-
-
RES_INIT
- True if the initial name server address and default domain
name are initialized (i.e., res_ninit() /
res_init() has been called).
-
-
RES_DEBUG
- Print debugging messages.
-
-
RES_AAONLY
- Accept authoritative answers only. Should continue until it
finds an authoritative answer or finds an error. 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
- Ignore truncation errors, i.e., don't retry with TCP.
-
-
RES_RECURSE
- Set the recursion-desired bit in queries. This is the
default. (res_nsend() / res_send()
does not do iterative queries and expects the name server to handle
recursion.)
-
-
RES_DEFNAMES
- If set, res_nsearch() /
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.
-
-
RES_DNSRCH
- If this option is set, res_nsearch() /
res_search() will search for host names in the current
domain and in parent domains; see
hostname(7). This is used
by the standard host lookup routine
gethostbyname(3).
This option is enabled by default.
-
-
RES_USE_INET6
- Enables support for IPv6-only applications. 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. The option is meaningful
with certain kernel configuration only.
-
-
RES_USE_EDNS0
- Enables support for OPT pseudo-RR for EDNS0 extension. With
the option, resolver code will attach OPT pseudo-RR into DNS queries, to
inform of our receive buffer size. The option will allow DNS servers to
take advantage of non-default receive buffer size, and to send larger
replies. DNS query packets with EDNS0 extension is not compatible with
non-EDNS0 DNS servers.
-
-
RES_NOALIASES
- This option turns off the user level aliasing feature
controlled by the
HOSTALIASES
environment
variable. Network daemons should set this option.
-
-
RES_ROTATE
- This options causes res_nsend() /
res_send() to rotate the list of nameservers in
statp->nsaddr_list /
_res.nsaddr_list.
-
-
RES_KEEPTSIG
- This option causes res_nsendsigned() to
leave the message unchanged after TSIG verification; otherwise the TSIG
record would be removed and the header updated.
-
-
RES_NOTLDQUERY
- This option causes res_nsearch() to not
attempt to resolve an unqualified name as if it were a top level domain
(TLD). This option can cause problems if the site has
"localhost" as a TLD rather than having localhost on one or more
elements of the search list. This option has no effect if neither
RES_DEFNAMES
or RES_DNSRCH
are set.
The
res_ninit() /
res_init() routines read
the configuration file (if any; see
resolv.conf(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
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
search command in the configuration file. Another
environment variable
RES_OPTIONS
can be set to
override certain internal resolver options which are otherwise set by changing
fields in the
statp /
_res
structure or are inherited from the configuration file's
options command. The syntax of the
RES_OPTIONS
environment variable is explained in
resolv.conf(5).
Initialization normally occurs on the first call to one of the other resolver
routines.
In
NetBSD the initialization code also sets up a
kqueue(2) and creates a
kevent(2) watching a file
descriptor that points to the resolver file. Every resolver function calls the
internal function
__res_check() which checks for a new
kevent(2) related to the
resolv.conf(5) file, and
reloads the file if necessary. This does not work if the file is accessed
through a symlink and the symlink changes to point to a different file. To fix
the symlink issue one could add a system call per resolver call to get the
current time, and reload every so often. This is not done currently, but it is
under consideration.
The memory referred to by
statp must be set to all zeros
prior to the first call to
res_ninit().
res_ndestroy() should be called to free memory allocated by
res_ninit() after last use.
The
res_nquery() /
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
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_nquery() /
res_query() return -1 on
error or the length of the answer.
The
res_nsearch() /
res_search() routines
make a query and awaits a response like
res_nquery() /
res_query(), but in addition, they implement the default and
search rules controlled by the
RES_DEFNAMES
and
RES_DNSRCH
options. They return the length of the
first successful reply which is stored in
answer or -1
on error.
The remaining routines are lower-level routines used by
res_nquery() /
res_query(). The
res_nmkquery() /
res_mkquery() functions
construct a standard query message and place it in
buf.
They return 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.
newrr is currently unused but is intended for making
update messages.
The
res_nsend() /
res_send() /
res_nsendsigned() routines send a pre-formatted query and
return an answer. They will call
res_ninit() /
res_init() if
RES_INIT
is not set,
send the query to the local name server, and handle timeouts and retries.
Additionally,
res_nsendsigned() will use TSIG signatures to
add authentication to the query and verify the response. In this case, only
one nameserver will be contacted. The length of the reply message is returned,
or -1 if there were errors.
res_nquery() /
res_query(),
res_nsearch() /
res_search() and
res_nsend() /
res_send() return a length
that may be bigger than
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.
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.
The function
res_ourserver_p() returns true when
inp is one of the servers in
statp->nsaddr_list /
_res.nsaddr_list.
The functions
fp_nquery() /
p_query() print
out the query and any answer in
msg on
fp.
p_query() is equivalent to
fp_nquery() with
msglen set to 512.
The function
fp_resstat() prints out the active flag bits in
statp->options preceeded by the text ";; res
options:" on
file.
The functions
res_hostalias() /
hostalias()
look up name in the file referred to by the
HOSTALIASES
files and return a fully qualified
hostname if found or
NULL
if not found or an error
occurred.
res_hostalias() uses
buf to
store the result in,
hostalias() uses a static buffer.
The functions
res_getservers() and
res_setservers() are used to get and set the list of server
to be queried.
The functions
res_nupdate() /
res_update()
take a list of ns_updrec
rrecp_in. They identify the
containing zone for each record and group the records according to containing
zone maintaining in zone order then send an update request to the servers for
these zones. The number of zones updated is returned or -1 on error. Note that
res_nupdate() will perform TSIG authenticated dynamic update
operations if the key is not
NULL
.
The function
res_findzonecut() discovers the closest enclosing
zone cut for a specified domain name, and finds the IP addresses of the zone's
master servers.
The functions
res_nmkupdate() /
res_mkupdate() take a linked list of ns_updrec
rrecp_in and construct an UPDATE message in
buf.
res_nmkupdate() /
res_mkupdate() return the length of the constructed message
on no error or one of the following error values.
- -1
- An error occurred parsing
rrecp_in.
- -2
- The buffer
buf was too small.
- -3
- The first record was not a
zone section or there was a section order problem. The section order is
S_ZONE, S_PREREQ and S_UPDATE.
- -4
- A number overflow
occurred.
- -5
- Unknown operation or no
records.
The functions
res_nclose() /
res_close()
close any open socket file descriptors referenced through
statp /
_res. These functions were
designed to be used to emulate
endhostent(3), and don't
release other resources held in
res_state; to free
all_resources, call
res_ndestroy().
The function
res_ndestroy() calls
res_nclose() then frees any memory allocated by
res_ninit().
The
dn_comp() function 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. The
size of the array pointed to by
comp_dn is given by
length. The compression uses an array of pointers
dnptrs to previously-compressed names in the current
message. The first pointer points 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.
The
dn_expand() entry 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.
eomorig is a pointer to
the first location after 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.
The variables
statp->res_h_errno /
_res.res_h_errno and external variable
h_errno are set whenever an error occurs during resolver
operation. The following definitions are given in
⟨
netdb.h⟩:
#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 */
The following functions are only in
libresolv
:
res_findzonecut(),
res_nmkupdate(),
res_nsendsigned(), and
res_nupdate(). All
the rest are in both
libc
and
libresolv
.
FILES
-
-
- /etc/resolv.conf
- The configuration file, see
resolv.conf(5).
SEE ALSO
getaddrinfo(3),
gethostbyaddr(3),
gethostbyname(3),
getnameinfo(3),
resolv.conf(5),
hostname(7),
named(8)
RFC 974, RFC 1032,
RFC 1033, RFC 1034,
RFC 1035, RFC 1535
Name Server Operations Guide for
BIND.
HISTORY
The
res_ninit function appeared in
4.3BSD.