getdns_general(3) getdns getdns_general(3)NAME
getdns_general, getdns_general_sync-- do a getdns DNS lookup
LIBRARY
DNS Resolver library (libgetdns, -lgetdns)
SYNOPSIS
#include <getdns.h>
getdns_return_t
getdns_general (getdns_context *context,
const char *name,
uint16_t request_type
getdns_dict *extensions,
void *userarg,
getdns_transaction_t *transaction_id,
getdns_callback_t callbackfn)
getdns_return_t
getdns_general_sync (getdns_context *context,
const char *name,
uint16_t request_type
getdns_dict *extensions,
getdns_dict **response)
DESCRIPTION
The getdns_general(3) and getdns_general_sync functions provide public
entry points into the getdns API library to retrieve any valid
responses to a query from the DNS (note that other namespaces in the
context are not used). Most typical use cases for applications are
probably satisifed via calls to getdns_address(3) which would replace
getaddrinfo(3).
context A pointer to the previsouly created DNS context that is to be
used with this DNS request. see getdns_context (3)
name The ASCII-based domain name looked up as a string. This can also
be an IPv4 or IPv6 address for request types that take addresses
instead of domain names, such as PTR. The values here follow the
rules in section 2.1 of RFC 4343 to allow non-ASCII octets and spe‐
cial characters in labels.
request_type Specifies the RRtype for the query; the RRtype numbers are
listed in the IANA registry. For example, to get the NS records,
request_type would be 2. The API also has defined macros for most of
the RRtypes by name; the definition names all start with
"GETDNS_RRTYPE_". For example, to get the NS records, you can also
set the request_type to GETDNS_RRTYPE_NS.
extensions extensions for this request, NULL if no extensions, see
libgetnds (3) for a detailed description of extensions
userarg returned to the callback function untouched, can be NULL
transaction_id populated by the API and used to identify the callback
(for example to getdns_cancel_callback), can be NULL, set to 0 if
the function fails
callbackfn non-NULL pointer to a callback function defined by the
application, typically used to process the response. Only the asyn‐
chronous signature accepts a callback function, the synchronous sig‐
nature does not include a callback. See libgetdns (3) for a more
detailed discussion of callback functions.
response A getdns_dict type is returned in response and always contains
at least three names: replies_full (a list containing the DNS
response as binary data), replies_tree (a list containing the parsed
DNS response data) and status (an int). The storage associated with
this must be freed by a call to getdns_free_sync_request_memory (3).
RETURN VALUES
Upon successful completion the functions return GETDNS_RETURN_GOOD ,
otherwise the following error values are returned:
GETDNS_RETURN_BAD_CONTEXT if the context pointer is invalid or the con‐
text has internal deficiencies
GETDNS_RETURN_BAD_DOMAIN_NAME if the domain name passed to the function
is invalid
GETDNS_RETURN_EXTENSION_MISFORMAT if the data type specified in one or
more of the extensions does not match the specifications
GETDNS_RETURN_GENERIC_ERROR if some problem was encountered in the
function not addressed by one of the more specific return codes
GETDNS_RETURN_INVALID PARAMETER if one or more parameters has an
invalid value
GETDNS_RETURN_MEMORY_ERROR if unable to allocate the memory required
GETDNS_RETURN_NO_SUCH_EXTENSION if one or more of the strings specified
in the extensions are not valid
The values of status included in the response parameter are:
GETDNS_RESPSTATUS_GOOD if at least one response was returned
GETDNS_RESPSTATUS_NO_NAME if queries for the name yielded all negative
responses
GETDNS_RESPSTATUS_ALL_TIMEOUT if all queries for the name timed out
GETDNS_RESPSTATUS_NO_SECURE_ANSWERS if only secure replies accepted
(per context) and at least one response was received but no DNS
responses were secure through DNSSEC
For a more detailed explanation of the response object see libgetdns
(3)
REQUEST TYPES
This is a list of the most common request types, a full list of request
types in more detail is available at http://www.iana.org/assign‐
ments/dns-parameters/dns-parameters.xml
A Host address
AAAA IPv6 address
CAA Certificate Authority Authorization
CNAME Canonical name for an alias
DLV DNSSEC lookaside validation
DNAME DNAME
DS Delegation signer
HINFO Host information
KEY Security key
MINFO Mailbox or mail list information
MX Mail exchange
NS Authoritative name server
NSEC Next secure record
NSEC3 Next secure record (hashed)
NSEC3PARAM NSEC3PARAM
PTR Domain name pointer
RRSIG Signature for a record set
SIG Security signature
SOA Marks the start of a zone of authority
SRV Server selection
TA DNSSEC trust authorities
TKEY Transaction key
TLSA TLSA
TSIG Transaction signature
TXT Text strings
EXAMPLES
TBD
FILES
/etc/hosts
/etc/resolv.conf
SEE ALSOlibgetdns(3), getdns_address(3), getdns_context(3),
getdns_free_sync_request_memory(3), getdns_hostname(3), getdns_ser‐
vice(3),
getdns 0.9.0 December 2015 getdns_general(3)
