IO::As...r::DNS(3pm)

✨ NAME ✨

okay bestie, this is the IO::Async::Resolver::DNS(3pm) page from User Contributed Perl Documentation. The module is "IO::Async::Resolver::DNS" — resolve DNS queries using "IO::Async". periodt. 💖

🌸 SYNOPSIS 🌸

here's the vibe, copy-paste style:

use IO::Async::Loop;
use IO::Async::Resolver::DNS;

my $loop = IO::Async::Loop->new;
my $resolver = $loop->resolver;

$resolver->res_query(
   dname => "cpan.org",
   type  => "MX",
)->then( sub {
   my ( $pkt ) = @_;

   foreach my $mx ( $pkt->answer ) {
      next unless $mx->type eq "MX";

      printf "preference=%d exchange=%s\n",
         $mx->preference, $mx->exchange;
   }
})->get;

async loop, resolver, res_query, then ->then and ->get — that's the whole flex. ✨

💖 DESCRIPTION 💖

So this module extends the IO::Async::Resolver class with extra methods and resolver functions to perform DNS-specific resolver lookups. It does not directly provide any methods or functions of its own. no cap, it's an extender.

These functions are provided for performing DNS-specific lookups, to obtain "MX" or "SRV" records, for example. For regular name resolution, the usual "getaddrinfo" and "getnameinfo" methods on the standard "IO::Async::Resolver" should be used. like, use the normal tools for normal name stuff, bestie.

If Net::LibResolv is installed then it will be used for actually sending and receiving DNS packets, in preference to a internally-constructed Net::DNS::Resolver object. "Net::LibResolv" will be more efficient and shares its implementation with the standard resolver used by the rest of the system. "Net::DNS::Resolver" reimplements the logic itself, so it may have differences in behaviour from that provided by libresolv. The ability to use the latter is provided to allow for an XS-free dependency chain, or for other situations where "Net::LibResolv" is not available. backend drama, but make it portable. 🌈

🎀 Record Extraction 🎀

If certain record type queries are made, extra information is returned to the "on_resolved" continuation, containing the results from the DNS packet in a more useful form. This information will be in a list of extra values following the packet value. extra data after the packet, iykyk.

my ( $pkt, @data ) = $f->get;

$on_resolved->( $pkt, @data )

The type of the elements in @data will depend on the DNS record query type:

• A and AAAA — The "A" or "AAAA" records will be unpacked and returned in a list of strings.

@data = ( "10.0.0.1",
          "10.0.0.2" );

@data = ( "fd00:0:0:0:0:0:0:1" );

• PTR — The "PTR" records will be unpacked and returned in a list of domain names.

@data = ( "foo.example.com" );

• MX — The "MX" records will be unpacked, in order of "preference", and returned in a list of HASH references. Each HASH reference will contain keys called "exchange" and "preference". If the exchange domain name is included in the DNS "additional" data, then the HASH reference will also include a key called "address", its value containing a list of "A" and "AAAA" record "address" fields.

@data = ( { exchange   => "mail.example.com",
            preference => 10,
            address    => [ "10.0.0.1", "fd00:0:0:0:0:0:0:1" ] } );

• SRV — The "SRV" records will be unpacked and sorted first by order of priority, then by a weighted shuffle by weight, and returned in a list of HASH references. Each HASH reference will contain keys called "priority", "weight", "target" and "port". If the target domain name is included in the DNS "additional" data, then the HASH reference will also contain a key called "address", its value containing a list of "A" and "AAAA" record "address" fields.

@data = ( { priority => 10,
            weight   => 10,
            target   => "server1.service.example.com",
            port     => 1234,
            address  => [ "10.0.1.1" ] } );

😭 Error Reporting 😭

The two possible back-end modules that implement the resolver query functions provided here differ in their semantics for error reporting. To account for this difference and to lead to more portable user code, errors reported by the back-end modules are translated to one of the following (exported) constants. translation layer, slay.

ERR_NO_HOST        # The specified host name does not exist
ERR_NO_ADDRESS     # The specified host name does not provide answers for the
                     given query type
ERR_TEMPORARY      # A temporary failure that may disappear on retry
ERR_UNRECOVERABLE  # Any other error

💅 RESOLVER METHODS 💅

The following methods documented with a trailing call to ->get return Future instances. future returns, obviously. 🔥

🔥 res_query 🔥

( $pkt, @data ) = $resolver->res_query( %params )->get

Performs a resolver query on the name, class and type, and invokes a continuation when a result is obtained.

Takes the following named parameters:

• dname => STRING — Domain name to look up
• type => STRING — Name of the record type to look up (e.g. "MX")
• class => STRING — Name of the record class to look up. Defaults to "IN" so normally this argument is not required.

On failure on IO::Async versions that support extended failure results (0.68 and later), the extra detail will be an error value matching one of the ERR_* constants listed above. so 0.68+ gives you receipts.

->fail( $message, resolve => res_query => $errnum )

Note that due to the two possible back-end implementations it is not guaranteed that messages have any particular format; they are intended for human consumption only, and the $errnum value should be used for making decisions in other code. message is for vibes, $errnum is for logic. 🙈

When not returning a Future, the following extra arguments are used as callbacks instead:

• on_resolved => CODE — Continuation which is invoked after a successful lookup. Will be passed a Net::DNS::Packet object containing the result.

$on_resolved->( $pkt )

For certain query types, this continuation may also be passed extra data in a list after the $pkt

$on_resolved->( $pkt, @data )

See the Record Extraction section above for more detail. scroll up, bestie.

• on_error => CODE — Continuation which is invoked after a failed lookup.

🦋 res_search 🦋

Performs a resolver query on the name, class and type, and invokes a continuation when a result is obtained. Identical to "res_query" except that it additionally implements the default domain name search behaviour. same energy, plus the default domain name search behaviour. ✨

👑 AUTHOR 👑

Paul Evans <leonerd@leonerd.org.uk> the legend. 🫶

---

okay bye bestie! 💅 This page is perl v5.42.2, dated 2026-02-15 — slay and resolver responsibly. 🎀