getdns_general_sync(3)

1
2getdns_general(3)                   getdns                   getdns_general(3)
3
4
5

NAME

7       getdns_general, getdns_general_sync -- do a getdns DNS lookup
8
9

LIBRARY

11       DNS Resolver library (libgetdns, -lgetdns)
12
13

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUES

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

REQUEST TYPES

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

EXAMPLES

192       TBD
193
194

FILES

196       /etc/hosts
197       /etc/resolv.conf
198
199