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