...
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", "google.com: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		"errors"
    83		"io"
    84		"os"
    85		"syscall"
    86		"time"
    87	)
    88	
    89	// netGo and netCgo contain the state of the build tags used
    90	// to build this binary, and whether cgo is available.
    91	// conf.go mirrors these into conf for easier testing.
    92	var (
    93		netGo  bool // set true in cgo_stub.go for build tag "netgo" (or no cgo)
    94		netCgo bool // set true in conf_netcgo.go for build tag "netcgo"
    95	)
    96	
    97	func init() {
    98		sysInit()
    99		supportsIPv4 = probeIPv4Stack()
   100		supportsIPv6, supportsIPv4map = probeIPv6Stack()
   101	}
   102	
   103	// Addr represents a network end point address.
   104	type Addr interface {
   105		Network() string // name of the network
   106		String() string  // string form of address
   107	}
   108	
   109	// Conn is a generic stream-oriented network connection.
   110	//
   111	// Multiple goroutines may invoke methods on a Conn simultaneously.
   112	type Conn interface {
   113		// Read reads data from the connection.
   114		// Read can be made to time out and return a Error with Timeout() == true
   115		// after a fixed time limit; see SetDeadline and SetReadDeadline.
   116		Read(b []byte) (n int, err error)
   117	
   118		// Write writes data to the connection.
   119		// Write can be made to time out and return a Error with Timeout() == true
   120		// after a fixed time limit; see SetDeadline and SetWriteDeadline.
   121		Write(b []byte) (n int, err error)
   122	
   123		// Close closes the connection.
   124		// Any blocked Read or Write operations will be unblocked and return errors.
   125		Close() error
   126	
   127		// LocalAddr returns the local network address.
   128		LocalAddr() Addr
   129	
   130		// RemoteAddr returns the remote network address.
   131		RemoteAddr() Addr
   132	
   133		// SetDeadline sets the read and write deadlines associated
   134		// with the connection. It is equivalent to calling both
   135		// SetReadDeadline and SetWriteDeadline.
   136		//
   137		// A deadline is an absolute time after which I/O operations
   138		// fail with a timeout (see type Error) instead of
   139		// blocking. The deadline applies to all future I/O, not just
   140		// the immediately following call to Read or Write.
   141		//
   142		// An idle timeout can be implemented by repeatedly extending
   143		// the deadline after successful Read or Write calls.
   144		//
   145		// A zero value for t means I/O operations will not time out.
   146		SetDeadline(t time.Time) error
   147	
   148		// SetReadDeadline sets the deadline for future Read calls.
   149		// A zero value for t means Read will not time out.
   150		SetReadDeadline(t time.Time) error
   151	
   152		// SetWriteDeadline sets the deadline for future Write calls.
   153		// Even if write times out, it may return n > 0, indicating that
   154		// some of the data was successfully written.
   155		// A zero value for t means Write will not time out.
   156		SetWriteDeadline(t time.Time) error
   157	}
   158	
   159	type conn struct {
   160		fd *netFD
   161	}
   162	
   163	func (c *conn) ok() bool { return c != nil && c.fd != nil }
   164	
   165	// Implementation of the Conn interface.
   166	
   167	// Read implements the Conn Read method.
   168	func (c *conn) Read(b []byte) (int, error) {
   169		if !c.ok() {
   170			return 0, syscall.EINVAL
   171		}
   172		n, err := c.fd.Read(b)
   173		if err != nil && err != io.EOF {
   174			err = &OpError{Op: "read", Net: c.fd.net, Source: c.fd.laddr, Addr: c.fd.raddr, Err: err}
   175		}
   176		return n, err
   177	}
   178	
   179	// Write implements the Conn Write method.
   180	func (c *conn) Write(b []byte) (int, error) {
   181		if !c.ok() {
   182			return 0, syscall.EINVAL
   183		}
   184		n, err := c.fd.Write(b)
   185		if err != nil {
   186			err = &OpError{Op: "write", Net: c.fd.net, Source: c.fd.laddr, Addr: c.fd.raddr, Err: err}
   187		}
   188		return n, err
   189	}
   190	
   191	// Close closes the connection.
   192	func (c *conn) Close() error {
   193		if !c.ok() {
   194			return syscall.EINVAL
   195		}
   196		err := c.fd.Close()
   197		if err != nil {
   198			err = &OpError{Op: "close", Net: c.fd.net, Source: c.fd.laddr, Addr: c.fd.raddr, Err: err}
   199		}
   200		return err
   201	}
   202	
   203	// LocalAddr returns the local network address.
   204	// The Addr returned is shared by all invocations of LocalAddr, so
   205	// do not modify it.
   206	func (c *conn) LocalAddr() Addr {
   207		if !c.ok() {
   208			return nil
   209		}
   210		return c.fd.laddr
   211	}
   212	
   213	// RemoteAddr returns the remote network address.
   214	// The Addr returned is shared by all invocations of RemoteAddr, so
   215	// do not modify it.
   216	func (c *conn) RemoteAddr() Addr {
   217		if !c.ok() {
   218			return nil
   219		}
   220		return c.fd.raddr
   221	}
   222	
   223	// SetDeadline implements the Conn SetDeadline method.
   224	func (c *conn) SetDeadline(t time.Time) error {
   225		if !c.ok() {
   226			return syscall.EINVAL
   227		}
   228		if err := c.fd.setDeadline(t); err != nil {
   229			return &OpError{Op: "set", Net: c.fd.net, Source: nil, Addr: c.fd.laddr, Err: err}
   230		}
   231		return nil
   232	}
   233	
   234	// SetReadDeadline implements the Conn SetReadDeadline method.
   235	func (c *conn) SetReadDeadline(t time.Time) error {
   236		if !c.ok() {
   237			return syscall.EINVAL
   238		}
   239		if err := c.fd.setReadDeadline(t); err != nil {
   240			return &OpError{Op: "set", Net: c.fd.net, Source: nil, Addr: c.fd.laddr, Err: err}
   241		}
   242		return nil
   243	}
   244	
   245	// SetWriteDeadline implements the Conn SetWriteDeadline method.
   246	func (c *conn) SetWriteDeadline(t time.Time) error {
   247		if !c.ok() {
   248			return syscall.EINVAL
   249		}
   250		if err := c.fd.setWriteDeadline(t); err != nil {
   251			return &OpError{Op: "set", Net: c.fd.net, Source: nil, Addr: c.fd.laddr, Err: err}
   252		}
   253		return nil
   254	}
   255	
   256	// SetReadBuffer sets the size of the operating system's
   257	// receive buffer associated with the connection.
   258	func (c *conn) SetReadBuffer(bytes int) error {
   259		if !c.ok() {
   260			return syscall.EINVAL
   261		}
   262		if err := setReadBuffer(c.fd, bytes); err != nil {
   263			return &OpError{Op: "set", Net: c.fd.net, Source: nil, Addr: c.fd.laddr, Err: err}
   264		}
   265		return nil
   266	}
   267	
   268	// SetWriteBuffer sets the size of the operating system's
   269	// transmit buffer associated with the connection.
   270	func (c *conn) SetWriteBuffer(bytes int) error {
   271		if !c.ok() {
   272			return syscall.EINVAL
   273		}
   274		if err := setWriteBuffer(c.fd, bytes); err != nil {
   275			return &OpError{Op: "set", Net: c.fd.net, Source: nil, Addr: c.fd.laddr, Err: err}
   276		}
   277		return nil
   278	}
   279	
   280	// File sets the underlying os.File to blocking mode and returns a copy.
   281	// It is the caller's responsibility to close f when finished.
   282	// Closing c does not affect f, and closing f does not affect c.
   283	//
   284	// The returned os.File's file descriptor is different from the connection's.
   285	// Attempting to change properties of the original using this duplicate
   286	// may or may not have the desired effect.
   287	func (c *conn) File() (f *os.File, err error) {
   288		f, err = c.fd.dup()
   289		if err != nil {
   290			err = &OpError{Op: "file", Net: c.fd.net, Source: c.fd.laddr, Addr: c.fd.raddr, Err: err}
   291		}
   292		return
   293	}
   294	
   295	// PacketConn is a generic packet-oriented network connection.
   296	//
   297	// Multiple goroutines may invoke methods on a PacketConn simultaneously.
   298	type PacketConn interface {
   299		// ReadFrom reads a packet from the connection,
   300		// copying the payload into b.  It returns the number of
   301		// bytes copied into b and the return address that
   302		// was on the packet.
   303		// ReadFrom can be made to time out and return
   304		// an error with Timeout() == true after a fixed time limit;
   305		// see SetDeadline and SetReadDeadline.
   306		ReadFrom(b []byte) (n int, addr Addr, err error)
   307	
   308		// WriteTo writes a packet with payload b to addr.
   309		// WriteTo can be made to time out and return
   310		// an error with Timeout() == true after a fixed time limit;
   311		// see SetDeadline and SetWriteDeadline.
   312		// On packet-oriented connections, write timeouts are rare.
   313		WriteTo(b []byte, addr Addr) (n int, err error)
   314	
   315		// Close closes the connection.
   316		// Any blocked ReadFrom or WriteTo operations will be unblocked and return errors.
   317		Close() error
   318	
   319		// LocalAddr returns the local network address.
   320		LocalAddr() Addr
   321	
   322		// SetDeadline sets the read and write deadlines associated
   323		// with the connection.
   324		SetDeadline(t time.Time) error
   325	
   326		// SetReadDeadline sets the deadline for future Read calls.
   327		// If the deadline is reached, Read will fail with a timeout
   328		// (see type Error) instead of blocking.
   329		// A zero value for t means Read will not time out.
   330		SetReadDeadline(t time.Time) error
   331	
   332		// SetWriteDeadline sets the deadline for future Write calls.
   333		// If the deadline is reached, Write will fail with a timeout
   334		// (see type Error) instead of blocking.
   335		// A zero value for t means Write will not time out.
   336		// Even if write times out, it may return n > 0, indicating that
   337		// some of the data was successfully written.
   338		SetWriteDeadline(t time.Time) error
   339	}
   340	
   341	var listenerBacklog = maxListenerBacklog()
   342	
   343	// A Listener is a generic network listener for stream-oriented protocols.
   344	//
   345	// Multiple goroutines may invoke methods on a Listener simultaneously.
   346	type Listener interface {
   347		// Accept waits for and returns the next connection to the listener.
   348		Accept() (c Conn, err error)
   349	
   350		// Close closes the listener.
   351		// Any blocked Accept operations will be unblocked and return errors.
   352		Close() error
   353	
   354		// Addr returns the listener's network address.
   355		Addr() Addr
   356	}
   357	
   358	// An Error represents a network error.
   359	type Error interface {
   360		error
   361		Timeout() bool   // Is the error a timeout?
   362		Temporary() bool // Is the error temporary?
   363	}
   364	
   365	// Various errors contained in OpError.
   366	var (
   367		// For connection setup and write operations.
   368		errMissingAddress = errors.New("missing address")
   369	
   370		// For both read and write operations.
   371		errTimeout          error = &timeoutError{}
   372		errCanceled               = errors.New("operation was canceled")
   373		errClosing                = errors.New("use of closed network connection")
   374		ErrWriteToConnected       = errors.New("use of WriteTo with pre-connected connection")
   375	)
   376	
   377	// OpError is the error type usually returned by functions in the net
   378	// package. It describes the operation, network type, and address of
   379	// an error.
   380	type OpError struct {
   381		// Op is the operation which caused the error, such as
   382		// "read" or "write".
   383		Op string
   384	
   385		// Net is the network type on which this error occurred,
   386		// such as "tcp" or "udp6".
   387		Net string
   388	
   389		// For operations involving a remote network connection, like
   390		// Dial, Read, or Write, Source is the corresponding local
   391		// network address.
   392		Source Addr
   393	
   394		// Addr is the network address for which this error occurred.
   395		// For local operations, like Listen or SetDeadline, Addr is
   396		// the address of the local endpoint being manipulated.
   397		// For operations involving a remote network connection, like
   398		// Dial, Read, or Write, Addr is the remote address of that
   399		// connection.
   400		Addr Addr
   401	
   402		// Err is the error that occurred during the operation.
   403		Err error
   404	}
   405	
   406	func (e *OpError) Error() string {
   407		if e == nil {
   408			return "<nil>"
   409		}
   410		s := e.Op
   411		if e.Net != "" {
   412			s += " " + e.Net
   413		}
   414		if e.Source != nil {
   415			s += " " + e.Source.String()
   416		}
   417		if e.Addr != nil {
   418			if e.Source != nil {
   419				s += "->"
   420			} else {
   421				s += " "
   422			}
   423			s += e.Addr.String()
   424		}
   425		s += ": " + e.Err.Error()
   426		return s
   427	}
   428	
   429	var noDeadline = time.Time{}
   430	
   431	type timeout interface {
   432		Timeout() bool
   433	}
   434	
   435	func (e *OpError) Timeout() bool {
   436		if ne, ok := e.Err.(*os.SyscallError); ok {
   437			t, ok := ne.Err.(timeout)
   438			return ok && t.Timeout()
   439		}
   440		t, ok := e.Err.(timeout)
   441		return ok && t.Timeout()
   442	}
   443	
   444	type temporary interface {
   445		Temporary() bool
   446	}
   447	
   448	func (e *OpError) Temporary() bool {
   449		if ne, ok := e.Err.(*os.SyscallError); ok {
   450			t, ok := ne.Err.(temporary)
   451			return ok && t.Temporary()
   452		}
   453		t, ok := e.Err.(temporary)
   454		return ok && t.Temporary()
   455	}
   456	
   457	type timeoutError struct{}
   458	
   459	func (e *timeoutError) Error() string   { return "i/o timeout" }
   460	func (e *timeoutError) Timeout() bool   { return true }
   461	func (e *timeoutError) Temporary() bool { return true }
   462	
   463	// A ParseError is the error type of literal network address parsers.
   464	type ParseError struct {
   465		// Type is the type of string that was expected, such as
   466		// "IP address", "CIDR address".
   467		Type string
   468	
   469		// Text is the malformed text string.
   470		Text string
   471	}
   472	
   473	func (e *ParseError) Error() string { return "invalid " + e.Type + ": " + e.Text }
   474	
   475	type AddrError struct {
   476		Err  string
   477		Addr string
   478	}
   479	
   480	func (e *AddrError) Error() string {
   481		if e == nil {
   482			return "<nil>"
   483		}
   484		s := e.Err
   485		if e.Addr != "" {
   486			s += " " + e.Addr
   487		}
   488		return s
   489	}
   490	
   491	func (e *AddrError) Timeout() bool   { return false }
   492	func (e *AddrError) Temporary() bool { return false }
   493	
   494	type UnknownNetworkError string
   495	
   496	func (e UnknownNetworkError) Error() string   { return "unknown network " + string(e) }
   497	func (e UnknownNetworkError) Timeout() bool   { return false }
   498	func (e UnknownNetworkError) Temporary() bool { return false }
   499	
   500	type InvalidAddrError string
   501	
   502	func (e InvalidAddrError) Error() string   { return string(e) }
   503	func (e InvalidAddrError) Timeout() bool   { return false }
   504	func (e InvalidAddrError) Temporary() bool { return false }
   505	
   506	// DNSConfigError represents an error reading the machine's DNS configuration.
   507	// (No longer used; kept for compatibility.)
   508	type DNSConfigError struct {
   509		Err error
   510	}
   511	
   512	func (e *DNSConfigError) Error() string   { return "error reading DNS config: " + e.Err.Error() }
   513	func (e *DNSConfigError) Timeout() bool   { return false }
   514	func (e *DNSConfigError) Temporary() bool { return false }
   515	
   516	// Various errors contained in DNSError.
   517	var (
   518		errNoSuchHost = errors.New("no such host")
   519	)
   520	
   521	// DNSError represents a DNS lookup error.
   522	type DNSError struct {
   523		Err       string // description of the error
   524		Name      string // name looked for
   525		Server    string // server used
   526		IsTimeout bool   // if true, timed out; not all timeouts set this
   527	}
   528	
   529	func (e *DNSError) Error() string {
   530		if e == nil {
   531			return "<nil>"
   532		}
   533		s := "lookup " + e.Name
   534		if e.Server != "" {
   535			s += " on " + e.Server
   536		}
   537		s += ": " + e.Err
   538		return s
   539	}
   540	
   541	// Timeout reports whether the DNS lookup is known to have timed out.
   542	// This is not always known; a DNS lookup may fail due to a timeout
   543	// and return a DNSError for which Timeout returns false.
   544	func (e *DNSError) Timeout() bool { return e.IsTimeout }
   545	
   546	// Temporary reports whether the DNS error is known to be temporary.
   547	// This is not always known; a DNS lookup may fail due to a temporary
   548	// error and return a DNSError for which Temporary returns false.
   549	func (e *DNSError) Temporary() bool { return e.IsTimeout }
   550	
   551	type writerOnly struct {
   552		io.Writer
   553	}
   554	
   555	// Fallback implementation of io.ReaderFrom's ReadFrom, when sendfile isn't
   556	// applicable.
   557	func genericReadFrom(w io.Writer, r io.Reader) (n int64, err error) {
   558		// Use wrapper to hide existing r.ReadFrom from io.Copy.
   559		return io.Copy(writerOnly{w}, r)
   560	}
   561	
   562	// Limit the number of concurrent cgo-using goroutines, because
   563	// each will block an entire operating system thread. The usual culprit
   564	// is resolving many DNS names in separate goroutines but the DNS
   565	// server is not responding. Then the many lookups each use a different
   566	// thread, and the system or the program runs out of threads.
   567	
   568	var threadLimit = make(chan struct{}, 500)
   569	
   570	func acquireThread() {
   571		threadLimit <- struct{}{}
   572	}
   573	
   574	func releaseThread() {
   575		<-threadLimit
   576	}
   577	

View as plain text