From b711f5ad8f945a6c8e823cb1e7fc65eafdb3a3e4 Mon Sep 17 00:00:00 2001 From: Russ Cox Date: Tue, 18 Aug 2015 23:19:41 -0400 Subject: [PATCH] net: document GODEBUG=netdns=xxx settings Fixes #12191. Change-Id: I5c7659ccb0566dad3613041d9e76be87ceacae61 Reviewed-on: https://go-review.googlesource.com/13700 Reviewed-by: Rob Pike --- src/net/net.go | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/src/net/net.go b/src/net/net.go index 75510a2223..6e84c3a100 100644 --- a/src/net/net.go +++ b/src/net/net.go @@ -35,6 +35,46 @@ The Listen function creates servers: } go handleConnection(conn) } + +Name Resolution + +The method for resolving domain names, whether indirectly with functions like Dial +or directly with functions like LookupHost and LookupAddr, varies by operating system. + +On Unix systems, the resolver has two options for resolving names. +It can use a pure Go resolver that sends DNS requests directly to the servers +listed in /etc/resolv.conf, or it can use a cgo-based resolver that calls C +library routines such as getaddrinfo and getnameinfo. + +By default the pure Go resolver is used, because a blocked DNS request consumes +only a goroutine, while a blocked C call consumes an operating system thread. +When cgo is available, the cgo-based resolver is used instead under a variety of +conditions: on systems that do not let programs make direct DNS requests (OS X), +when the LOCALDOMAIN environment variable is present (even if empty), +when the RES_OPTIONS or HOSTALIASES environment variable is non-empty, +when the ASR_CONFIG environment variable is non-empty (OpenBSD only), +when /etc/resolv.conf or /etc/nsswitch.conf specify the use of features that the +Go resolver does not implement, and when the name being looked up ends in .local +or is an mDNS name. + +The resolver decision can be overridden by setting the netdns value of the +GODEBUG environment variable (see package runtime) to go or cgo, as in: + + export GODEBUG=netdns=go # force pure Go resolver + export GODEBUG=netdns=cgo # force cgo resolver + +The decision can also be forced while building the Go source tree +by setting the netgo or netcgo build tag. + +A numeric netdns setting, as in GODEBUG=netdns=1, causes the resolver +to print debugging information about its decisions. +To force a particular resolver while also printing debugging information, +join the two settings by a plus sign, as in GODEBUG=netdns=go+1. + +On Plan 9, the resolver always accesses /net/cs and /net/dns. + +On Windows, the resolver always uses C library functions, such as GetAddrInfo and DnsQuery. + */ package net