FunctionPackage: socketToCDocOverviewCGDocRelNotesFAQIndexPermutedIndex
Allegro CL version 10.1
Moderately revised from 10.0.
10.0 version


Arguments: name &key type nameserver repeat timeout queue decode search ignore-cache

The arguments are:

Name Default What
name Depending on the value of the type argument, this is either a string or an integer IP address.
type :a The type of dns query to make.
:a means determine the ip address(es) for the given name. (name should be a string.)
:ptr means determine the hostname for a given IP address. (name should be an integer IP address, a string containing a dotted IP address, or an IPv6 address.
:mx means determine if there is another machine that email for name should be directed. (name should be a string.)
:srv means get SRV records for a domain. name should be a string. See SRV queries in dns.htm.
:txt means get all TXT records associated with name. The answer is a list containing one or more strings (TXT records can be composed of multiple strings), or nil if there are no TXT records. If there is more than one TXT record, then the third return value will contain a list of the remaining answers.
:aaaa means look up IPv6 adresses.
:any means return all information about the first argument. decode should be specified nil (its default is t) when type is :any.
nameserver nil If specified this can be an IP address or a list of IP addresses. This overrides the configured list of nameservers for just this query.
repeat 5 How many times to try to get an answer to this query before giving up.
timeout 5 How long to wait until we assume that a try has failed and we then try again or give up. The value should be an integer indicating a number of seconds.
queue t If true then handle this request using the background process that is backed up by a cache of recent answers. If this is nil then a request will always be sent to the nameserver
decode t The nameserver returns a structure of many fields. If true then dns-query will examine the returned structures and will return only the information requested by the query. If this is nil then the result of dns-query will be the actual information returned by the nameserver. This response is a dns-response object. See that page for information on this raw object. Please specify nil when you specify :any as the value of type.
search nil When specified true, *dns-domain* and *domain-search-list* will be used to fully qualify the name argument before doing the query. See below for details on how the search is conducted.
ignore-cache nil Allegro CL DNS caches positive and negative responses for at least the time-to-live specified in the respones. If dns-query is called again with the same request before the time-to-live expires, the cached information will be returned immediately. If ignore-cache is true, then the cached value will be ignored and a DNS lookup will occur.

If either nameserver is non-nil or decode is nil, then queue will be set to nil regardless of the value of queue supplied. This ensures that a fresh query is sent to the nameserver.

Where an IP address is a valid argument, it can be specified as either an integer or as a string such as "" or "127.1". Ipv6 address structures and IPv6 colon hex strings are allowed too.

Search details

When the search keyword argument is specified true, and so *dns-domain* and *domain-search-list* are used to fully qualify the name argument before doing the query, the search steps are as follows:

  1. The search list comprises *dns-domain* followed by *domain-search-list*. If the given name ends in a period (e.g. then that is an absolute name. Only that name is checked and the search list is not used.
  2. If the given name has a period in it, but that period is not at the end (e.g. then that name is checked first.
  3. Finally for the given name N and for each name S in the search list a new name is constructed by concatenating the strings with a period in between (e.g N.S). That constructed name is used in the query. If the query returns a response with :no-such-domain then the next item in the search list is used.

Thus the first response from the search (with a positive or negative valid time, which is the second returned value) is returned as the first returned value, but illegal domains in the search list are ignored.

Return values

There are four return values from dns-query.

  1. the primary answer
  2. the amount of time that that answer is valid (in seconds) This can be a negative number (see the discussion in the The DNS API section of dns.htm for why).
  3. a list of other answers
  4. a list of the flags returned by the dns server that replied to the query

There are examples of using dns-query in the subsections of The DNS API in dns.htm.

See dns.htm for information on the domain naming system utility in Allegro CL and see socket.htm for general information on sockets in Allegro CL.

Copyright (c) 1998-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page has had moderate revisions compared to the 10.0 page.
Created 2019.8.20.

Allegro CL version 10.1
Moderately revised from 10.0.
10.0 version