Package net provides a portable interface for network I/O, including TCP/IP, UDP, domain name resolution, and Unix domain sockets.

Although the package provides access to low-level networking primitives, most clients will need only the basic interface provided by the [Dial], [Listen], and Accept functions and the associated [Conn] and [Listener] interfaces. The crypto/tls package uses the same interfaces and similar Dial and Listen functions.

The Dial function connects to a server:

 conn, err := net.Dial("tcp", "golang.org:80")
 if err != nil {
   // handle error
 }
 fmt.Fprintf(conn, "GET / HTTP/1.0\r\n\r\n")
 status, err := bufio.NewReader(conn).ReadString('\n')
 // ...
Copy

The Listen function creates servers:

 ln, err := net.Listen("tcp", ":8080")
 if err != nil {
   // handle error
 }
 for {
   conn, err := ln.Accept()
   if err != nil {
     // handle error
   }
   go handleConnection(conn)
 }
Copy

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.

On Unix the pure Go resolver is preferred over the cgo resolver, 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.

On all systems (except Plan 9), when the cgo resolver is being used this package applies a concurrent cgo lookup limit to prevent the system from running out of system threads. Currently, it is limited to 500 concurrent lookups.

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 native resolver (cgo, win32)
Copy

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.

The Go resolver will send an EDNS0 additional header with a DNS request, to signal a willingness to accept a larger DNS packet size. This can reportedly cause sporadic failures with the DNS server run by some modems and routers. Setting GODEBUG=netedns0=0 will disable sending the additional header.

On macOS, if Go code that uses the net package is built with -buildmode=c-archive, linking the resulting archive into a C program requires passing -lresolv when linking the C code.

On Plan 9, the resolver always accesses /net/cs and /net/dns.

On Windows, in Go 1.18.x and earlier, the resolver always used C library functions, such as GetAddrInfo and DnsQuery.