RESOLVER(3) | Library Functions Manual | RESOLVER(3) |
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
—
#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);
#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);
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 compatibility 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
res_ninit
() /
res_init
() has been called).RES_DEBUG
RES_AAONLY
RES_USEVC
RES_STAYOPEN
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
RES_RECURSE
res_nsend
() / res_send
()
does not do iterative queries and expects the name server to handle
recursion.)RES_DEFNAMES
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
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
RES_USE_EDNS0
RES_NOALIASES
HOSTALIASES
environment variable. Network daemons
should set this option.RES_ROTATE
res_nsend
() /
res_send
() to rotate the list of nameservers in
statp->nsaddr_list /
_res.nsaddr_list.RES_KEEPTSIG
res_nsendsigned
() to leave the
message unchanged after TSIG verification; otherwise the TSIG record would
be removed and the header updated.RES_NOTLDQUERY
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 preceded 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.
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
.
RFC 974, RFC 1032, RFC 1033, RFC 1034, RFC 1035, RFC 1535
Name Server Operations Guide for BIND.
res_ninit
function appeared in
4.3BSD.
February 7, 2018 | NetBSD 9.0 |