| 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_INITres_ninit() /
      res_init() has been called).RES_DEBUGRES_AAONLYRES_USEVCRES_STAYOPENRES_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_IGNTCRES_RECURSEres_nsend() / res_send()
      does not do iterative queries and expects the name server to handle
      recursion.)RES_DEFNAMESres_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_DNSRCHres_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_INET6RES_USE_EDNS0RES_NOALIASESHOSTALIASES environment variable. Network daemons
      should set this option.RES_ROTATEres_nsend() /
      res_send() to rotate the list of nameservers in
      statp->nsaddr_list /
      _res.nsaddr_list.RES_KEEPTSIGres_nsendsigned() to leave the
      message unchanged after TSIG verification; otherwise the TSIG record would
      be removed and the header updated.RES_NOTLDQUERYres_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.3 |