net::dns +linux +x86_64

net::dns implements low-level DNS message encoding and decoding, as well as a porcelain DNS resolver.




type a;
type aaaa;
type class;
type header;
type message;
type mx;
type op;
type opcode;
type qclass;
type qr;
type qtype;
type question;
type rcode;
type rdata;
type rrecord;
type rtype;
type txt;
type unknown_rdata;


type error;
type format;
type name_error;
type not_implemented;
type refused;
type server_failure;
type unknown_error;


fn decode([]u8) (*message | format);
fn encode([]u8, *message) (size | error);
fn message_free(*message) void;
fn parse_domain(str) []str;
fn query(*message, ip::addr...) (*message | error);
fn unparse_domain([]str) str;

// Undocumented functions:
fn strerror(error) const str;


type a[link]

type a = ip::addr4;

An A record.

type aaaa[link]

type aaaa = ip::addr6;

An AAAA record.

type class[link]

type class = enum u16 {
	IN = 1,
	CS = 2,
	CH = 3,
	HS = 4,


Class type (e.g. Internet).

type header = struct {
	id: u16,
	op: op,
	// Number of questions
qdcount: u16, // Number of answers
ancount: u16, // Number of name servers
nscount: u16, // Number of additional resources
arcount: u16, };

DNS message header.

type message[link]

type message = struct {
	header: header,
	questions: []question,
	answers: []rrecord,
	authority: []rrecord,
	additional: []rrecord,

A DNS message, Hare representation. See encode and decode for the DNS representation.

type mx[link]

type mx = struct {
	priority: u16,
	name: []str,

An MX record.

type op[link]

type op = struct {
	// Is this a query or a response?
qr: qr, // Operation code
opcode: opcode, // Authoritative answer bit
aa: bool, // Truncation bit
tc: bool, // Recursion desired bit
rd: bool, // Recursion available bit
ra: bool, // Response code
rcode: rcode, };

Operational information for this message.

type opcode[link]

type opcode = enum u8 {
	QUERY = 0,
	IQUERY = 1,
	STATUS = 2,


Operation requested from resolver.

type qclass[link]

type qclass = enum u16 {
	IN = 1,
	CS = 2,
	CH = 3,
	HS = 4,
	ANY = 255, // *

Query class (superset of class).

type qr[link]

type qr = enum u8 {
	QUERY = 0,


Bit indicating if a header precedes a query or response.

type qtype[link]

type qtype = enum u16 {
	A = 1,
	NS = 2,
	CNAME = 5,
	SOA = 6,
	PTR = 12,
	MX = 15,
	TXT = 16,
	AAAA = 28,
	SRV = 33,
	DNSKEY = 48,
	AXFR = 252, // ...
ALL = 255, // *

Question type (superset of rtype).

type question[link]

type question = struct {
	qname: []str,
	qtype: qtype,
	qclass: qclass,

A question section item.

type rcode[link]

type rcode = enum u8 {
	NO_ERROR = 0,


Response code from resolver.

type rdata[link]

type rdata = (a | aaaa | mx | txt | unknown_rdata);

Tagged union of supported rdata types.

type rrecord[link]

type rrecord = struct {
	name: []str,
	rtype: rtype,
	class: class,
	ttl: u32,
	rdata: rdata,

A resource record item.

type rtype[link]

type rtype = enum u16 {
	A = 1,
	NS = 2,
	CNAME = 5,
	SOA = 6,
	PTR = 12,
	MX = 15,
	TXT = 16,
	AAAA = 28,
	SRV = 33,
	DNSKEY = 48,


Record type.

type txt[link]

type txt = [][]u8;

A TXT record.

type unknown_rdata[link]

type unknown_rdata = []u8;

The raw rdata field for an rrecord with an unknown rtype.


type error[link]

type error = !(format | server_failure | name_error | not_implemented | refused |
unknown_error | errors::overflow | errors::timeout | net::error);

All error types which might be returned from net::dns functions.

type format[link]

type format = !void;

The DNS message was poorly formatted.

type name_error[link]

type name_error = !void;

The domain name referenced in the query does not exist. Meaningful only for responses from an authoritative name server.

type not_implemented[link]

type not_implemented = !void;

The name server does not support the requested kind of query.

type refused[link]

type refused = !void;

The name server refuses to perform the specified operation for policy reasons.

type server_failure[link]

type server_failure = !void;

The name server was unable to process this query due to a problem with the name server.

type unknown_error[link]

type unknown_error = !u8;

Any other server-provided error condition not known to Hare.


fn decode[link]

fn decode(buf: []u8) (*message | format);

Decodes a DNS message, heap allocating the resources necessary to represent it in Hare's type system. The caller must use message_free to free the return value. To decode without use of the heap, see decoder_init.

fn encode[link]

fn encode(buf: []u8, msg: *message) (size | error);

Encodes a DNS message, returning its size, or an error.

fn message_free[link]

fn message_free(msg: *message) void;

Frees a message and the resources associated with it.

fn parse_domain[link]

fn parse_domain(in: str) []str;

Converts a human-readable domain name (e.g. "") into a DNS-ready name slice (e.g. ["example", "org"]). The slice returned must be freed by the caller, but the members of the slice themselves are borrowed from the input.

fn query[link]

fn query(query: *message, servers: ip::addr...) (*message | error);

Performs a DNS query using the provided list of DNS servers. The caller must free the return value with message_free.

If no DNS servers are provided, the system default servers (if any) are used.

fn unparse_domain[link]

fn unparse_domain(in: []str) str;

Converts a DNS name slice (e.g. ["example", "org"]) into a human-readable domain name (e.g. ""). The return value must be freed by the caller.

fn strerror[link]

Show undocumented member
fn strerror(err: error) const str;