--- name: "getdns_context_set" 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_context_set" --- # getdns\_context\_set(3) ## NAME **getdns\_context\_set\_append\_name,** **getdns\_context\_set\_context\_update\_callback,** **getdns\_context\_set\_dns\_root\_servers,** **getdns\_context\_set\_dns\_transport,** **getdns\_context\_set\_dnssec\_trust\_anchors,** **getdns\_context\_set\_dnssec\_allowed\_skew,** **getdns\_context\_set\_follow\_redirects,** **getdns\_context\_set\_limit\_outstanding\_queries,** **getdns\_context\_set\_namespaces,** **getdns\_context\_set\_resolution\_type,** **getdns\_context\_set\_suffix,** **getdns\_context\_set\_timeout,** -- getdns context manipulation routines ## LIBRARY DNS Resolver library (libgetdns, -lgetdns) ## SYNOPSIS \#include \ getdns\_return\_t \ **getdns\_context\_set\_append\_name** (getdns\_context\_t context, getdns\_append\_name\_t when\_to\_append) getdns\_return\_t \ **getdns\_context\_set\_context\_update\_callback** (getdns\_context\_t context, (\*callback)(struct getdns\_context \*context, uint16\_t changed\_item)) getdns\_return\_t \ **getdns\_context\_set\_dns\_root\_servers** (getdns\_context\_t context, getdns\_list \*root\_addresses) getdns\_return\_t \ **getdns\_context\_set\_dns\_transport** (getdns\_context\_t context, uint16\_t transport) getdns\_return\_t\ **getdns\_contet\_set\_dnssec\_allowed\_skew** (getdns\_context \*context, uint32\_t skew\_seconds) getdns\_return\_t\ **getdns\_contet\_set\_dnssec\_trust\_anchors** (getdns\_context \*context, getdns\_list \*trust\_anchors) getdns\_return\_t \ **getdns\_context\_set\_follow\_redirects** (getdns\_context\_t context, getdns\_redirects\_t followredir) getdns\_return\_t \ **getdns\_context\_set\_limit\_outstanding\_queries** (getdns\_context\_t context, uint16\_t limit) getdns\_return\_t \ **getdns\_context\_set\_namespaces** (getdns\_context\_t context, size\_t namespace\_count,\ uint16\_t \*namespaces) getdns\_return\_t \ **getdns\_context\_set\_resolution\_type** (getdns\_context\_t context, uint16\_t restype) getdns\_return\_t\ **getdns\_context\_set\_suffix** (getdns\_context \*context, getdns\_list \*suffixes) getdns\_return\_t \ **getdns\_context\_set\_timeout** (getdns\_context\_t context, uint16\_t timeout) ## DESCRIPTION These functions are used to manipulate a previously allocated and initialized context, see getdns\_context (3) for more details on the functions used to allocate, initialized and destroy contexts and for a more detailed discussion of the getdns\_context in general. **getdns\_context\_set\_append\_name** Specifies whether to append a suffix supplied via getdns\_context\_set\_suffix (3) to the query string before the API starts resolving a name. **getdns\_context\_set\_context\_update\_callback** sets a function that will be called if changes to the system files (for example /etc/resolv.conf and /etc/hosts). **getdns\_context\_set\_dns\_transport** specifies the transport used for DNS lookups, the default is to use UDP and fall back to TCP as needed. **getdns\_context\_set\_dnssec\_trust\_anchors** allows the caller to specify trust anchors as alternatives to the default trust anchors **getdns\_context\_set\_dnssec\_allowed\_skew** set the number of seconds skew allowed in either direction when checking an RRSIGs expiration and inception fields, the default is 0. **getdns\_context\_set\_limit\_outstanding\_queries** specifies the maximum number of outstanding DNS queries, the API will queue queries over this limit until current queries are answers and will then automatically issue the queries on the queue. **getdns\_context\_set\_dns\_root\_servers** provides an alternate set of addresses to use to look up the top level domains. The default (if this function is not called) is the list of IANA root servers (think of this as the root hints). **getdns\_context\_set\_follow\_redirects** specifies whether or not DNS queries follow redirects (CNAME and DNAME), the default behavior is to follow redirects and return the eventual target. **getdns\_context\_set\_namespaces** sets the namespaces to be used by the resolver, the default is DNS and then local files. Future implementations will support netbios, mdns, and nis. **getdns\_context\_set\_resolution\_type** specifies whether DNS queries are performed with non-recursive lookups or as a stub resolver. **getdns\_context\_set\_suffix** Append suffixes to domain names prior to executing the lookup based on getdns\_context\_set\_append\_name. **getdns\_context\_set\_timeout** specifies the number of milliseconds the API will wait for a response. *context* a previously allocated and initialized getdns\_context *callback* a callback function that will be called when changes are made to the system files (/etc/resolv.conf and /etc/hosts) for contexts created with set\_from\_os = 1. When this function is called the changed\_item parameter indicates which item in the context has changed. *root\_addresses* This is a list of getdns\_dict types that each identify a single root server to use to look up top level domains. Each dictionary includes two names, *address\_type* , a bindata containing the string "IPv4" or "IPv6" and *address\_data* a bindata containing the IP address. *transport* may be one of GETDNS\_CONTEXT\_UDP\_FIRST\_AND\_FALL\_BACK\_TO\_TCP, GETDNS\_CONTEXT\_UDP\_ONLY, GETDNS\_CONTEXT\_TCP\_ONLY, GETDNS\_CONTEXT\_TCP\_ONLY\_KEEP\_CONNECTIONS\_OPEN. If you need more information on what each of these means reread the mnemonic and take a guess ;) *followredir* If set to GETDNS\_REDIRECTS\_FOLLOW (the default) then the eventual target of the redirect is returned. If set to GETDNS\_REDIRECTS\_DO\_NOT\_FOLLOW then the CNAME or DNAME is returned and NOT the eventual target. *limit* the maximum number of concurrent outstanding (unanswered) DNS queries, if exceeded the API will queue queries and issue them as the number of outstanding queries drops. A value of 0 indicates that there is no limit. *namespaces* The namespaces array contains an ordered list of namespaces that will be queried. Important: this context setting is ignored for the getdns\_general and getdns\_general\_sync functions; it is used for the other functions. The values are GETDNS\_CONTEXT\_NAMESPACE\_DNS, GETDNS\_CONTEXT\_NAMESPACE\_LOCALNAMES, GETDNS\_CONTEXT\_NAMESPACE\_NETBIOS, GETDNS\_CONTEXT\_NAMESPACE\_MDNS, and GETDNS\_CONTEXT\_NAMESPACE\_NIS. When a normal lookup is done, the API does the lookups in the order given and stops when it gets the first result; a different method with the same result would be to run the queries in parallel and return when it gets the first result. Because lookups might be done over different mechanisms because of the different namespaces, there can be information leakage that is similar to that seen with getaddrinfo(). The default is determined by the OS. *restype* can be set to either GETDNS\_CONTEXT\_RECURSIVE (the default) or GETDNS\_CONTEXT\_STUB (requires that forwarders be specified by the caller). *seconds\_skew* the number of seconds skew allowed in either direction when checking an RRSIGs expiration and inception fields. *suffixes* A list of bindatas that are strings that are to be appended based on getdns\_context\_set\_append\_name. The values here follow the rules in section 2.1 of RFC 4343 to allow non-ASCII octets and special characters in labels. *timeout* the number of milliseconds the API will wait for a response, after which the callback will be invoked (or the synchronous function will return) with a timeout error. *trust\_anchors* list of bindatas that are the DNSSEC trust anchors expressed as RDATA from the DNSKEY resource records, the default are supplied by the IANA root. *when\_to\_append* The value is - • GETDNS\_APPEND\_NAME\_ALWAYS, - • GETDNS\_APPEND\_NAME\_ONLY\_TO\_SINGLE\_LABEL\_AFTER\_FAILURE, - • GETDNS\_APPEND\_NAME\_ONLY\_TO\_MULTIPLE\_LABEL\_NAME\_AFTER\_FAILURE, or - • GETDNS\_APPEND\_NAME\_NEVER. ## 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 **GETDNS\_RETURN\_CONTEXT\_UPDATE\_FAIL** if there was a problem updating the context ## EXAMPLES TBD ## FILES /etc/hosts\ /etc/resolv.conf ## SEE ALSO [**libgetdns**(3)](/libgetdns/3.md), [**getdns\_address**(3)](/getdns_address/3.md), [**getdns\_address\_sync**(3)](/getdns_address_sync/3.md), [**getdns\_context**(3)](/getdns_context/3.md), [**getdns\_general**(3)](/getdns_general/3.md), [**getdns\_general\_sync**(3)](/getdns_general_sync/3.md), [**getdns\_hostname**(3)](/getdns_hostname/3.md), [**getdns\_hostname\_sync**(3)](/getdns_hostname_sync/3.md), [**getdns\_service**(3)](/getdns_service/3.md), [**getdns\_service\_sync**(3)](/getdns_service_sync/3.md).