libsres

libsres(3)                    Programmer's Manual                   libsres(3)



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 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);

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:

           #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.

       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.

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.

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

SEE ALSO
       libval(3)

       http://www.dnssec-tools.org



perl v5.14.3                      2013-02-27                        libsres(3)