--- name: "libwget-dns" section: "3" platform: "linux" package: "wget2-dev" version: "2.2.0+ds-1+deb13u1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/libwget-dns" --- # libwget-dns(3) DNS resolver functions ## NAME libwget-dns - DNS resolver functions ## SYNOPSIS ### Data Structures struct **wget\_dns\_stats\_data**\ struct **wget\_dns\_st**\ ### Functions **INITIALIZER** (dns\_init)\ int **wget\_dns\_init** (**wget\_dns** \*\*dns)\ void **wget\_dns\_free** (**wget\_dns** \*\*dns)\ void **wget\_dns\_set\_timeout** (**wget\_dns** \*dns, int timeout)\ void **wget\_dns\_set\_cache** (**wget\_dns** \*dns, **wget\_dns\_cache** \*cache)\ **wget\_dns\_cache** \* **wget\_dns\_get\_cache** (**wget\_dns** \*dns)\ int **wget\_dns\_cache\_ip** (**wget\_dns** \*dns, const char \*ip, const char \*name, uint16\_t port)\ struct addrinfo \* **wget\_dns\_resolve** (**wget\_dns** \*dns, const char \*host, uint16\_t port, int family, int preferred\_family)\ void **wget\_dns\_freeaddrinfo** (**wget\_dns** \*dns, struct addrinfo \*\*addrinfo)\ void **wget\_dns\_set\_stats\_callback** (**wget\_dns** \*dns, wget\_dns\_stats\_callback \*fn, void \*ctx)\ ## Detailed Description DNS Resolver functions. ## Function Documentation ### int wget\_dns\_init (wget\_dns \*\* dns) **Parameters** *dns* Pointer to return newly allocated and initialized wget\_dns instance **Returns** WGET\_E\_SUCCESS if OK, WGET\_E\_MEMORY if out-of-memory or WGET\_E\_INVALID if the mutex initialization failed. Allocates and initializes a wget\_dns instance. `dns` may be NULL for the purpose of initializing the global structures. ### void wget\_dns\_free (wget\_dns \*\* dns) **Parameters** *\[in/out\]* dns Pointer to wget\_dns instance that will be freed and NULLified. Free the resources allocated by **wget\_dns\_init()**. `dns` may be NULL for the purpose of freeing the global structures. ### void wget\_dns\_set\_timeout (wget\_dns \* dns, int timeout) **Parameters** *dns* The wget\_dns instance to set the timeout \ *timeout* The timeout value. Set the timeout (in milliseconds) for the DNS queries. This is the maximum time to wait until we get a response from the server. Warning: For standard getaddrinfo() a timeout can't be set in a portable way. So this functions currently is a no-op. The following two values are special: - • `0`: No timeout, immediate. - • `-1`: Infinite timeout. Wait indefinitely. ### void wget\_dns\_set\_cache (wget\_dns \* dns, wget\_dns\_cache \* cache) **Parameters** *dns* A `wget_dns` instance, created by **wget\_dns\_init()**. \ *cache* A `wget_dns_cache` instance Enable or disable DNS caching for the DNS instance provided. The DNS cache is kept internally in memory, and is used in **wget\_dns\_resolve()** to speed up DNS queries. ### wget\_dns\_cache \* wget\_dns\_get\_cache (wget\_dns \* dns) **Parameters** *dns* A `wget_dns` instance, created by **wget\_dns\_init()**. **Returns** 1 if DNS caching is enabled, 0 otherwise. Tells whether DNS caching is enabled or not. You can enable and disable DNS caching with wget\_dns\_set\_caching(). ### int wget\_dns\_cache\_ip (wget\_dns \* dns, const char \* ip, const char \* name, uint16\_t port) **Parameters** *ip* IP address of name \ *name* Domain name, part of the cache's lookup key \ *port* Port number, part of the cache's lookup key **Returns** 0 on success, \< 0 on error Assign an IP address to the name+port key in the DNS cache. The `name` should be lowercase. ### struct addrinfo \* wget\_dns\_resolve (wget\_dns \* dns, const char \* host, uint16\_t port, int family, int preferred\_family) **Parameters** *dns* A `wget_dns` instance, created by **wget\_dns\_init()**. \ *host* Hostname \ *port* TCP destination port \ *family* Protocol family AF\_INET or AF\_INET6 \ *preferred\_family* Preferred protocol family AF\_INET or AF\_INET6 **Returns** A `struct addrinfo` structure (defined in libc's ``). Must be freed by the caller with **wget\_dns\_freeaddrinfo().** **Resolve a host name into its IPv4/IPv6 address.** **family: Desired address family for the returned addresses. This will typically be** `AF_INET` **or** `AF_INET6`**, but it can be any of the values defined in** ``**. Additionally,** `AF_UNSPEC` **means you don't care: it will return any address family that can be used with the specified** `host` **and** `port`**. If family is different than** `AF_UNSPEC` **and the specified family is not found,** *that's an error condition* **and thus wget\_dns\_resolve() will return NULL.** **preferred\_family: Tries to resolve addresses of this family if possible. This is only honored if family (see point above) is** `AF_UNSPEC`**.** **The returned** `addrinfo` **structure must be freed with wget\_dns\_freeaddrinfo().** ### void wget\_dns\_freeaddrinfo (wget\_dns \* dns, struct addrinfo \*\* addrinfo) **Parameters** *dns* **A** `wget_dns` **instance, created by wget\_dns\_init().** \ *\[in/out\]* **addrinfo Value returned by** `c` **Release addrinfo, previously returned by wget\_dns\_resolve(). If the underlying** `dns` **uses caching, just the reference/pointer is set to NULL.** ### void wget\_dns\_set\_stats\_callback (wget\_dns \* dns, wget\_dns\_stats\_callback \* fn, void \* ctx) **Parameters** *dns* **A** `wget_dns` **instance, created by wget\_dns\_init().** \ *fn* **A** `wget_dns_stats_callback` **callback function to receive resolve statistics data** \ *ctx* **Context data given to** `fn` **Set callback function to be called once DNS statistics for a host are collected** ## Author **Generated automatically by Doxygen for wget2 from the source code.**