1#lang scribble/doc
2@(require "common.rkt" scribble/eval (for-label net/dns net/dns-unit net/dns-sig))
3
4@(define dns-evaluator (make-base-eval))
5@(dns-evaluator '(require net/dns))
6
7@title[#:tag "dns"]{DNS: Domain Name Service Queries}
8
9@defmodule[net/dns]{The @racketmodname[net/dns] library provides
10utilities for looking up hostnames.
11
12Thanks to Eduardo Cavazos and Jason Crowe for repairs and
13improvements.}
14
15@; ----------------------------------------
16
17@section[#:tag "dns-proc"]{Functions}
18
19@defproc[(dns-get-address [nameserver string?]
20                          [address string?]
21                          [#:ipv6? ipv6? any/c #f])
22         string?]{
23
24Consults the specified nameserver (normally a numerical address like
25@racket["128.42.1.30"]) to obtain a numerical address for the given
26Internet address.
27
28The query record sent to the DNS server includes the "recursive" bit,
29but @racket[dns-get-address] also implements a recursive search itself
30in case the server does not provide this optional feature.
31
32If @racket[ipv6?] is a true value, then the numerical address
33that is returned will be an IPv6 address. If no AAAA record exists,
34an error will be raised.
35}
36
37
38@deftogether[(
39@defproc[(dns-get-srv [nameserver string?]
40		      [name string?]
41		      [service string?]
42		      [proto string? "tcp"])
43         (listof srv-rr?)]
44@defstruct*[srv-rr ([priority (integer-in 0 65535)]
45		    [weight (integer-in 0 65535)]
46		    [port (integer-in 0 65535)]
47		    [target string?]) #:prefab]
48)]{
49
50@margin-note{An SRV record is a particular kind of DNS resource record
51that maps an abstract service name onto a hostname and port
52combination. For more information, see
53@hyperlink["https://en.wikipedia.org/wiki/SRV_record"]{the Wikipedia
54page on SRV records}.}
55
56Consults the specified nameserver (normally a numerical address like
57@racket["128.42.1.30"]) to retrieve the SRV records corresponding to
58the given name, service, and protocol. Returns a list of
59@racket[srv-rr] structs if any corresponding SRV records are found;
60otherwise, returns @racket['()].
61
62If @racket[service] is @racket["X"], @racket[proto] is @racket["Y"],
63and @racket[name] is @racket["example.com"], then this will retrieve
64any SRV records at the domain name @tt{_X._Y.example.com}.
65
66The query record sent to the DNS server includes the "recursive" bit,
67but @racket[dns-get-srv] also implements a recursive search itself
68in case the server does not provide this optional feature.
69
70@examples[#:eval dns-evaluator
71	  (eval:alts (dns-get-srv (dns-find-nameserver) "racket-lang.org" "xmpp-client")
72		     (list (srv-rr 0 0 5222 "xmpp.racket-lang.org")))
73	  (eval:alts (dns-get-srv (dns-find-nameserver) "racket-lang.org" "nonexistent-protocol")
74		     (list))
75	  (eval:alts (dns-get-srv (dns-find-nameserver) "racket-lang.org" "xmpp-client" "tcp")
76		     (list (srv-rr 0 0 5222 "xmpp.racket-lang.org")))
77	  (eval:alts (dns-get-srv (dns-find-nameserver) "racket-lang.org" "xmpp-client" "udp")
78		     (list))
79	  ]
80
81@history[#:added "6.4.0.8"]
82}
83
84
85@defproc[(dns-get-name [nameserver string?]
86                       [address string?])
87         string?]{
88
89Consults the specified nameserver (normally a numerical address like
90@racket["128.42.1.30"]) to obtain a name for the given numerical
91address.}
92
93
94@defproc[(dns-get-mail-exchanger [nameserver string?]
95                                 [address string?])
96         string?]{
97
98Consults the specified nameserver to obtain the address for a mail
99exchanger the given mail host address. For example, the mail exchanger
100for @racket["ollie.cs.rice.edu"] might be @racket["cs.rice.edu"].}
101
102
103
104@defproc[(dns-find-nameserver) (or/c string? false/c)]{
105
106Attempts to find the address of a nameserver on the present system.
107On Unix and Mac OS, this procedure parses @filepath{/etc/resolv.conf} to
108extract the first nameserver address. On Windows, it runs
109@exec{nslookup.exe}.}
110
111@; ----------------------------------------
112
113@section{DNS Unit}
114
115@margin-note{@racket[dns@] and @racket[dns^] are deprecated.
116They exist for backward-compatibility and will likely be removed in
117the future. New code should use the @racketmodname[net/dns] module.}
118
119@defmodule[net/dns-unit]
120
121@defthing[dns@ unit?]{
122
123Imports nothing, exports @racket[dns^].}
124
125@; ----------------------------------------
126
127@section{DNS Signature}
128
129@defmodule[net/dns-sig]
130
131@defsignature[dns^ ()]{}
132
133Includes @racket[dns-get-address], @racket[dns-get-name],
134@racket[dns-get-mail-exchanger] and @racket[dns-find-nameserver].
135