1
2getdns_general(3) getdns getdns_general(3)
3
4
5
7 getdns_general, getdns_general_sync -- do a getdns DNS lookup
8
9
11 DNS Resolver library (libgetdns, -lgetdns)
12
13
15 #include <getdns.h>
16
17 getdns_return_t
18 getdns_general (getdns_context *context,
19 const char *name,
20 uint16_t request_type
21 getdns_dict *extensions,
22 void *userarg,
23 getdns_transaction_t *transaction_id,
24 getdns_callback_t callbackfn)
25
26 getdns_return_t
27 getdns_general_sync (getdns_context *context,
28 const char *name,
29 uint16_t request_type
30 getdns_dict *extensions,
31 getdns_dict **response)
32
33
35 The getdns_general(3) and getdns_general_sync functions provide public
36 entry points into the getdns API library to retrieve any valid re‐
37 sponses to a query from the DNS (note that other namespaces in the con‐
38 text are not used). Most typical use cases for applications are prob‐
39 ably satisfied via calls to getdns_address(3) which would replace
40 getaddrinfo(3).
41
42
43 context A pointer to the previsouly created DNS context that is to be
44 used with this DNS request. see getdns_context (3)
45
46
47 name The ASCII-based domain name looked up as a string. This can also
48 be an IPv4 or IPv6 address for request types that take addresses in‐
49 stead of domain names, such as PTR. The values here follow the rules
50 in section 2.1 of RFC 4343 to allow non-ASCII octets and special
51 characters in labels.
52
53
54 request_type Specifies the RRtype for the query; the RRtype numbers are
55 listed in the IANA registry. For example, to get the NS records, re‐
56 quest_type would be 2. The API also has defined macros for most of
57 the RRtypes by name; the definition names all start with
58 "GETDNS_RRTYPE_". For example, to get the NS records, you can also
59 set the request_type to GETDNS_RRTYPE_NS.
60
61
62 extensions extensions for this request, NULL if no extensions, see
63 libgetnds (3) for a detailed description of extensions
64
65
66 userarg returned to the callback function untouched, can be NULL
67
68
69 transaction_id populated by the API and used to identify the callback
70 (for example to getdns_cancel_callback), can be NULL, set to 0 if
71 the function fails
72
73
74 callbackfn non-NULL pointer to a callback function defined by the ap‐
75 plication, typically used to process the response. Only the asyn‐
76 chronous signature accepts a callback function, the synchronous sig‐
77 nature does not include a callback. See libgetdns (3) for a more
78 detailed discussion of callback functions.
79
80
81 response A getdns_dict type is returned in response and always contains
82 at least three names: replies_full (a list containing the DNS re‐
83 sponse as binary data), replies_tree (a list containing the parsed
84 DNS response data) and status (an int). The storage associated with
85 this must be freed by a call to getdns_free_sync_request_memory (3).
86
87
88
89
91 Upon successful completion the functions return GETDNS_RETURN_GOOD ,
92 otherwise the following error values are returned:
93
94
95 GETDNS_RETURN_BAD_CONTEXT if the context pointer is invalid or the con‐
96 text has internal deficiencies
97
98 GETDNS_RETURN_BAD_DOMAIN_NAME if the domain name passed to the function
99 is invalid
100
101 GETDNS_RETURN_EXTENSION_MISFORMAT if the data type specified in one or
102 more of the extensions does not match the specifications
103
104 GETDNS_RETURN_GENERIC_ERROR if some problem was encountered in the
105 function not addressed by one of the more specific return codes
106
107 GETDNS_RETURN_INVALID PARAMETER if one or more parameters has an in‐
108 valid value
109
110 GETDNS_RETURN_MEMORY_ERROR if unable to allocate the memory required
111
112 GETDNS_RETURN_NO_SUCH_EXTENSION if one or more of the strings specified
113 in the extensions are not valid
114
115 The values of status included in the response parameter are:
116
117
118 GETDNS_RESPSTATUS_GOOD if at least one response was returned
119
120 GETDNS_RESPSTATUS_NO_NAME if queries for the name yielded all negative
121 responses
122
123 GETDNS_RESPSTATUS_ALL_TIMEOUT if all queries for the name timed out
124
125 GETDNS_RESPSTATUS_NO_SECURE_ANSWERS if only secure replies accepted
126 (per context) and at least one response was received but no DNS re‐
127 sponses were secure through DNSSEC
128
129
130 For a more detailed explanation of the response object see libgetdns
131 (3)
132
133
135 This is a list of the most common request types, a full list of request
136 types in more detail is available at http://www.iana.org/assign‐
137 ments/dns-parameters/dns-parameters.xml
138
139
140 A Host address
141
142 AAAA IPv6 address
143
144 CAA Certificate Authority Authorization
145
146 CNAME Canonical name for an alias
147
148 DLV DNSSEC lookaside validation
149
150 DNAME DNAME
151
152 DS Delegation signer
153
154 HINFO Host information
155
156 KEY Security key
157
158 MINFO Mailbox or mail list information
159
160 MX Mail exchange
161
162 NS Authoritative name server
163
164 NSEC Next secure record
165
166 NSEC3 Next secure record (hashed)
167
168 NSEC3PARAM NSEC3PARAM
169
170 PTR Domain name pointer
171
172 RRSIG Signature for a record set
173
174 SIG Security signature
175
176 SOA Marks the start of a zone of authority
177
178 SRV Server selection
179
180 TA DNSSEC trust authorities
181
182 TKEY Transaction key
183
184 TLSA TLSA
185
186 TSIG Transaction signature
187
188 TXT Text strings
189
190
192 TBD
193
194
196 /etc/hosts
197 /etc/resolv.conf
198
199
201 libgetdns(3), getdns_address(3), getdns_context(3),
202 getdns_free_sync_request_memory(3), getdns_hostname(3), getdns_ser‐
203 vice(3),
204
205
206
207
208getdns 1.7.3 December 2015 getdns_general(3)