...
Run Format

Source file src/net/net.go

     1	// Copyright 2009 The Go Authors. All rights reserved.
     2	// Use of this source code is governed by a BSD-style
     3	// license that can be found in the LICENSE file.
     4	
     5	/*
     6	Package net provides a portable interface for network I/O, including
     7	TCP/IP, UDP, domain name resolution, and Unix domain sockets.
     8	
     9	Although the package provides access to low-level networking
    10	primitives, most clients will need only the basic interface provided
    11	by the Dial, Listen, and Accept functions and the associated
    12	Conn and Listener interfaces. The crypto/tls package uses
    13	the same interfaces and similar Dial and Listen functions.
    14	
    15	The Dial function connects to a server:
    16	
    17		conn, err := net.Dial("tcp", "golang.org:80")
    18		if err != nil {
    19			// handle error
    20		}
    21		fmt.Fprintf(conn, "GET / HTTP/1.0\r\n\r\n")
    22		status, err := bufio.NewReader(conn).ReadString('\n')
    23		// ...
    24	
    25	The Listen function creates servers:
    26	
    27		ln, err := net.Listen("tcp", ":8080")
    28		if err != nil {
    29			// handle error
    30		}
    31		for {
    32			conn, err := ln.Accept()
    33			if err != nil {
    34				// handle error
    35			}
    36			go handleConnection(conn)
    37		}
    38	
    39	Name Resolution
    40	
    41	The method for resolving domain names, whether indirectly with functions like Dial
    42	or directly with functions like LookupHost and LookupAddr, varies by operating system.
    43	
    44	On Unix systems, the resolver has two options for resolving names.
    45	It can use a pure Go resolver that sends DNS requests directly to the servers
    46	listed in /etc/resolv.conf, or it can use a cgo-based resolver that calls C
    47	library routines such as getaddrinfo and getnameinfo.
    48	
    49	By default the pure Go resolver is used, because a blocked DNS request consumes
    50	only a goroutine, while a blocked C call consumes an operating system thread.
    51	When cgo is available, the cgo-based resolver is used instead under a variety of
    52	conditions: on systems that do not let programs make direct DNS requests (OS X),
    53	when the LOCALDOMAIN environment variable is present (even if empty),
    54	when the RES_OPTIONS or HOSTALIASES environment variable is non-empty,
    55	when the ASR_CONFIG environment variable is non-empty (OpenBSD only),
    56	when /etc/resolv.conf or /etc/nsswitch.conf specify the use of features that the
    57	Go resolver does not implement, and when the name being looked up ends in .local
    58	or is an mDNS name.
    59	
    60	The resolver decision can be overridden by setting the netdns value of the
    61	GODEBUG environment variable (see package runtime) to go or cgo, as in:
    62	
    63		export GODEBUG=netdns=go    # force pure Go resolver
    64		export GODEBUG=netdns=cgo   # force cgo resolver
    65	
    66	The decision can also be forced while building the Go source tree
    67	by setting the netgo or netcgo build tag.
    68	
    69	A numeric netdns setting, as in GODEBUG=netdns=1, causes the resolver
    70	to print debugging information about its decisions.
    71	To force a particular resolver while also printing debugging information,
    72	join the two settings by a plus sign, as in GODEBUG=netdns=go+1.
    73	
    74	On Plan 9, the resolver always accesses /net/cs and /net/dns.
    75	
    76	On Windows, the resolver always uses C library functions, such as GetAddrInfo and DnsQuery.
    77	
    78	*/
    79	package net
    80	
    81	import (
    82		"context"
    83		"errors"
    84		"io"
    85		"os"
    86		"syscall"
    87		"time"
    88	)
    89	
    90	// netGo and netCgo contain the state of the build tags used
    91	// to build this binary, and whether cgo is available.
    92	// conf.go mirrors these into conf for easier testing.
    93	var (
    94		netGo  bool // set true in cgo_stub.go for build tag "netgo" (or no cgo)
    95		netCgo bool // set true in conf_netcgo.go for build tag "netcgo"
    96	)
    97	
    98	func init() {
    99		sysInit()
   100		supportsIPv4 = probeIPv4Stack()
   101		supportsIPv6, supportsIPv4map = probeIPv6Stack()
   102	}
   103	
   104	// Addr represents a network end point address.
   105	type Addr interface {
   106		Network() string // name of the network
   107		String() string  // string form of address
   108	}
   109	
   110	// Conn is a generic stream-oriented network connection.
   111	//
   112	// Multiple goroutines may invoke methods on a Conn simultaneously.
   113	type Conn interface {
   114		// Read reads data from the connection.
   115		// Read can be made to time out and return a Error with Timeout() == true
   116		// after a fixed time limit; see SetDeadline and SetReadDeadline.
   117		Read(b []byte) (n int, err error)
   118	
   119		// Write writes data to the connection.
   120		// Write can be made to time out and return a Error with Timeout() == true
   121		// after a fixed time limit; see SetDeadline and SetWriteDeadline.
   122		Write(b []byte) (n int, err error)
   123	
   124		// Close closes the connection.
   125		// Any blocked Read or Write operations will be unblocked and return errors.
   126		Close() error
   127	
   128		// LocalAddr returns the local network address.
   129		LocalAddr() Addr
   130	
   131		// RemoteAddr returns the remote network address.
   132		RemoteAddr() Addr
   133	
   134		// SetDeadline sets the read and write deadlines associated
   135		// with the connection. It is equivalent to calling both
   136		// SetReadDeadline and SetWriteDeadline.
   137		//
   138		// A deadline is an absolute time after which I/O operations
   139		// fail with a timeout (see type Error) instead of
   140		// blocking. The deadline applies to all future I/O, not just
   141		// the immediately following call to Read or Write.
   142		//
   143		// An idle timeout can be implemented by repeatedly extending
   144		// the deadline after successful Read or Write calls.
   145		//
   146		// A zero value for t means I/O operations will not time out.
   147		SetDeadline(t time.Time) error
   148	
   149		// SetReadDeadline sets the deadline for future Read calls.
   150		// A zero value for t means Read will not time out.
   151		SetReadDeadline(t time.Time) error
   152	
   153		// SetWriteDeadline sets the deadline for future Write calls.
   154		// Even if write times out, it may return n > 0, indicating that
   155		// some of the data was successfully written.
   156		// A zero value for t means Write will not time out.
   157		SetWriteDeadline(t time.Time) error
   158	}
   159	
   160	type conn struct {
   161		fd *netFD
   162	}
   163	
   164	func (c *conn) ok() bool { return c != nil && c.fd != nil }
   165	
   166	// Implementation of the Conn interface.
   167	
   168	// Read implements the Conn Read method.
   169	func (c *conn) Read(b []byte) (int, error) {
   170		if !c.ok() {
   171			return 0, syscall.EINVAL
   172		}
   173		n, err := c.fd.Read(b)
   174		if err != nil && err != io.EOF {
   175			err = &OpError{Op: "read", Net: c.fd.net, Source: c.fd.laddr, Addr: c.fd.raddr, Err: err}
   176		}
   177		return n, err
   178	}
   179	
   180	// Write implements the Conn Write method.
   181	func (c *conn) Write(b []byte) (int, error) {
   182		if !c.ok() {
   183			return 0, syscall.EINVAL
   184		}
   185		n, err := c.fd.Write(b)
   186		if err != nil {
   187			err = &OpError{Op: "write", Net: c.fd.net, Source: c.fd.laddr, Addr: c.fd.raddr, Err: err}
   188		}
   189		return n, err
   190	}
   191	
   192	// Close closes the connection.
   193	func (c *conn) Close() error {
   194		if !c.ok() {
   195			return syscall.EINVAL
   196		}
   197		err := c.fd.Close()
   198		if err != nil {
   199			err = &OpError{Op: "close", Net: c.fd.net, Source: c.fd.laddr, Addr: c.fd.raddr, Err: err}
   200		}
   201		return err
   202	}
   203	
   204	// LocalAddr returns the local network address.
   205	// The Addr returned is shared by all invocations of LocalAddr, so
   206	// do not modify it.
   207	func (c *conn) LocalAddr() Addr {
   208		if !c.ok() {
   209			return nil
   210		}
   211		return c.fd.laddr
   212	}
   213	
   214	// RemoteAddr returns the remote network address.
   215	// The Addr returned is shared by all invocations of RemoteAddr, so
   216	// do not modify it.
   217	func (c *conn) RemoteAddr() Addr {
   218		if !c.ok() {
   219			return nil
   220		}
   221		return c.fd.raddr
   222	}
   223	
   224	// SetDeadline implements the Conn SetDeadline method.
   225	func (c *conn) SetDeadline(t time.Time) error {
   226		if !c.ok() {
   227			return syscall.EINVAL
   228		}
   229		if err := c.fd.setDeadline(t); err != nil {
   230			return &OpError{Op: "set", Net: c.fd.net, Source: nil, Addr: c.fd.laddr, Err: err}
   231		}
   232		return nil
   233	}
   234	
   235	// SetReadDeadline implements the Conn SetReadDeadline method.
   236	func (c *conn) SetReadDeadline(t time.Time) error {
   237		if !c.ok() {
   238			return syscall.EINVAL
   239		}
   240		if err := c.fd.setReadDeadline(t); err != nil {
   241			return &OpError{Op: "set", Net: c.fd.net, Source: nil, Addr: c.fd.laddr, Err: err}
   242		}
   243		return nil
   244	}
   245	
   246	// SetWriteDeadline implements the Conn SetWriteDeadline method.
   247	func (c *conn) SetWriteDeadline(t time.Time) error {
   248		if !c.ok() {
   249			return syscall.EINVAL
   250		}
   251		if err := c.fd.setWriteDeadline(t); err != nil {
   252			return &OpError{Op: "set", Net: c.fd.net, Source: nil, Addr: c.fd.laddr, Err: err}
   253		}
   254		return nil
   255	}
   256	
   257	// SetReadBuffer sets the size of the operating system's
   258	// receive buffer associated with the connection.
   259	func (c *conn) SetReadBuffer(bytes int) error {
   260		if !c.ok() {
   261			return syscall.EINVAL
   262		}
   263		if err := setReadBuffer(c.fd, bytes); err != nil {
   264			return &OpError{Op: "set", Net: c.fd.net, Source: nil, Addr: c.fd.laddr, Err: err}
   265		}
   266		return nil
   267	}
   268	
   269	// SetWriteBuffer sets the size of the operating system's
   270	// transmit buffer associated with the connection.
   271	func (c *conn) SetWriteBuffer(bytes int) error {
   272		if !c.ok() {
   273			return syscall.EINVAL
   274		}
   275		if err := setWriteBuffer(c.fd, bytes); err != nil {
   276			return &OpError{Op: "set", Net: c.fd.net, Source: nil, Addr: c.fd.laddr, Err: err}
   277		}
   278		return nil
   279	}
   280	
   281	// File sets the underlying os.File to blocking mode and returns a copy.
   282	// It is the caller's responsibility to close f when finished.
   283	// Closing c does not affect f, and closing f does not affect c.
   284	//
   285	// The returned os.File's file descriptor is different from the connection's.
   286	// Attempting to change properties of the original using this duplicate
   287	// may or may not have the desired effect.
   288	func (c *conn) File() (f *os.File, err error) {
   289		f, err = c.fd.dup()
   290		if err != nil {
   291			err = &OpError{Op: "file", Net: c.fd.net, Source: c.fd.laddr, Addr: c.fd.raddr, Err: err}
   292		}
   293		return
   294	}
   295	
   296	// PacketConn is a generic packet-oriented network connection.
   297	//
   298	// Multiple goroutines may invoke methods on a PacketConn simultaneously.
   299	type PacketConn interface {
   300		// ReadFrom reads a packet from the connection,
   301		// copying the payload into b. It returns the number of
   302		// bytes copied into b and the return address that
   303		// was on the packet.
   304		// ReadFrom can be made to time out and return
   305		// an error with Timeout() == true after a fixed time limit;
   306		// see SetDeadline and SetReadDeadline.
   307		ReadFrom(b []byte) (n int, addr Addr, err error)
   308	
   309		// WriteTo writes a packet with payload b to addr.
   310		// WriteTo can be made to time out and return
   311		// an error with Timeout() == true after a fixed time limit;
   312		// see SetDeadline and SetWriteDeadline.
   313		// On packet-oriented connections, write timeouts are rare.
   314		WriteTo(b []byte, addr Addr) (n int, err error)
   315	
   316		// Close closes the connection.
   317		// Any blocked ReadFrom or WriteTo operations will be unblocked and return errors.
   318		Close() error
   319	
   320		// LocalAddr returns the local network address.
   321		LocalAddr() Addr
   322	
   323		// SetDeadline sets the read and write deadlines associated
   324		// with the connection.
   325		SetDeadline(t time.Time) error
   326	
   327		// SetReadDeadline sets the deadline for future Read calls.
   328		// If the deadline is reached, Read will fail with a timeout
   329		// (see type Error) instead of blocking.
   330		// A zero value for t means Read will not time out.
   331		SetReadDeadline(t time.Time) error
   332	
   333		// SetWriteDeadline sets the deadline for future Write calls.
   334		// If the deadline is reached, Write will fail with a timeout
   335		// (see type Error) instead of blocking.
   336		// A zero value for t means Write will not time out.
   337		// Even if write times out, it may return n > 0, indicating that
   338		// some of the data was successfully written.
   339		SetWriteDeadline(t time.Time) error
   340	}
   341	
   342	var listenerBacklog = maxListenerBacklog()
   343	
   344	// A Listener is a generic network listener for stream-oriented protocols.
   345	//
   346	// Multiple goroutines may invoke methods on a Listener simultaneously.
   347	type Listener interface {
   348		// Accept waits for and returns the next connection to the listener.
   349		Accept() (Conn, error)
   350	
   351		// Close closes the listener.
   352		// Any blocked Accept operations will be unblocked and return errors.
   353		Close() error
   354	
   355		// Addr returns the listener's network address.
   356		Addr() Addr
   357	}
   358	
   359	// An Error represents a network error.
   360	type Error interface {
   361		error
   362		Timeout() bool   // Is the error a timeout?
   363		Temporary() bool // Is the error temporary?
   364	}
   365	
   366	// Various errors contained in OpError.
   367	var (
   368		// For connection setup operations.
   369		errNoSuitableAddress = errors.New("no suitable address found")
   370	
   371		// For connection setup and write operations.
   372		errMissingAddress = errors.New("missing address")
   373	
   374		// For both read and write operations.
   375		errTimeout          error = &timeoutError{}
   376		errCanceled               = errors.New("operation was canceled")
   377		errClosing                = errors.New("use of closed network connection")
   378		ErrWriteToConnected       = errors.New("use of WriteTo with pre-connected connection")
   379	)
   380	
   381	// mapErr maps from the context errors to the historical internal net
   382	// error values.
   383	//
   384	// TODO(bradfitz): get rid of this after adjusting tests and making
   385	// context.DeadlineExceeded implement net.Error?
   386	func mapErr(err error) error {
   387		switch err {
   388		case context.Canceled:
   389			return errCanceled
   390		case context.DeadlineExceeded:
   391			return errTimeout
   392		default:
   393			return err
   394		}
   395	}
   396	
   397	// OpError is the error type usually returned by functions in the net
   398	// package. It describes the operation, network type, and address of
   399	// an error.
   400	type OpError struct {
   401		// Op is the operation which caused the error, such as
   402		// "read" or "write".
   403		Op string
   404	
   405		// Net is the network type on which this error occurred,
   406		// such as "tcp" or "udp6".
   407		Net string
   408	
   409		// For operations involving a remote network connection, like
   410		// Dial, Read, or Write, Source is the corresponding local
   411		// network address.
   412		Source Addr
   413	
   414		// Addr is the network address for which this error occurred.
   415		// For local operations, like Listen or SetDeadline, Addr is
   416		// the address of the local endpoint being manipulated.
   417		// For operations involving a remote network connection, like
   418		// Dial, Read, or Write, Addr is the remote address of that
   419		// connection.
   420		Addr Addr
   421	
   422		// Err is the error that occurred during the operation.
   423		Err error
   424	}
   425	
   426	func (e *OpError) Error() string {
   427		if e == nil {
   428			return "<nil>"
   429		}
   430		s := e.Op
   431		if e.Net != "" {
   432			s += " " + e.Net
   433		}
   434		if e.Source != nil {
   435			s += " " + e.Source.String()
   436		}
   437		if e.Addr != nil {
   438			if e.Source != nil {
   439				s += "->"
   440			} else {
   441				s += " "
   442			}
   443			s += e.Addr.String()
   444		}
   445		s += ": " + e.Err.Error()
   446		return s
   447	}
   448	
   449	var (
   450		// aLongTimeAgo is a non-zero time, far in the past, used for
   451		// immediate cancelation of dials.
   452		aLongTimeAgo = time.Unix(233431200, 0)
   453	
   454		// nonDeadline and noCancel are just zero values for
   455		// readability with functions taking too many parameters.
   456		noDeadline = time.Time{}
   457		noCancel   = (chan struct{})(nil)
   458	)
   459	
   460	type timeout interface {
   461		Timeout() bool
   462	}
   463	
   464	func (e *OpError) Timeout() bool {
   465		if ne, ok := e.Err.(*os.SyscallError); ok {
   466			t, ok := ne.Err.(timeout)
   467			return ok && t.Timeout()
   468		}
   469		t, ok := e.Err.(timeout)
   470		return ok && t.Timeout()
   471	}
   472	
   473	type temporary interface {
   474		Temporary() bool
   475	}
   476	
   477	func (e *OpError) Temporary() bool {
   478		if ne, ok := e.Err.(*os.SyscallError); ok {
   479			t, ok := ne.Err.(temporary)
   480			return ok && t.Temporary()
   481		}
   482		t, ok := e.Err.(temporary)
   483		return ok && t.Temporary()
   484	}
   485	
   486	type timeoutError struct{}
   487	
   488	func (e *timeoutError) Error() string   { return "i/o timeout" }
   489	func (e *timeoutError) Timeout() bool   { return true }
   490	func (e *timeoutError) Temporary() bool { return true }
   491	
   492	// A ParseError is the error type of literal network address parsers.
   493	type ParseError struct {
   494		// Type is the type of string that was expected, such as
   495		// "IP address", "CIDR address".
   496		Type string
   497	
   498		// Text is the malformed text string.
   499		Text string
   500	}
   501	
   502	func (e *ParseError) Error() string { return "invalid " + e.Type + ": " + e.Text }
   503	
   504	type AddrError struct {
   505		Err  string
   506		Addr string
   507	}
   508	
   509	func (e *AddrError) Error() string {
   510		if e == nil {
   511			return "<nil>"
   512		}
   513		s := e.Err
   514		if e.Addr != "" {
   515			s += " " + e.Addr
   516		}
   517		return s
   518	}
   519	
   520	func (e *AddrError) Timeout() bool   { return false }
   521	func (e *AddrError) Temporary() bool { return false }
   522	
   523	type UnknownNetworkError string
   524	
   525	func (e UnknownNetworkError) Error() string   { return "unknown network " + string(e) }
   526	func (e UnknownNetworkError) Timeout() bool   { return false }
   527	func (e UnknownNetworkError) Temporary() bool { return false }
   528	
   529	type InvalidAddrError string
   530	
   531	func (e InvalidAddrError) Error() string   { return string(e) }
   532	func (e InvalidAddrError) Timeout() bool   { return false }
   533	func (e InvalidAddrError) Temporary() bool { return false }
   534	
   535	// DNSConfigError represents an error reading the machine's DNS configuration.
   536	// (No longer used; kept for compatibility.)
   537	type DNSConfigError struct {
   538		Err error
   539	}
   540	
   541	func (e *DNSConfigError) Error() string   { return "error reading DNS config: " + e.Err.Error() }
   542	func (e *DNSConfigError) Timeout() bool   { return false }
   543	func (e *DNSConfigError) Temporary() bool { return false }
   544	
   545	// Various errors contained in DNSError.
   546	var (
   547		errNoSuchHost = errors.New("no such host")
   548	)
   549	
   550	// DNSError represents a DNS lookup error.
   551	type DNSError struct {
   552		Err         string // description of the error
   553		Name        string // name looked for
   554		Server      string // server used
   555		IsTimeout   bool   // if true, timed out; not all timeouts set this
   556		IsTemporary bool   // if true, error is temporary; not all errors set this
   557	}
   558	
   559	func (e *DNSError) Error() string {
   560		if e == nil {
   561			return "<nil>"
   562		}
   563		s := "lookup " + e.Name
   564		if e.Server != "" {
   565			s += " on " + e.Server
   566		}
   567		s += ": " + e.Err
   568		return s
   569	}
   570	
   571	// Timeout reports whether the DNS lookup is known to have timed out.
   572	// This is not always known; a DNS lookup may fail due to a timeout
   573	// and return a DNSError for which Timeout returns false.
   574	func (e *DNSError) Timeout() bool { return e.IsTimeout }
   575	
   576	// Temporary reports whether the DNS error is known to be temporary.
   577	// This is not always known; a DNS lookup may fail due to a temporary
   578	// error and return a DNSError for which Temporary returns false.
   579	func (e *DNSError) Temporary() bool { return e.IsTimeout || e.IsTemporary }
   580	
   581	type writerOnly struct {
   582		io.Writer
   583	}
   584	
   585	// Fallback implementation of io.ReaderFrom's ReadFrom, when sendfile isn't
   586	// applicable.
   587	func genericReadFrom(w io.Writer, r io.Reader) (n int64, err error) {
   588		// Use wrapper to hide existing r.ReadFrom from io.Copy.
   589		return io.Copy(writerOnly{w}, r)
   590	}
   591	
   592	// Limit the number of concurrent cgo-using goroutines, because
   593	// each will block an entire operating system thread. The usual culprit
   594	// is resolving many DNS names in separate goroutines but the DNS
   595	// server is not responding. Then the many lookups each use a different
   596	// thread, and the system or the program runs out of threads.
   597	
   598	var threadLimit = make(chan struct{}, 500)
   599	
   600	func acquireThread() {
   601		threadLimit <- struct{}{}
   602	}
   603	
   604	func releaseThread() {
   605		<-threadLimit
   606	}
   607	

View as plain text