710320e3dc
Although "macOS" is the correct name for Apple's current desktop OS, we've decided to go with "Mac OS" to cover all of Apple's Unix-like desktop OS versions. The label "Mac OS" is more readable, clear in context (i.e., unlikely to be confused with the Mac OSes that proceeded Mac OS X), and as likely to match Apple's future OS names as anything.
135 lines
4.4 KiB
Racket
135 lines
4.4 KiB
Racket
#lang scribble/doc
|
|
@(require "common.rkt" scribble/eval (for-label net/dns net/dns-unit net/dns-sig))
|
|
|
|
@(define dns-evaluator (make-base-eval))
|
|
@(dns-evaluator '(require net/dns))
|
|
|
|
@title[#:tag "dns"]{DNS: Domain Name Service Queries}
|
|
|
|
@defmodule[net/dns]{The @racketmodname[net/dns] library provides
|
|
utilities for looking up hostnames.
|
|
|
|
Thanks to Eduardo Cavazos and Jason Crowe for repairs and
|
|
improvements.}
|
|
|
|
@; ----------------------------------------
|
|
|
|
@section[#:tag "dns-proc"]{Functions}
|
|
|
|
@defproc[(dns-get-address [nameserver string?]
|
|
[address string?]
|
|
[#:ipv6? ipv6? any/c #f])
|
|
string?]{
|
|
|
|
Consults the specified nameserver (normally a numerical address like
|
|
@racket["128.42.1.30"]) to obtain a numerical address for the given
|
|
Internet address.
|
|
|
|
The query record sent to the DNS server includes the "recursive" bit,
|
|
but @racket[dns-get-address] also implements a recursive search itself
|
|
in case the server does not provide this optional feature.
|
|
|
|
If @racket[ipv6?] is a true value, then the numerical address
|
|
that is returned will be an IPv6 address. If no AAAA record exists,
|
|
an error will be raised.
|
|
}
|
|
|
|
|
|
@deftogether[(
|
|
@defproc[(dns-get-srv [nameserver string?]
|
|
[name string?]
|
|
[service string?]
|
|
[proto string? "tcp"])
|
|
(listof srv-rr?)]
|
|
@defstruct*[srv-rr ([priority (integer-in 0 65535)]
|
|
[weight (integer-in 0 65535)]
|
|
[port (integer-in 0 65535)]
|
|
[target string?]) #:prefab]
|
|
)]{
|
|
|
|
@margin-note{An SRV record is a particular kind of DNS resource record
|
|
that maps an abstract service name onto a hostname and port
|
|
combination. For more information, see
|
|
@hyperlink["https://en.wikipedia.org/wiki/SRV_record"]{the Wikipedia
|
|
page on SRV records}.}
|
|
|
|
Consults the specified nameserver (normally a numerical address like
|
|
@racket["128.42.1.30"]) to retrieve the SRV records corresponding to
|
|
the given name, service, and protocol. Returns a list of
|
|
@racket[srv-rr] structs if any corresponding SRV records are found;
|
|
otherwise, returns @racket['()].
|
|
|
|
If @racket[service] is @racket["X"], @racket[proto] is @racket["Y"],
|
|
and @racket[name] is @racket["example.com"], then this will retrieve
|
|
any SRV records at the domain name @tt{_X._Y.example.com}.
|
|
|
|
The query record sent to the DNS server includes the "recursive" bit,
|
|
but @racket[dns-get-srv] also implements a recursive search itself
|
|
in case the server does not provide this optional feature.
|
|
|
|
@examples[#:eval dns-evaluator
|
|
(eval:alts (dns-get-srv (dns-find-nameserver) "racket-lang.org" "xmpp-client")
|
|
(list (srv-rr 0 0 5222 "xmpp.racket-lang.org")))
|
|
(eval:alts (dns-get-srv (dns-find-nameserver) "racket-lang.org" "nonexistent-protocol")
|
|
(list))
|
|
(eval:alts (dns-get-srv (dns-find-nameserver) "racket-lang.org" "xmpp-client" "tcp")
|
|
(list (srv-rr 0 0 5222 "xmpp.racket-lang.org")))
|
|
(eval:alts (dns-get-srv (dns-find-nameserver) "racket-lang.org" "xmpp-client" "udp")
|
|
(list))
|
|
]
|
|
|
|
@history[#:added "6.4.0.8"]
|
|
}
|
|
|
|
|
|
@defproc[(dns-get-name [nameserver string?]
|
|
[address string?])
|
|
string?]{
|
|
|
|
Consults the specified nameserver (normally a numerical address like
|
|
@racket["128.42.1.30"]) to obtain a name for the given numerical
|
|
address.}
|
|
|
|
|
|
@defproc[(dns-get-mail-exchanger [nameserver string?]
|
|
[address string?])
|
|
string?]{
|
|
|
|
Consults the specified nameserver to obtain the address for a mail
|
|
exchanger the given mail host address. For example, the mail exchanger
|
|
for @racket["ollie.cs.rice.edu"] might be @racket["cs.rice.edu"].}
|
|
|
|
|
|
|
|
@defproc[(dns-find-nameserver) (or/c string? false/c)]{
|
|
|
|
Attempts to find the address of a nameserver on the present system.
|
|
On Unix and Mac OS, this procedure parses @filepath{/etc/resolv.conf} to
|
|
extract the first nameserver address. On Windows, it runs
|
|
@exec{nslookup.exe}.}
|
|
|
|
@; ----------------------------------------
|
|
|
|
@section{DNS Unit}
|
|
|
|
@margin-note{@racket[dns@] and @racket[dns^] are deprecated.
|
|
They exist for backward-compatibility and will likely be removed in
|
|
the future. New code should use the @racketmodname[net/dns] module.}
|
|
|
|
@defmodule[net/dns-unit]
|
|
|
|
@defthing[dns@ unit?]{
|
|
|
|
Imports nothing, exports @racket[dns^].}
|
|
|
|
@; ----------------------------------------
|
|
|
|
@section{DNS Signature}
|
|
|
|
@defmodule[net/dns-sig]
|
|
|
|
@defsignature[dns^ ()]{}
|
|
|
|
Includes @racket[dns-get-address], @racket[dns-get-name],
|
|
@racket[dns-get-mail-exchanger] and @racket[dns-find-nameserver].
|