1LIBSRES(1) User Contributed Perl Documentation LIBSRES(1)
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 u_int16_t type,
19 const u_int16_t class,
20 struct name_server *nslist,
21 int edns0_size,
22 int *trans_id);
23 int response_recv(int *trans_id,
25 struct name_server **respondent,
26 u_int8_t **response,
27 u_int32_t *response_length);
28 int get(const char *name_n,
30 const u_int16_t type_h,
31 const u_int16_t class_h,
32 struct name_server *nslist,
33 int edns0_size,
34 struct name_server **respondent,
35 u_int8_t **response,
36 u_int32_t *response_length);
37 int clone_ns(struct name_server **cloned_ns, struct name_server *ns);
39 int clone_ns_list(struct name_server **ns_list,
41 struct name_server *orig_ns_list);
42 void free_name_server(struct name_server **ns);
44 void free_name_servers(struct name_server **ns);
46 void print_response(u_int8_t *response, int response_length);
48
50 The query_send() function sends a query to the name servers specified
51 in nslist. The query is comprised of the <name, class, type> tuple and
52 trans_id provides a handle to this transaction within the libsres
53 library. The buffer size advertised in the EDNS0 option can be set
54 using the ends0_size argument.
55 The response_recv() function returns the answers, if available, from
57 the name server that responds for the query identified by trans_id.
58 The response is available in response and the responding name server is
59 returned in respondent. The length of the response in bytes is
60 returned in response_length.
61 The get() function provides a wrapper around the query_send() and
63 response_recv() functions. After sending a request, it blocks until a
64 response is received from some name server or until the request times
65 out. The libsres library does not automatically follow referrals;
66 responses containing referrals are treated as valid responses.
67 The memory pointed to by *respondent is internally allocated by the
69 libsres library and must be freed by the invoker using
70 free_name_server(). An entire list of name servers can be freed using
71 free_name_servers(). A copy of the name server can be created using
72 clone_ns() and a copy of a name server list can be made using
73 clone_ns_list().
74 print_response() provides a convenient way to display answers returned
76 in response by the name server.
77 The name_server structure is defined in resolver.h as follows:
79 struct name_server
81 {
82 u_int8_t ns_name_n[NS_MAXCDNAME];
83 void *ns_tsig;
84 u_int32_t ns_security_options;
85 u_int32_t ns_status;
86 u_long ns_options;
87 int ns_retry;
88 int ns_retrans;
89 struct name_server *ns_next;
90 int ns_number_of_addresses;
91 struct sockaddr_storage **ns_address;
92 };
93 ns_name_n
95 The name of the zone for which this name server is authoritative.
96 ns_tsig
98 The tsig key that should be used to protect messages sent to this
99 name server. This field is currently unused and must be set to
100 NULL.
101 ns_security_options
103 The security options for the zone. This field is currently unused
104 and must be set to ZONE_USE_NOTHING.
105 ns_status
107 The status of the zone. This field indicates how the zone informa‐
108 tion was obtained. The invoker must set this value to SR_ZI_STA‐
109 TUS_UNSET. Zone information obtained through referrals have a value
110 of SR_ZI_STATUS_LEARNED for this field.
111 ns_options
113 Specifies additional resolver flags. Currently defined flags are
114 RES_RECURSE, which sets the "Recursion Desired" flag;
115 RES_USE_DNSSEC, which sets the "DNSSEC OK" bit in the EDNS0 header;
116 and RES_DEBUG, which enables debugging.
117 ns_retry
119 Specifies the maximum number of attempts that must be made to
120 obtain a name from an unresponsive name server before giving up.
121 ns_retrans
123 Specifies the retransmission interval in seconds for queries sent
124 to unresponsive name servers.
125 ns_next
127 The address of the next name server in the list.
128 ns_number_of_addresses
130 The number of elements in the array ns_addresses. This field is
131 currently unused.
132 ns_addresses
134 The IP address of the name server.
135
137 The libsres library also exports the following BIND functions, documen‐
138 tation for which can be found in the BIND sources and documentation
139 manuals:
140 res_nametoclass
142 res_nametotype
143 ns_name_ntop
144 ns_name_pton
145 ns_name_unpack
146 ns_parse_ttl
147 p_class
148 p_section
149 p_type
150 The p_type() function exported from libsres has been augmented such
152 that it recognizes the various DNSSEC type codes such DNSKEY, RRSIG,
153 NSEC, NSEC3 and DLV.
154
156 SR_UNSET
157 No error.
158 SR_CALL_ERROR
160 An invalid parameter was passed to get(), query_send(), or
161 response_recv().
162 SR_INTERNAL_ERROR
164 The resolver encountered some internal error.
165 SR_TSIG_ERROR
167 The resolver encountered some TSIG-related error. This is cur‐
168 rently not implemented.
169 SR_NO_ANSWER
171 No answers were received from any name server.
172 SR_NO_ANSWER_YET
174 No answer currently available; the query is still active.
175 SR_HEADER_ERROR
177 The length and count of records in the header were incorrect.
178 SR_NXDOMAIN
180 The queried name did not exist.
181 SR_FORMERR
183 The name server was not able to parse the query message.
184 SR_SERVFAIL
186 The name server was not reachable.
187 SR_NOTIMPL
189 A particular functionality is not yet implemented.
190 SR_REFUSED
192 The name server refused to answer this query.
193 SR_DNS_GENERIC_FAILURE
195 Other failure returned by the name server and reflected in the
196 returned message RCODE.
197 SR_EDNS_VERSION_ERROR
199 The EDNS version was not recognized
200 SR_NAME_EXPANSION_FAILURE
202 A failure was encountered while trying to expand a compressed
203 domain name.
204
206 There is currently no support for IPv6.
207 There is limited support for specifying resolver policy; members of the
209 struct name_server are still subject to change.
210
212 Copyright 2004-2007 SPARTA, Inc. All rights reserved. See the COPYING
213 file included with the dnssec-tools package for details.
214
216 libval(3)
217 http://dnssec-tools.sourceforge.net
219perl v5.8.6 2007-09-10 LIBSRES(1)