plucky (3) getdns_general.3.gz

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 satisfied 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),