libsres

Section: Programmer's Manual (3)
Updated: 2009-01-26
Index Return to Main Contents

NAME

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

SYNOPSIS

  #include <resolver.h>

  int query_send(const char    *name,
            const u_int16_t     type,
            const u_int16_t     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,
            u_char              **response,
            size_t              *response_length);

  int get(const char          *name_n,
          const u_int16_t     type_h,
          const u_int16_t     class_h,
          struct name_server  *nslist,
          int                 edns0_size,
          struct name_server  **respondent,
          u_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(u_char *response, size_t response_length);

DESCRIPTION

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.

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:

    struct name_server
    {
        u_int8_t ns_name_n[NS_MAXCDNAME];
        void *ns_tsig;
        u_int32_t ns_security_options;
        u_int32_t ns_status;
        u_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.
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 RES_RECURSE, which sets the ``Recursion Desired'' flag; RES_USE_DNSSEC, which sets the ``DNSSEC OK'' bit in the EDNS0 header; and RES_DEBUG, which enables debugging.
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.

OTHER SYMBOLS EXPORTED

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.

RETURN VALUES

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.

CURRENT STATUS

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.