libwget-dns(3) Introduction to Library Functions libwget-dns(3)

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:

+o 0: No timeout, immediate.

+o -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 <netdb.h>). 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 <socket.h>. 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.

wget2 Version 2.2.0 libwget-dns(3)