The dns-client Reference Manual

This is the dns-client Reference Manual, version 1.0.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Wed May 15 05:06:58 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 dns-client

A client for the DNS protocol.

Maintainer

Yukari Hafner <>

Author

Yukari Hafner <>

Home Page

https://shinmera.github.io/dns-client/

Source Control

(GIT https://github.com/shinmera/dns-client.git)

Bug Tracker

https://github.com/shinmera/dns-client/issues

License

zlib

Version

1.0.0

Dependencies
  • usocket (system).
  • punycode (system).
  • documentation-utils (system).
Source

dns-client.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


3.1 Lisp


3.1.1 dns-client/dns-client.asd

Source

dns-client.asd.

Parent Component

dns-client (system).

ASDF Systems

dns-client.


3.1.2 dns-client/package.lisp

Source

dns-client.asd.

Parent Component

dns-client (system).

Packages

org.shirakumo.dns-client.


3.1.3 dns-client/toolkit.lisp

Dependency

package.lisp (file).

Source

dns-client.asd.

Parent Component

dns-client (system).

Public Interface
Internals

3.1.4 dns-client/record-types.lisp

Dependency

toolkit.lisp (file).

Source

dns-client.asd.

Parent Component

dns-client (system).

Public Interface

3.1.5 dns-client/client.lisp

Dependency

record-types.lisp (file).

Source

dns-client.asd.

Parent Component

dns-client (system).

Public Interface
Internals

3.1.6 dns-client/documentation.lisp

Dependency

client.lisp (file).

Source

dns-client.asd.

Parent Component

dns-client (system).


4 Packages

Packages are listed by definition order.


4.1 org.shirakumo.dns-client

Source

package.lisp.

Use List

common-lisp.

Public Interface
Internals

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


5.1 Public Interface


5.1.1 Constants

Constant: dns-port

The port used for DNS queries.

Should be 53.

Package

org.shirakumo.dns-client.

Source

client.lisp.

Constant: recv-buffer-length

The buffer size for received DNS packets.

Defaults to 65507, which should be more than enough for all DNS queries. Note that while the standard DNS packet size used to (and still is in some devices) limited to 512 bytes, this restriction no longer applies generally.

Package

org.shirakumo.dns-client.

Source

client.lisp.


5.1.2 Special variables

Special Variable: *cloudflare-servers*

List of IP addresses to CloudFlare’s DNS servers.

Package

org.shirakumo.dns-client.

Source

client.lisp.

Special Variable: *dns-servers*

List of IP addresses to query for DNS records.

By default this is a combination of the localhost address and a bunch of other publicly available DNS servers, in rough order of trustworthiness and speed.

You may bind or modify this variable to suit your preferences.

See *CLOUDFLARE-SERVERS*
See *DNSWATCH-SERVERS*
See *GOOGLE-SERVERS*
See *OPENDNS-SERVERS*
See *QUAD9-SERVERS*
See QUERY

Package

org.shirakumo.dns-client.

Source

client.lisp.

Special Variable: *dnswatch-servers*

List of IP addresses to DNSWatch’s DNS servers.

Package

org.shirakumo.dns-client.

Source

client.lisp.

Special Variable: *google-servers*

List of IP addresses to Google’s DNS servers.

Package

org.shirakumo.dns-client.

Source

client.lisp.

Special Variable: *opendns-servers*

List of IP addresses to OpenDNS’ DNS servers.

Package

org.shirakumo.dns-client.

Source

client.lisp.

Special Variable: *quad9-servers*

List of IP addresses to Quad9’s DNS servers.

Package

org.shirakumo.dns-client.

Source

client.lisp.

Special Variable: *record-type-table*

Table associating standardised names to DNS record type IDs.

This is a list where each entry should be a list of two elements, the standardised name as a symbol, and the (unsigned-byte 16) ID.

You should not need to modify this. The table contains all standardised records types.

See RECORD-TYPE-ID
See ID-RECORD-TYPE

Package

org.shirakumo.dns-client.

Source

record-types.lisp.


5.1.3 Macros

Macro: with-dns-error-handling (&body body)

Wraps a handler around BODY that performs useful defaults.

In particular, it will cause CONTINUE to be invoked on all error responses that are a failure on the server side, but still let the error propagate for all failures that indicate a bad query.

See DNS-SERVER-FAILURE

Package

org.shirakumo.dns-client.

Source

toolkit.lisp.


5.1.4 Ordinary functions

Function: hostname (ip &rest args &key type dns-servers attempts timeout)

Perform a reverse DNS query.

Returns three values, the first hostname that was found (if any), a list of all hostnames that were found, and whether the query was successful. If the last value is NIL, the first two values are NIL as well.

See QUERY

Package

org.shirakumo.dns-client.

Source

client.lisp.

Function: id-record-type (id)

Returns the standardised record name for the given record type ID.

If the record type ID is not known, the ID itself is returned instead.

See *RECORD-TYPE-TABLE*

Package

org.shirakumo.dns-client.

Source

record-types.lisp.

Function: query (hostname &key type dns-servers attempts timeout)

Perform a DNS query for the given hostname.

TYPE should be a DNS class name or class ID that identifies the type of record you want to retrieve.

DNS-SERVERS should be a list of DNS servers to consult for your query. Each server in the list is asked ATTEMPTS number of times before skipping ahead to the next one.

Returns a PLIST of the resulting query, if successful.

The result contains the following keys:

:QUESTIONS — A list of QUERY structures.
:ANSWERS — A list of RECORD structures.
:AUTHORITIES — A list of RECORD structures.
:ADDITIONAL — A list of RECORD structures.
:ID — The ID identifying the query. :RECURSION-DESIRED — Whether recursion was asked for. :TRUNCATED-MESSAGE — Whether the message was truncated. :OPERATION — The operation that was carried out.
:REPLY-P — Whether this is a reply.
:RESPONSE-CODE — The response status code. :CHECKING-DISABLED — Whether checking was disabled. :AUTHENTICATED-DATA — Whether the data is authorative. :Z-RESERVED — Reserved flag.
:RECURSION-AVAILABLE — Whether the server allows recursion. :QUESTION-COUNT — How many QUESTION records there are. :ANSWER-COUNT — How many ANSWER records there are. :AUTHORITY-COUNT — How many AUTHORITY records there are. :ADDITIONAL-COUNT — How many ADDITIONAL records there are.

A query structure is a plist with the following keys:

:NAME — The hostname that was queried.
:TYPE — The record type that was queried.
:CLASS — The record class that was queried.

A record structure is a plist with the following keys:

:NAME — The hostname the result relates to.
:TYPE — The record type.
:CLASS — The record class.
:TTL — The time this record remains valid for, in minutes.
:LENGTH — The length of the payload in octets.
:DATA — A record type specific data payload.

The client will translate record types from their octet data into a more easily digestible format for some record types:

:A — An IPv4 address in string format.
:AAAA — An IPv6 address in string format.
:TXT :URI :CNAME :PTR
— A hostname.
:MX — A plist with the following keys:
:PRIORITY
:NAME
:SOA — A plist with the following keys:
:MNAME
:RNAME
:SERIAL
:REFRESH
:RETRY
:EXPIRE
:MINIMUM

If a server is queried and has sent a response, but the response contains a non-zero response code, a condition of type DNS-SERVER-FAILURE is signalled. During this time, the CONTINUE restart can be used to skip the server and attempt the next one,
or the ABORT restart can be used to simply return NIL from QUERY.

If no server succeeds, an error of type DNS-SERVERS-EXHAUSTED
is signalled.

See DNS-SERVER-FAILURE
See DNS-SERVERS-EXHAUSTED
See RESOLVE
See HOSTNAME

Package

org.shirakumo.dns-client.

Source

client.lisp.

Function: query-data (hostname &rest args &key type dns-servers attempts timeout)

Shorthand to return the data payloads from the answers of a query.

This returns a list of all :DATA fields of :ANSWERS records from the query result that match the requested record type.

See QUERY

Package

org.shirakumo.dns-client.

Source

client.lisp.

Function: record-type-id (record-type &optional error)

Returns the record type ID for the given record name.

If ERROR is non-NIL, and the given record type does not exist, an error is signalled. Otherwise, NIL is returned for inexistent record types.

See *RECORD-TYPE-TABLE*

Package

org.shirakumo.dns-client.

Source

record-types.lisp.

Function: resolve (hostname &rest args &key type dns-servers attempts timeout)

Resolves a hostname to its IP address.

This is a shorthand to fetch the A or AAAA records.

Returns three values, the first IP that was found (if any), a list of all IPs that were found, and whether the query was successful. If the last value is NIL, the first two values are NIL as well.

See QUERY

Package

org.shirakumo.dns-client.

Source

client.lisp.

Function: response-code-name (code)

Returns a name for the response code if one is known.

Package

org.shirakumo.dns-client.

Source

toolkit.lisp.


5.1.5 Generic functions

Generic Reader: dns-server (condition)

Returns the DNS server that returned the failure.

See DNS-SERVER-FAILURE

Package

org.shirakumo.dns-client.

Methods
Reader Method: dns-server ((condition dns-server-failure))
Source

toolkit.lisp.

Target Slot

dns-server.

Generic Reader: response-code (condition)

Returns the response code of the condition.

See DNS-SERVER-FAILURE
See RESPONSE-CODE-NAME

Package

org.shirakumo.dns-client.

Methods
Reader Method: response-code ((condition dns-server-failure))
Source

toolkit.lisp.

Target Slot

response-code.


5.1.6 Conditions

Condition: dns-condition

Base type for all DNS conditions.

Package

org.shirakumo.dns-client.

Source

toolkit.lisp.

Direct superclasses

condition.

Direct subclasses
Condition: dns-server-failure

Error signalled when a DNS server replies with a bad response code.

See DNS-CONDITION
See DNS-SERVER
See RESPONSE-CODE
See QUERY

Package

org.shirakumo.dns-client.

Source

toolkit.lisp.

Direct superclasses
Direct methods
Direct slots
Slot: dns-server
Initargs

:dns-server

Readers

dns-server.

Writers

This slot is read-only.

Slot: response-code
Initargs

:response-code

Readers

response-code.

Writers

This slot is read-only.

Condition: dns-servers-exhausted

Error signalled when all DNS servers fail to provide a response.

See DNS-CONDITION

Package

org.shirakumo.dns-client.

Source

toolkit.lisp.

Direct superclasses

5.2 Internals


5.2.1 Macros

Macro: maybe-set ((octets offset) &body calls)
Package

org.shirakumo.dns-client.

Source

toolkit.lisp.

Macro: with-decoding ((octets start &optional pos) &body body)
Package

org.shirakumo.dns-client.

Source

toolkit.lisp.

Macro: with-encoding ((octets start &optional pos) &body body)
Package

org.shirakumo.dns-client.

Source

toolkit.lisp.

Macro: with-query-buffer ((send pos hostname type &rest header-args) &body body)
Package

org.shirakumo.dns-client.

Source

client.lisp.


5.2.2 Ordinary functions

Function: decode-data (octets offset)
Package

org.shirakumo.dns-client.

Source

client.lisp.

Function: decode-header (octets offset)
Package

org.shirakumo.dns-client.

Source

client.lisp.

Function: decode-host (octets offset start)
Package

org.shirakumo.dns-client.

Source

client.lisp.

Function: decode-host* (string)
Package

org.shirakumo.dns-client.

Source

client.lisp.

Function: decode-query (octets offset)
Package

org.shirakumo.dns-client.

Source

client.lisp.

Function: decode-record (octets offset)
Package

org.shirakumo.dns-client.

Source

client.lisp.

Function: decode-response (server octets offset limit)
Package

org.shirakumo.dns-client.

Source

client.lisp.

Function: encode-header (octets offset &key id recursion-desired truncated-message authorative-answer operation reply-p response-code checking-disabled authenticated-data z-reserved recursion-available question-count answer-count authority-count additional-count)
Package

org.shirakumo.dns-client.

Source

client.lisp.

Function: encode-host (name octets offset)
Package

org.shirakumo.dns-client.

Source

client.lisp.

Function: encode-query (octets offset hostname &key type class)
Package

org.shirakumo.dns-client.

Source

client.lisp.

Function: split (on string)
Package

org.shirakumo.dns-client.

Source

toolkit.lisp.

Function: try-server (server send send-length recv recv-length &key attempts timeout)
Package

org.shirakumo.dns-client.

Source

client.lisp.


5.2.3 Generic functions

Generic Function: decode-record-payload (type octets start end)
Package

org.shirakumo.dns-client.

Source

client.lisp.

Methods
Method: decode-record-payload ((type (eql :soa)) octets start end)
Method: decode-record-payload ((type (eql :mx)) octets start end)
Method: decode-record-payload ((type (eql :ptr)) octets start end)
Method: decode-record-payload ((type (eql :cname)) octets start end)
Method: decode-record-payload ((type (eql :uri)) octets start end)
Method: decode-record-payload ((type (eql :txt)) octets start end)
Method: decode-record-payload ((type (eql :aaaa)) octets start end)
Method: decode-record-payload ((type (eql :a)) octets start end)
Method: decode-record-payload (type octets start end)

Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   D   E   F   G   H   I   M   Q   R   S   T   W  
Index Entry  Section

D
decode-data: Private ordinary functions
decode-header: Private ordinary functions
decode-host: Private ordinary functions
decode-host*: Private ordinary functions
decode-query: Private ordinary functions
decode-record: Private ordinary functions
decode-record-payload: Private generic functions
decode-record-payload: Private generic functions
decode-record-payload: Private generic functions
decode-record-payload: Private generic functions
decode-record-payload: Private generic functions
decode-record-payload: Private generic functions
decode-record-payload: Private generic functions
decode-record-payload: Private generic functions
decode-record-payload: Private generic functions
decode-record-payload: Private generic functions
decode-response: Private ordinary functions
dns-server: Public generic functions
dns-server: Public generic functions

E
encode-header: Private ordinary functions
encode-host: Private ordinary functions
encode-query: Private ordinary functions

F
Function, decode-data: Private ordinary functions
Function, decode-header: Private ordinary functions
Function, decode-host: Private ordinary functions
Function, decode-host*: Private ordinary functions
Function, decode-query: Private ordinary functions
Function, decode-record: Private ordinary functions
Function, decode-response: Private ordinary functions
Function, encode-header: Private ordinary functions
Function, encode-host: Private ordinary functions
Function, encode-query: Private ordinary functions
Function, hostname: Public ordinary functions
Function, id-record-type: Public ordinary functions
Function, query: Public ordinary functions
Function, query-data: Public ordinary functions
Function, record-type-id: Public ordinary functions
Function, resolve: Public ordinary functions
Function, response-code-name: Public ordinary functions
Function, split: Private ordinary functions
Function, try-server: Private ordinary functions

G
Generic Function, decode-record-payload: Private generic functions
Generic Function, dns-server: Public generic functions
Generic Function, response-code: Public generic functions

H
hostname: Public ordinary functions

I
id-record-type: Public ordinary functions

M
Macro, maybe-set: Private macros
Macro, with-decoding: Private macros
Macro, with-dns-error-handling: Public macros
Macro, with-encoding: Private macros
Macro, with-query-buffer: Private macros
maybe-set: Private macros
Method, decode-record-payload: Private generic functions
Method, decode-record-payload: Private generic functions
Method, decode-record-payload: Private generic functions
Method, decode-record-payload: Private generic functions
Method, decode-record-payload: Private generic functions
Method, decode-record-payload: Private generic functions
Method, decode-record-payload: Private generic functions
Method, decode-record-payload: Private generic functions
Method, decode-record-payload: Private generic functions
Method, dns-server: Public generic functions
Method, response-code: Public generic functions

Q
query: Public ordinary functions
query-data: Public ordinary functions

R
record-type-id: Public ordinary functions
resolve: Public ordinary functions
response-code: Public generic functions
response-code: Public generic functions
response-code-name: Public ordinary functions

S
split: Private ordinary functions

T
try-server: Private ordinary functions

W
with-decoding: Private macros
with-dns-error-handling: Public macros
with-encoding: Private macros
with-query-buffer: Private macros