/ 
DNS-Unbound-0.05
River stage zero No dependents
/ DNS::Unbound

NAME

DNS::Unbound - libunbound in Perl

SYNOPSIS

my $dns = DNS::Unbound->new()->set_option( verbosity => 2 );

my $verbosity = $dns->get_option( 'verbosity' );

$dns->set_option( verbosity => 1 + $verbosity );

Synchronous queries:

my $res_hr = $dns->resolve( 'cpan.org', 'NS' );

# See below about encodings in “data”.
my @ns = map { $dns->decode_name($_) } @{ $res_hr->{'data'} };

Asynchronous queries use the “Promise” pattern:

my $query1 = $dns->resolve_async( 'usa.gov', 'A' )->then(
    sub { my $data = shift()->{'data'}; ... },  # success handler
    sub { ... },                                # failure handler
);

my $query2 = $dns->resolve_async( 'in-addr.arpa', 'NS' )->then(
    sub { ... },
    sub { ... },
);

# As an alternative to wait(), see below for documentation on
# the fd(), poll(), and process() methods.

$dns->wait();

DESCRIPTION

This library is a Perl interface to NLNetLabs’s widely-used Unbound recursive DNS resolver.

METHODS

CLASS->new()

Instantiates this class.

$result_hr = OBJ->resolve( $NAME, $TYPE [, $CLASS ] )

Runs a synchronous query for a given $NAME and $TYPE. $TYPE may be expressed numerically or, for convenience, as a string. $CLASS is optional and defaults to 1 (IN), which is probably what you want.

Returns a reference to a hash that corresponds to a libunbound struct ub_result (cf. libunbound(3)), excluding len, answer_packet, and answer_len.

NOTE: Members of data are in their DNS-native RDATA encodings. (libunbound doesn’t track which record type uses which encoding, so neither does DNS::Unbound.) To decode some common record types, see "CONVENIENCE FUNCTIONS" below.

Also NOTE: libunbound’s facilities for timing out a synchronous query are rather lackluster. If that’s relevant for you, you probably want to use resolve_async() instead.

$query = OBJ->resolve_async( $NAME, $TYPE [, $CLASS ] );

Like resolve() but starts an asynchronous query rather than a synchronous one.

This returns an instance of DNS::Unbound::AsyncQuery, which subclasses Promise::ES6. You may cancel() this promise object. The promise resolves with either the same hash reference as resolve() returns, or it rejects with a DNS::Unbound::X instance that describes the failure.

OBJ->enable_threads()

Sets OBJ’s asynchronous queries to use threads rather than forking. Off by default. Throws an exception if called after an asynchronous query has already been sent.

Returns OBJ.

NOTE: Perl’s relationship with threads is … complicated. This option is not well-tested. If in doubt, just skip it.

OBJ->set_option( $NAME => $VALUE )

Sets a configuration option. Returns OBJ.

$value = OBJ->get_option( $NAME )

Gets a configuration option’s value.

$str = CLASS->unbound_version()

Gives the libunbound version string.

METHODS FOR DEALING WITH ASYNCHRONOUS QUERIES

The following methods correspond to their equivalents in libunbound:

OBJ->poll()

OBJ->fd()

OBJ->wait()

OBJ->process()

CONVENIENCE FUNCTIONS

Note that Socket provides the inet_ntoa() and inet_ntop() functions for decoding A and AAAA records.

The following may be called either as object methods or as static functions (but not as class methods):

$decoded = decode_name($encoded)

Decodes a DNS name. Useful for, e.g., NS query results.

Note that this will normally include a trailing . because of the trailing NUL byte in an encoded DNS name.

$strings_ar = decode_character_strings($encoded)

Decodes a list of character-strings into component strings, returned as an array reference. Useful for TXT query results.

REPOSITORY

https://github.com/FGasper/p5-DNS-Unbound

THANK YOU

Special thanks to ATOOMIC for making some helpful review notes.