getdns_general_sync (3) - Linux Manuals

getdns_general_sync: do a getdns DNS lookup

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 special 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 asynchronous signature accepts a callback function, the synchronous signature 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 context 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/assignments/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 ALSO

libgetdns(3), getdns_address(3), getdns_context(3), getdns_free_sync_request_memory(3), getdns_hostname(3), getdns_service(3),

Pages related to getdns_general_sync