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