---
name: "getdns_general"
section: "3"
platform: "linux"
package: "getdns"
version: "1.7.3-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/getdns_general"
---

# 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)](/getdns_general/3.md) 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)](/getdns_address/3.md) which would replace [getaddrinfo(3)](/getaddrinfo/3.md).

*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)](/libgetdns/3.md), [**getdns\_address**(3)](/getdns_address/3.md), [**getdns\_context**(3)](/getdns_context/3.md), **getdns\_free\_sync\_request\_memory**(3), [**getdns\_hostname**(3)](/getdns_hostname/3.md), [**getdns\_service**(3)](/getdns_service/3.md),