1libsres(3) Programmer's Manual libsres(3)
2
6 query_send(), response_rcv(), get() - send queries and receive
7 responses from a DNS name server.
8 clone_ns(), clone_ns_list(), free_name_server(), free_name_servers() -
10 manage name server lists
11 print_response() - display answers returned from the name server
13
15 #include <resolver.h>
16 int query_send(const char *name,
18 const unsigned short type,
19 const unsigned short class,
20 struct name_server *nslist,
21 int edns0_size,
22 int *trans_id);
23 int response_recv(int *trans_id,
25 fd_set *pending_desc,
26 struct timeval *closest_event,
27 struct name_server **respondent,
28 unsigned char **response,
29 size_t *response_length);
30 int get(const char *name_n,
32 const unsigned short type_h,
33 const unsigned short class_h,
34 struct name_server *nslist,
35 struct name_server **respondent,
36 unsigned char **response,
37 size_t *response_length);
38 int clone_ns(struct name_server **cloned_ns,
40 struct name_server *ns);
41 int clone_ns_list(struct name_server **ns_list,
43 struct name_server *orig_ns_list);
44 void free_name_server(struct name_server **ns);
46 void free_name_servers(struct name_server **ns);
48 void print_response(unsigned char *response,
50 size_t response_length);
51
53 The query_send() function sends a query to the name servers specified
54 in nslist. The query is comprised of the <name, class, type> tuple and
55 trans_id provides a handle to this transaction within the libsres
56 library. The buffer size advertised in the EDNS0 option can be set
57 using the ends0_size argument.
58 The response_recv() function returns the answers, if available, from
60 the name server that responds for the query identified by trans_id.
61 The response is available in response and the responding name server is
62 returned in respondent. The length of the response in bytes is
63 returned in response_length.
64 The get() function provides a wrapper around the query_send() and
66 response_recv() functions. After sending a request, it blocks until a
67 response is received from some name server or until the request times
68 out. The libsres library does not automatically follow referrals;
69 responses containing referrals are treated as valid responses.
70 The memory pointed to by *respondent is internally allocated by the
72 libsres library and must be freed by the invoker using
73 free_name_server(). An entire list of name servers can be freed using
74 free_name_servers(). A copy of the name server can be created using
75 clone_ns() and a copy of a name server list can be made using
76 clone_ns_list().
77 print_response() provides a convenient way to display answers returned
79 in response by the name server.
80 The name_server structure is defined in resolver.h as follows:
82 #define NS_MAXCDNAME 255
84 struct name_server
85 {
86 unsigned char ns_name_n[NS_MAXCDNAME];
87 void *ns_tsig;
88 unsigned int ns_security_options;
89 unsigned int ns_status;
90 unsigned long ns_options;
91 int ns_retry;
92 int ns_retrans;
93 struct name_server *ns_next;
94 int ns_number_of_addresses;
95 struct sockaddr_storage **ns_address;
96 };
97 ns_name_n
99 The name of the zone for which this name server is authoritative.
100 ns_tsig
102 The tsig key that should be used to protect messages sent to this
103 name server. This field is currently unused and must be set to
104 NULL.
105 ns_security_options
107 The security options for the zone. This field is currently unused
108 and must be set to ZONE_USE_NOTHING.
109 ns_status
111 The status of the zone. This field indicates how the zone
112 information was obtained. The invoker must set this value to
113 SR_ZI_STATUS_UNSET. Zone information obtained through referrals
114 have a value of SR_ZI_STATUS_LEARNED for this field.
115 ns_options
117 Specifies additional resolver flags. Currently defined flags are
118 SR_QUERY_RECURSE, which sets the "Recursion Desired" flag;
119 SR_QUERY_SET_DO, which sets the "DNSSEC OK" bit in the EDNS0
120 header; SR_QUERY_SET_CD, which sets the "DNSSEC CD" bit in the
121 EDNS0 header; and SR_QUERY_DEBUG, which enables debugging.
122 SR_QUERY_VALIDATING_STUB_FLAGS sets both SR_QUERY_SET_DO and
123 SR_QUERY_SET_CD.
124 ns_retry
126 Specifies the maximum number of attempts that must be made to
127 obtain a name from an unresponsive name server before giving up.
128 ns_retrans
130 Specifies the retransmission interval in seconds for queries sent
131 to unresponsive name servers.
132 ns_next
134 The address of the next name server in the list.
135 ns_number_of_addresses
137 The number of elements in the array ns_addresses. This field is
138 currently unused.
139 ns_addresses
141 The IP address of the name server.
142
144 The libsres library also exports the following BIND functions,
145 documentation for which can be found in the BIND sources and
146 documentation manuals:
147 res_nametoclass
149 res_nametotype
150 ns_name_ntop
151 ns_name_pton
152 ns_name_unpack
153 ns_parse_ttl
154 p_class
155 p_section
156 p_type
157 The p_type() function exported from libsres has been augmented such
159 that it recognizes the various DNSSEC type codes such DNSKEY, RRSIG,
160 NSEC, NSEC3 and DLV.
161
163 SR_UNSET
164 No error.
165 SR_CALL_ERROR
167 An invalid parameter was passed to get(), query_send(), or
168 response_recv().
169 SR_INTERNAL_ERROR
171 The resolver encountered some internal error.
172 SR_TSIG_ERROR
174 The resolver encountered some TSIG-related error. This is
175 currently not implemented.
176 SR_NO_ANSWER
178 No answers were received from any name server.
179 SR_NO_ANSWER_YET
181 No answer currently available; the query is still active.
182 SR_HEADER_ERROR
184 The length and count of records in the header were incorrect.
185 SR_NXDOMAIN
187 The queried name did not exist.
188 SR_FORMERR
190 The name server was not able to parse the query message.
191 SR_SERVFAIL
193 The name server was not reachable.
194 SR_NOTIMPL
196 A particular functionality is not yet implemented.
197 SR_REFUSED
199 The name server refused to answer this query.
200 SR_DNS_GENERIC_FAILURE
202 Other failure returned by the name server and reflected in the
203 returned message RCODE.
204 SR_EDNS_VERSION_ERROR
206 The EDNS version was not recognized
207 SR_NAME_EXPANSION_FAILURE
209 A failure was encountered while trying to expand a compressed
210 domain name.
211
213 There is currently no support for IPv6.
214 There is limited support for specifying resolver policy; members of the
216 struct name_server are still subject to change.
217
219 Copyright 2004-2013 SPARTA, Inc. All rights reserved. See the COPYING
220 file included with the dnssec-tools package for details.
221
223 libval(3)
224 http://www.dnssec-tools.org
226perl v5.14.3 2013-02-27 libsres(3)