libsres






query_send(), response_rcv(), get() − send queries and
receive responses from a DNS name server.

     clone_ns(), clone_ns_list(), free_name_server(),
free_name_servers() − manage name server lists

     print_response() − display answers returned from the
name server


  #include <resolver.h>

  int query_send(const char    *name,
            const unsigned short type,
            const unsigned short class,
            struct name_server  *nslist,
            int                 edns0_size,
            int                 *trans_id);

  int response_recv(int         *trans_id,
            fd_set              *pending_desc,
            struct timeval      *closest_event,
            struct name_server  **respondent,
            unsigned char       **response,
            size_t              *response_length);

  int get(const char          *name_n,
          const unsigned short type_h,
          const unsigned short class_h,
          struct name_server  *nslist,
          struct name_server  **respondent,
          unsigned char       **response,
          size_t              *response_length);

  int clone_ns(struct name_server **cloned_ns,
          struct name_server *ns);

  int clone_ns_list(struct name_server **ns_list,
                    struct name_server *orig_ns_list);

  void free_name_server(struct name_server **ns);

  void free_name_servers(struct name_server **ns);

  void print_response(unsigned char *response,
            size_t response_length);

The query_send() function sends a query to the name servers
specified in nslist.  The query is comprised of the <name,
class, type> tuple and trans_id provides a handle to this
transaction within the libsres library.  The buffer size
advertised in the EDNS0 option can be set using the
ends0_size argument.










                             ‐2‐


     The response_recv() function returns the answers, if
available, from the name server that responds for the query
identified by trans_id.  The response is available in
response and the responding name server is returned in
respondent.  The length of the response in bytes is returned
in response_length.

     The get() function provides a wrapper around the
query_send() and response_recv() functions.  After sending a
request, it blocks until a response is received from some
name server or until the request times out.  The libsres
library does not automatically follow referrals; responses
containing referrals are treated as valid responses.

     The memory pointed to by *respondent is internally
allocated by the libsres library and must be freed by the
invoker using free_name_server().  An entire list of name
servers can be freed using free_name_servers().  A copy of
the name server can be created using clone_ns() and a copy
of a name server list can be made using clone_ns_list().

     print_response() provides a convenient way to display
answers returned in response by the name server.

     The name_server structure is defined in resolver.h as
follows:

         #define NS_MAXCDNAME    255
    struct name_server
    {
        unsigned char ns_name_n[NS_MAXCDNAME];
        void *ns_tsig;
        unsigned int ns_security_options;
        unsigned int ns_status;
        unsigned long ns_options;
        int ns_retry;
        int ns_retrans;
        struct name_server *ns_next;
        int ns_number_of_addresses;
        struct sockaddr_storage **ns_address;
    };

ns_name_n
    The name of the zone for which this name server is
    authoritative.

ns_tsig
    The tsig key that should be used to protect messages
    sent to this name server. This field is currently unused
    and must be set to NULL.

ns_security_options
    The security options for the zone.  This field is
    currently unused and must be set to ZONE_USE_NOTHING.









                             ‐3‐


ns_status
    The status of the zone.  This field indicates how the
    zone information was obtained. The invoker must set this
    value to SR_ZI_STATUS_UNSET. Zone information obtained
    through referrals have a value of SR_ZI_STATUS_LEARNED
    for this field.

ns_options
    Specifies additional resolver flags.  Currently defined
    flags are SR_QUERY_RECURSE, which sets the "Recursion
    Desired" flag; SR_QUERY_SET_DO, which sets the "DNSSEC
    OK" bit in the EDNS0 header; SR_QUERY_SET_CD, which sets
    the "DNSSEC CD" bit in the EDNS0 header; and
    SR_QUERY_DEBUG, which enables debugging.
    SR_QUERY_VALIDATING_STUB_FLAGS sets both SR_QUERY_SET_DO
    and SR_QUERY_SET_CD.

ns_retry
    Specifies the maximum number of attempts that must be
    made to obtain a name from an unresponsive name server
    before giving up.

ns_retrans
    Specifies the retransmission interval in seconds for
    queries sent to unresponsive name servers.

ns_next
    The address of the next name server in the list.

ns_number_of_addresses
    The number of elements in the array ns_addresses.  This
    field is currently unused.

ns_addresses
    The IP address of the name server.

The libsres library also exports the following BIND
functions, documentation for which can be found in the BIND
sources and documentation manuals:

       res_nametoclass
  res_nametotype
  ns_name_ntop
  ns_name_pton
  ns_name_unpack
  ns_parse_ttl
  p_class
  p_section
  p_type

     The p_type() function exported from libsres has been
augmented such that it recognizes the various DNSSEC type
codes such DNSKEY, RRSIG, NSEC, NSEC3 and DLV.










                             ‐4‐




SR_UNSET
    No error.

SR_CALL_ERROR
    An invalid parameter was passed to get(), query_send(),
    or response_recv().

SR_INTERNAL_ERROR
    The resolver encountered some internal error.

SR_TSIG_ERROR
    The resolver encountered some TSIG‐related error.  This
    is currently not implemented.

SR_NO_ANSWER
    No answers were received from any name server.

SR_NO_ANSWER_YET
    No answer currently available; the query is still
    active.

SR_HEADER_ERROR
    The length and count of records in the header were
    incorrect.

SR_NXDOMAIN
    The queried name did not exist.

SR_FORMERR
    The name server was not able to parse the query message.

SR_SERVFAIL
    The name server was not reachable.

SR_NOTIMPL
    A particular functionality is not yet implemented.

SR_REFUSED
    The name server refused to answer this query.

SR_DNS_GENERIC_FAILURE
    Other failure returned by the name server and reflected
    in the returned message RCODE.

SR_EDNS_VERSION_ERROR
    The EDNS version was not recognized

SR_NAME_EXPANSION_FAILURE
    A failure was encountered while trying to expand a
    compressed domain name.











                             ‐5‐


There is currently no support for IPv6.

     There is limited support for specifying resolver
policy; members of the struct name_server are still subject
to change.

Copyright 2004−2013 SPARTA, Inc.  All rights reserved.  See
the COPYING file included with the dnssec‐tools package for
details.

libval(3)

     http://www.dnssec−tools.org