5.24.1 dns_query

Built-in Function: number dns_query (number type, string domain; number sort, number resolve)

This function looks up the domain name name. The type argument specifies type of the query to perform. On success, the function returns DNS reply descriptor, a non-negative integer number identifying the reply. It can then be passed to any of the ‘dns_reply_’ functions discussed below in order to retrieve the information from it.

If no matching records were found, the function returns ‘-1’.

On error, it throws a corresponding exception.

The type argument is one of the following constants (defined in the module ‘dns’):

DNS_TYPE_A

Query the ‘A’ record. The domain should be the hostname to look up.

DNS_TYPE_NS

Query the ‘NS’ records.

DNS_TYPE_PTR

Query the ‘PTR’ record. The domain address should be the IP address in dotted-quad form.

DNS_TYPE_MX

Query the ‘MX’ records.

DNS_TYPE_TXT

Query the ‘TXT’ records.

If the query returns multiple RR sets, the optional argument sort controls whether they should be returned in the same order as obtained from the DNS (0, the default), or should be sorted (1).

Optional argument resolve is consulted if type is DNS_TYPE_MX or DNS_TYPE_NS. By default, queries for these types return hostnames. The resolve argument controls whether to return IP addresses instead. Its possible values (defined in module status.mfl are:

RESOLVE_NONE

Don’t resolve hostnames to IP addresses. This is the default.

RESOLVE_DFL

Resolve hostnames to IP addresses according to the address family of the SMTP session. That is, use ‘A’ records if the client connected using the INET family (i.e. connected to the IPv4 address), and use ‘AAAA’ records if the client connected to the IPv6 address.

RESOLVE_IP4

Resolve hostnames to IPv4 addresses (‘A’ records).

RESOLVE_IP6

Resolve hostnames to IPv6 addresses (‘AAAA’ records).

To extract actual data from the dns_query return value, use the functions dns_reply_count and dns_reply_string. The usual processing sequence is:

  require dns

  # Send the query and save the reply descriptor
  set n dns_query(DNS_TYPE_NS, domain_name)

  if n >= 0
    # If non-empty set is returned, iterate over each value in it:
    loop for set i 0,
         while i < dns_reply_count(n),
         set i i + 1
    do
      # Get the actual data:
      echo dns_reply_string(n, i)
    done
    # Release the memory associated with the reply.
    dns_reply_release(n)
  fi

Built-in Function: void dns_reply_release (number rd)

Release the memory associated with the reply rd. If rd is -1, the function does nothing.

Built-in Function: number dns_reply_count (number rd)

Return the number of records in the reply rd. For convenience, if rd is -1, the function returns 0. If rd is negative (excepting -1), a ‘e_failure’ exception is thrown.

Built-in Function: string dns_reply_string (number rd, number n)

Returns nth record from the DNS reply rd.

Built-in Function: number dns_reply_ip (number rd, number n)

Returns nth record from the DNS reply rd, if the reply contains IPv4 addresses.