Source file src/net/dial.go

Documentation: net

		 1  // Copyright 2010 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  package net
		 6  
		 7  import (
		 8  	"context"
		 9  	"internal/nettrace"
		10  	"syscall"
		11  	"time"
		12  )
		13  
		14  // defaultTCPKeepAlive is a default constant value for TCPKeepAlive times
		15  // See golang.org/issue/31510
		16  const (
		17  	defaultTCPKeepAlive = 15 * time.Second
		18  )
		19  
		20  // A Dialer contains options for connecting to an address.
		21  //
		22  // The zero value for each field is equivalent to dialing
		23  // without that option. Dialing with the zero value of Dialer
		24  // is therefore equivalent to just calling the Dial function.
		25  //
		26  // It is safe to call Dialer's methods concurrently.
		27  type Dialer struct {
		28  	// Timeout is the maximum amount of time a dial will wait for
		29  	// a connect to complete. If Deadline is also set, it may fail
		30  	// earlier.
		31  	//
		32  	// The default is no timeout.
		33  	//
		34  	// When using TCP and dialing a host name with multiple IP
		35  	// addresses, the timeout may be divided between them.
		36  	//
		37  	// With or without a timeout, the operating system may impose
		38  	// its own earlier timeout. For instance, TCP timeouts are
		39  	// often around 3 minutes.
		40  	Timeout time.Duration
		41  
		42  	// Deadline is the absolute point in time after which dials
		43  	// will fail. If Timeout is set, it may fail earlier.
		44  	// Zero means no deadline, or dependent on the operating system
		45  	// as with the Timeout option.
		46  	Deadline time.Time
		47  
		48  	// LocalAddr is the local address to use when dialing an
		49  	// address. The address must be of a compatible type for the
		50  	// network being dialed.
		51  	// If nil, a local address is automatically chosen.
		52  	LocalAddr Addr
		53  
		54  	// DualStack previously enabled RFC 6555 Fast Fallback
		55  	// support, also known as "Happy Eyeballs", in which IPv4 is
		56  	// tried soon if IPv6 appears to be misconfigured and
		57  	// hanging.
		58  	//
		59  	// Deprecated: Fast Fallback is enabled by default. To
		60  	// disable, set FallbackDelay to a negative value.
		61  	DualStack bool
		62  
		63  	// FallbackDelay specifies the length of time to wait before
		64  	// spawning a RFC 6555 Fast Fallback connection. That is, this
		65  	// is the amount of time to wait for IPv6 to succeed before
		66  	// assuming that IPv6 is misconfigured and falling back to
		67  	// IPv4.
		68  	//
		69  	// If zero, a default delay of 300ms is used.
		70  	// A negative value disables Fast Fallback support.
		71  	FallbackDelay time.Duration
		72  
		73  	// KeepAlive specifies the interval between keep-alive
		74  	// probes for an active network connection.
		75  	// If zero, keep-alive probes are sent with a default value
		76  	// (currently 15 seconds), if supported by the protocol and operating
		77  	// system. Network protocols or operating systems that do
		78  	// not support keep-alives ignore this field.
		79  	// If negative, keep-alive probes are disabled.
		80  	KeepAlive time.Duration
		81  
		82  	// Resolver optionally specifies an alternate resolver to use.
		83  	Resolver *Resolver
		84  
		85  	// Cancel is an optional channel whose closure indicates that
		86  	// the dial should be canceled. Not all types of dials support
		87  	// cancellation.
		88  	//
		89  	// Deprecated: Use DialContext instead.
		90  	Cancel <-chan struct{}
		91  
		92  	// If Control is not nil, it is called after creating the network
		93  	// connection but before actually dialing.
		94  	//
		95  	// Network and address parameters passed to Control method are not
		96  	// necessarily the ones passed to Dial. For example, passing "tcp" to Dial
		97  	// will cause the Control function to be called with "tcp4" or "tcp6".
		98  	Control func(network, address string, c syscall.RawConn) error
		99  }
	 100  
	 101  func (d *Dialer) dualStack() bool { return d.FallbackDelay >= 0 }
	 102  
	 103  func minNonzeroTime(a, b time.Time) time.Time {
	 104  	if a.IsZero() {
	 105  		return b
	 106  	}
	 107  	if b.IsZero() || a.Before(b) {
	 108  		return a
	 109  	}
	 110  	return b
	 111  }
	 112  
	 113  // deadline returns the earliest of:
	 114  //	 - now+Timeout
	 115  //	 - d.Deadline
	 116  //	 - the context's deadline
	 117  // Or zero, if none of Timeout, Deadline, or context's deadline is set.
	 118  func (d *Dialer) deadline(ctx context.Context, now time.Time) (earliest time.Time) {
	 119  	if d.Timeout != 0 { // including negative, for historical reasons
	 120  		earliest = now.Add(d.Timeout)
	 121  	}
	 122  	if d, ok := ctx.Deadline(); ok {
	 123  		earliest = minNonzeroTime(earliest, d)
	 124  	}
	 125  	return minNonzeroTime(earliest, d.Deadline)
	 126  }
	 127  
	 128  func (d *Dialer) resolver() *Resolver {
	 129  	if d.Resolver != nil {
	 130  		return d.Resolver
	 131  	}
	 132  	return DefaultResolver
	 133  }
	 134  
	 135  // partialDeadline returns the deadline to use for a single address,
	 136  // when multiple addresses are pending.
	 137  func partialDeadline(now, deadline time.Time, addrsRemaining int) (time.Time, error) {
	 138  	if deadline.IsZero() {
	 139  		return deadline, nil
	 140  	}
	 141  	timeRemaining := deadline.Sub(now)
	 142  	if timeRemaining <= 0 {
	 143  		return time.Time{}, errTimeout
	 144  	}
	 145  	// Tentatively allocate equal time to each remaining address.
	 146  	timeout := timeRemaining / time.Duration(addrsRemaining)
	 147  	// If the time per address is too short, steal from the end of the list.
	 148  	const saneMinimum = 2 * time.Second
	 149  	if timeout < saneMinimum {
	 150  		if timeRemaining < saneMinimum {
	 151  			timeout = timeRemaining
	 152  		} else {
	 153  			timeout = saneMinimum
	 154  		}
	 155  	}
	 156  	return now.Add(timeout), nil
	 157  }
	 158  
	 159  func (d *Dialer) fallbackDelay() time.Duration {
	 160  	if d.FallbackDelay > 0 {
	 161  		return d.FallbackDelay
	 162  	} else {
	 163  		return 300 * time.Millisecond
	 164  	}
	 165  }
	 166  
	 167  func parseNetwork(ctx context.Context, network string, needsProto bool) (afnet string, proto int, err error) {
	 168  	i := last(network, ':')
	 169  	if i < 0 { // no colon
	 170  		switch network {
	 171  		case "tcp", "tcp4", "tcp6":
	 172  		case "udp", "udp4", "udp6":
	 173  		case "ip", "ip4", "ip6":
	 174  			if needsProto {
	 175  				return "", 0, UnknownNetworkError(network)
	 176  			}
	 177  		case "unix", "unixgram", "unixpacket":
	 178  		default:
	 179  			return "", 0, UnknownNetworkError(network)
	 180  		}
	 181  		return network, 0, nil
	 182  	}
	 183  	afnet = network[:i]
	 184  	switch afnet {
	 185  	case "ip", "ip4", "ip6":
	 186  		protostr := network[i+1:]
	 187  		proto, i, ok := dtoi(protostr)
	 188  		if !ok || i != len(protostr) {
	 189  			proto, err = lookupProtocol(ctx, protostr)
	 190  			if err != nil {
	 191  				return "", 0, err
	 192  			}
	 193  		}
	 194  		return afnet, proto, nil
	 195  	}
	 196  	return "", 0, UnknownNetworkError(network)
	 197  }
	 198  
	 199  // resolveAddrList resolves addr using hint and returns a list of
	 200  // addresses. The result contains at least one address when error is
	 201  // nil.
	 202  func (r *Resolver) resolveAddrList(ctx context.Context, op, network, addr string, hint Addr) (addrList, error) {
	 203  	afnet, _, err := parseNetwork(ctx, network, true)
	 204  	if err != nil {
	 205  		return nil, err
	 206  	}
	 207  	if op == "dial" && addr == "" {
	 208  		return nil, errMissingAddress
	 209  	}
	 210  	switch afnet {
	 211  	case "unix", "unixgram", "unixpacket":
	 212  		addr, err := ResolveUnixAddr(afnet, addr)
	 213  		if err != nil {
	 214  			return nil, err
	 215  		}
	 216  		if op == "dial" && hint != nil && addr.Network() != hint.Network() {
	 217  			return nil, &AddrError{Err: "mismatched local address type", Addr: hint.String()}
	 218  		}
	 219  		return addrList{addr}, nil
	 220  	}
	 221  	addrs, err := r.internetAddrList(ctx, afnet, addr)
	 222  	if err != nil || op != "dial" || hint == nil {
	 223  		return addrs, err
	 224  	}
	 225  	var (
	 226  		tcp			*TCPAddr
	 227  		udp			*UDPAddr
	 228  		ip			 *IPAddr
	 229  		wildcard bool
	 230  	)
	 231  	switch hint := hint.(type) {
	 232  	case *TCPAddr:
	 233  		tcp = hint
	 234  		wildcard = tcp.isWildcard()
	 235  	case *UDPAddr:
	 236  		udp = hint
	 237  		wildcard = udp.isWildcard()
	 238  	case *IPAddr:
	 239  		ip = hint
	 240  		wildcard = ip.isWildcard()
	 241  	}
	 242  	naddrs := addrs[:0]
	 243  	for _, addr := range addrs {
	 244  		if addr.Network() != hint.Network() {
	 245  			return nil, &AddrError{Err: "mismatched local address type", Addr: hint.String()}
	 246  		}
	 247  		switch addr := addr.(type) {
	 248  		case *TCPAddr:
	 249  			if !wildcard && !addr.isWildcard() && !addr.IP.matchAddrFamily(tcp.IP) {
	 250  				continue
	 251  			}
	 252  			naddrs = append(naddrs, addr)
	 253  		case *UDPAddr:
	 254  			if !wildcard && !addr.isWildcard() && !addr.IP.matchAddrFamily(udp.IP) {
	 255  				continue
	 256  			}
	 257  			naddrs = append(naddrs, addr)
	 258  		case *IPAddr:
	 259  			if !wildcard && !addr.isWildcard() && !addr.IP.matchAddrFamily(ip.IP) {
	 260  				continue
	 261  			}
	 262  			naddrs = append(naddrs, addr)
	 263  		}
	 264  	}
	 265  	if len(naddrs) == 0 {
	 266  		return nil, &AddrError{Err: errNoSuitableAddress.Error(), Addr: hint.String()}
	 267  	}
	 268  	return naddrs, nil
	 269  }
	 270  
	 271  // Dial connects to the address on the named network.
	 272  //
	 273  // Known networks are "tcp", "tcp4" (IPv4-only), "tcp6" (IPv6-only),
	 274  // "udp", "udp4" (IPv4-only), "udp6" (IPv6-only), "ip", "ip4"
	 275  // (IPv4-only), "ip6" (IPv6-only), "unix", "unixgram" and
	 276  // "unixpacket".
	 277  //
	 278  // For TCP and UDP networks, the address has the form "host:port".
	 279  // The host must be a literal IP address, or a host name that can be
	 280  // resolved to IP addresses.
	 281  // The port must be a literal port number or a service name.
	 282  // If the host is a literal IPv6 address it must be enclosed in square
	 283  // brackets, as in "[2001:db8::1]:80" or "[fe80::1%zone]:80".
	 284  // The zone specifies the scope of the literal IPv6 address as defined
	 285  // in RFC 4007.
	 286  // The functions JoinHostPort and SplitHostPort manipulate a pair of
	 287  // host and port in this form.
	 288  // When using TCP, and the host resolves to multiple IP addresses,
	 289  // Dial will try each IP address in order until one succeeds.
	 290  //
	 291  // Examples:
	 292  //	Dial("tcp", "golang.org:http")
	 293  //	Dial("tcp", "192.0.2.1:http")
	 294  //	Dial("tcp", "198.51.100.1:80")
	 295  //	Dial("udp", "[2001:db8::1]:domain")
	 296  //	Dial("udp", "[fe80::1%lo0]:53")
	 297  //	Dial("tcp", ":80")
	 298  //
	 299  // For IP networks, the network must be "ip", "ip4" or "ip6" followed
	 300  // by a colon and a literal protocol number or a protocol name, and
	 301  // the address has the form "host". The host must be a literal IP
	 302  // address or a literal IPv6 address with zone.
	 303  // It depends on each operating system how the operating system
	 304  // behaves with a non-well known protocol number such as "0" or "255".
	 305  //
	 306  // Examples:
	 307  //	Dial("ip4:1", "192.0.2.1")
	 308  //	Dial("ip6:ipv6-icmp", "2001:db8::1")
	 309  //	Dial("ip6:58", "fe80::1%lo0")
	 310  //
	 311  // For TCP, UDP and IP networks, if the host is empty or a literal
	 312  // unspecified IP address, as in ":80", "0.0.0.0:80" or "[::]:80" for
	 313  // TCP and UDP, "", "0.0.0.0" or "::" for IP, the local system is
	 314  // assumed.
	 315  //
	 316  // For Unix networks, the address must be a file system path.
	 317  func Dial(network, address string) (Conn, error) {
	 318  	var d Dialer
	 319  	return d.Dial(network, address)
	 320  }
	 321  
	 322  // DialTimeout acts like Dial but takes a timeout.
	 323  //
	 324  // The timeout includes name resolution, if required.
	 325  // When using TCP, and the host in the address parameter resolves to
	 326  // multiple IP addresses, the timeout is spread over each consecutive
	 327  // dial, such that each is given an appropriate fraction of the time
	 328  // to connect.
	 329  //
	 330  // See func Dial for a description of the network and address
	 331  // parameters.
	 332  func DialTimeout(network, address string, timeout time.Duration) (Conn, error) {
	 333  	d := Dialer{Timeout: timeout}
	 334  	return d.Dial(network, address)
	 335  }
	 336  
	 337  // sysDialer contains a Dial's parameters and configuration.
	 338  type sysDialer struct {
	 339  	Dialer
	 340  	network, address string
	 341  }
	 342  
	 343  // Dial connects to the address on the named network.
	 344  //
	 345  // See func Dial for a description of the network and address
	 346  // parameters.
	 347  //
	 348  // Dial uses context.Background internally; to specify the context, use
	 349  // DialContext.
	 350  func (d *Dialer) Dial(network, address string) (Conn, error) {
	 351  	return d.DialContext(context.Background(), network, address)
	 352  }
	 353  
	 354  // DialContext connects to the address on the named network using
	 355  // the provided context.
	 356  //
	 357  // The provided Context must be non-nil. If the context expires before
	 358  // the connection is complete, an error is returned. Once successfully
	 359  // connected, any expiration of the context will not affect the
	 360  // connection.
	 361  //
	 362  // When using TCP, and the host in the address parameter resolves to multiple
	 363  // network addresses, any dial timeout (from d.Timeout or ctx) is spread
	 364  // over each consecutive dial, such that each is given an appropriate
	 365  // fraction of the time to connect.
	 366  // For example, if a host has 4 IP addresses and the timeout is 1 minute,
	 367  // the connect to each single address will be given 15 seconds to complete
	 368  // before trying the next one.
	 369  //
	 370  // See func Dial for a description of the network and address
	 371  // parameters.
	 372  func (d *Dialer) DialContext(ctx context.Context, network, address string) (Conn, error) {
	 373  	if ctx == nil {
	 374  		panic("nil context")
	 375  	}
	 376  	deadline := d.deadline(ctx, time.Now())
	 377  	if !deadline.IsZero() {
	 378  		if d, ok := ctx.Deadline(); !ok || deadline.Before(d) {
	 379  			subCtx, cancel := context.WithDeadline(ctx, deadline)
	 380  			defer cancel()
	 381  			ctx = subCtx
	 382  		}
	 383  	}
	 384  	if oldCancel := d.Cancel; oldCancel != nil {
	 385  		subCtx, cancel := context.WithCancel(ctx)
	 386  		defer cancel()
	 387  		go func() {
	 388  			select {
	 389  			case <-oldCancel:
	 390  				cancel()
	 391  			case <-subCtx.Done():
	 392  			}
	 393  		}()
	 394  		ctx = subCtx
	 395  	}
	 396  
	 397  	// Shadow the nettrace (if any) during resolve so Connect events don't fire for DNS lookups.
	 398  	resolveCtx := ctx
	 399  	if trace, _ := ctx.Value(nettrace.TraceKey{}).(*nettrace.Trace); trace != nil {
	 400  		shadow := *trace
	 401  		shadow.ConnectStart = nil
	 402  		shadow.ConnectDone = nil
	 403  		resolveCtx = context.WithValue(resolveCtx, nettrace.TraceKey{}, &shadow)
	 404  	}
	 405  
	 406  	addrs, err := d.resolver().resolveAddrList(resolveCtx, "dial", network, address, d.LocalAddr)
	 407  	if err != nil {
	 408  		return nil, &OpError{Op: "dial", Net: network, Source: nil, Addr: nil, Err: err}
	 409  	}
	 410  
	 411  	sd := &sysDialer{
	 412  		Dialer:	*d,
	 413  		network: network,
	 414  		address: address,
	 415  	}
	 416  
	 417  	var primaries, fallbacks addrList
	 418  	if d.dualStack() && network == "tcp" {
	 419  		primaries, fallbacks = addrs.partition(isIPv4)
	 420  	} else {
	 421  		primaries = addrs
	 422  	}
	 423  
	 424  	var c Conn
	 425  	if len(fallbacks) > 0 {
	 426  		c, err = sd.dialParallel(ctx, primaries, fallbacks)
	 427  	} else {
	 428  		c, err = sd.dialSerial(ctx, primaries)
	 429  	}
	 430  	if err != nil {
	 431  		return nil, err
	 432  	}
	 433  
	 434  	if tc, ok := c.(*TCPConn); ok && d.KeepAlive >= 0 {
	 435  		setKeepAlive(tc.fd, true)
	 436  		ka := d.KeepAlive
	 437  		if d.KeepAlive == 0 {
	 438  			ka = defaultTCPKeepAlive
	 439  		}
	 440  		setKeepAlivePeriod(tc.fd, ka)
	 441  		testHookSetKeepAlive(ka)
	 442  	}
	 443  	return c, nil
	 444  }
	 445  
	 446  // dialParallel races two copies of dialSerial, giving the first a
	 447  // head start. It returns the first established connection and
	 448  // closes the others. Otherwise it returns an error from the first
	 449  // primary address.
	 450  func (sd *sysDialer) dialParallel(ctx context.Context, primaries, fallbacks addrList) (Conn, error) {
	 451  	if len(fallbacks) == 0 {
	 452  		return sd.dialSerial(ctx, primaries)
	 453  	}
	 454  
	 455  	returned := make(chan struct{})
	 456  	defer close(returned)
	 457  
	 458  	type dialResult struct {
	 459  		Conn
	 460  		error
	 461  		primary bool
	 462  		done		bool
	 463  	}
	 464  	results := make(chan dialResult) // unbuffered
	 465  
	 466  	startRacer := func(ctx context.Context, primary bool) {
	 467  		ras := primaries
	 468  		if !primary {
	 469  			ras = fallbacks
	 470  		}
	 471  		c, err := sd.dialSerial(ctx, ras)
	 472  		select {
	 473  		case results <- dialResult{Conn: c, error: err, primary: primary, done: true}:
	 474  		case <-returned:
	 475  			if c != nil {
	 476  				c.Close()
	 477  			}
	 478  		}
	 479  	}
	 480  
	 481  	var primary, fallback dialResult
	 482  
	 483  	// Start the main racer.
	 484  	primaryCtx, primaryCancel := context.WithCancel(ctx)
	 485  	defer primaryCancel()
	 486  	go startRacer(primaryCtx, true)
	 487  
	 488  	// Start the timer for the fallback racer.
	 489  	fallbackTimer := time.NewTimer(sd.fallbackDelay())
	 490  	defer fallbackTimer.Stop()
	 491  
	 492  	for {
	 493  		select {
	 494  		case <-fallbackTimer.C:
	 495  			fallbackCtx, fallbackCancel := context.WithCancel(ctx)
	 496  			defer fallbackCancel()
	 497  			go startRacer(fallbackCtx, false)
	 498  
	 499  		case res := <-results:
	 500  			if res.error == nil {
	 501  				return res.Conn, nil
	 502  			}
	 503  			if res.primary {
	 504  				primary = res
	 505  			} else {
	 506  				fallback = res
	 507  			}
	 508  			if primary.done && fallback.done {
	 509  				return nil, primary.error
	 510  			}
	 511  			if res.primary && fallbackTimer.Stop() {
	 512  				// If we were able to stop the timer, that means it
	 513  				// was running (hadn't yet started the fallback), but
	 514  				// we just got an error on the primary path, so start
	 515  				// the fallback immediately (in 0 nanoseconds).
	 516  				fallbackTimer.Reset(0)
	 517  			}
	 518  		}
	 519  	}
	 520  }
	 521  
	 522  // dialSerial connects to a list of addresses in sequence, returning
	 523  // either the first successful connection, or the first error.
	 524  func (sd *sysDialer) dialSerial(ctx context.Context, ras addrList) (Conn, error) {
	 525  	var firstErr error // The error from the first address is most relevant.
	 526  
	 527  	for i, ra := range ras {
	 528  		select {
	 529  		case <-ctx.Done():
	 530  			return nil, &OpError{Op: "dial", Net: sd.network, Source: sd.LocalAddr, Addr: ra, Err: mapErr(ctx.Err())}
	 531  		default:
	 532  		}
	 533  
	 534  		dialCtx := ctx
	 535  		if deadline, hasDeadline := ctx.Deadline(); hasDeadline {
	 536  			partialDeadline, err := partialDeadline(time.Now(), deadline, len(ras)-i)
	 537  			if err != nil {
	 538  				// Ran out of time.
	 539  				if firstErr == nil {
	 540  					firstErr = &OpError{Op: "dial", Net: sd.network, Source: sd.LocalAddr, Addr: ra, Err: err}
	 541  				}
	 542  				break
	 543  			}
	 544  			if partialDeadline.Before(deadline) {
	 545  				var cancel context.CancelFunc
	 546  				dialCtx, cancel = context.WithDeadline(ctx, partialDeadline)
	 547  				defer cancel()
	 548  			}
	 549  		}
	 550  
	 551  		c, err := sd.dialSingle(dialCtx, ra)
	 552  		if err == nil {
	 553  			return c, nil
	 554  		}
	 555  		if firstErr == nil {
	 556  			firstErr = err
	 557  		}
	 558  	}
	 559  
	 560  	if firstErr == nil {
	 561  		firstErr = &OpError{Op: "dial", Net: sd.network, Source: nil, Addr: nil, Err: errMissingAddress}
	 562  	}
	 563  	return nil, firstErr
	 564  }
	 565  
	 566  // dialSingle attempts to establish and returns a single connection to
	 567  // the destination address.
	 568  func (sd *sysDialer) dialSingle(ctx context.Context, ra Addr) (c Conn, err error) {
	 569  	trace, _ := ctx.Value(nettrace.TraceKey{}).(*nettrace.Trace)
	 570  	if trace != nil {
	 571  		raStr := ra.String()
	 572  		if trace.ConnectStart != nil {
	 573  			trace.ConnectStart(sd.network, raStr)
	 574  		}
	 575  		if trace.ConnectDone != nil {
	 576  			defer func() { trace.ConnectDone(sd.network, raStr, err) }()
	 577  		}
	 578  	}
	 579  	la := sd.LocalAddr
	 580  	switch ra := ra.(type) {
	 581  	case *TCPAddr:
	 582  		la, _ := la.(*TCPAddr)
	 583  		c, err = sd.dialTCP(ctx, la, ra)
	 584  	case *UDPAddr:
	 585  		la, _ := la.(*UDPAddr)
	 586  		c, err = sd.dialUDP(ctx, la, ra)
	 587  	case *IPAddr:
	 588  		la, _ := la.(*IPAddr)
	 589  		c, err = sd.dialIP(ctx, la, ra)
	 590  	case *UnixAddr:
	 591  		la, _ := la.(*UnixAddr)
	 592  		c, err = sd.dialUnix(ctx, la, ra)
	 593  	default:
	 594  		return nil, &OpError{Op: "dial", Net: sd.network, Source: la, Addr: ra, Err: &AddrError{Err: "unexpected address type", Addr: sd.address}}
	 595  	}
	 596  	if err != nil {
	 597  		return nil, &OpError{Op: "dial", Net: sd.network, Source: la, Addr: ra, Err: err} // c is non-nil interface containing nil pointer
	 598  	}
	 599  	return c, nil
	 600  }
	 601  
	 602  // ListenConfig contains options for listening to an address.
	 603  type ListenConfig struct {
	 604  	// If Control is not nil, it is called after creating the network
	 605  	// connection but before binding it to the operating system.
	 606  	//
	 607  	// Network and address parameters passed to Control method are not
	 608  	// necessarily the ones passed to Listen. For example, passing "tcp" to
	 609  	// Listen will cause the Control function to be called with "tcp4" or "tcp6".
	 610  	Control func(network, address string, c syscall.RawConn) error
	 611  
	 612  	// KeepAlive specifies the keep-alive period for network
	 613  	// connections accepted by this listener.
	 614  	// If zero, keep-alives are enabled if supported by the protocol
	 615  	// and operating system. Network protocols or operating systems
	 616  	// that do not support keep-alives ignore this field.
	 617  	// If negative, keep-alives are disabled.
	 618  	KeepAlive time.Duration
	 619  }
	 620  
	 621  // Listen announces on the local network address.
	 622  //
	 623  // See func Listen for a description of the network and address
	 624  // parameters.
	 625  func (lc *ListenConfig) Listen(ctx context.Context, network, address string) (Listener, error) {
	 626  	addrs, err := DefaultResolver.resolveAddrList(ctx, "listen", network, address, nil)
	 627  	if err != nil {
	 628  		return nil, &OpError{Op: "listen", Net: network, Source: nil, Addr: nil, Err: err}
	 629  	}
	 630  	sl := &sysListener{
	 631  		ListenConfig: *lc,
	 632  		network:			network,
	 633  		address:			address,
	 634  	}
	 635  	var l Listener
	 636  	la := addrs.first(isIPv4)
	 637  	switch la := la.(type) {
	 638  	case *TCPAddr:
	 639  		l, err = sl.listenTCP(ctx, la)
	 640  	case *UnixAddr:
	 641  		l, err = sl.listenUnix(ctx, la)
	 642  	default:
	 643  		return nil, &OpError{Op: "listen", Net: sl.network, Source: nil, Addr: la, Err: &AddrError{Err: "unexpected address type", Addr: address}}
	 644  	}
	 645  	if err != nil {
	 646  		return nil, &OpError{Op: "listen", Net: sl.network, Source: nil, Addr: la, Err: err} // l is non-nil interface containing nil pointer
	 647  	}
	 648  	return l, nil
	 649  }
	 650  
	 651  // ListenPacket announces on the local network address.
	 652  //
	 653  // See func ListenPacket for a description of the network and address
	 654  // parameters.
	 655  func (lc *ListenConfig) ListenPacket(ctx context.Context, network, address string) (PacketConn, error) {
	 656  	addrs, err := DefaultResolver.resolveAddrList(ctx, "listen", network, address, nil)
	 657  	if err != nil {
	 658  		return nil, &OpError{Op: "listen", Net: network, Source: nil, Addr: nil, Err: err}
	 659  	}
	 660  	sl := &sysListener{
	 661  		ListenConfig: *lc,
	 662  		network:			network,
	 663  		address:			address,
	 664  	}
	 665  	var c PacketConn
	 666  	la := addrs.first(isIPv4)
	 667  	switch la := la.(type) {
	 668  	case *UDPAddr:
	 669  		c, err = sl.listenUDP(ctx, la)
	 670  	case *IPAddr:
	 671  		c, err = sl.listenIP(ctx, la)
	 672  	case *UnixAddr:
	 673  		c, err = sl.listenUnixgram(ctx, la)
	 674  	default:
	 675  		return nil, &OpError{Op: "listen", Net: sl.network, Source: nil, Addr: la, Err: &AddrError{Err: "unexpected address type", Addr: address}}
	 676  	}
	 677  	if err != nil {
	 678  		return nil, &OpError{Op: "listen", Net: sl.network, Source: nil, Addr: la, Err: err} // c is non-nil interface containing nil pointer
	 679  	}
	 680  	return c, nil
	 681  }
	 682  
	 683  // sysListener contains a Listen's parameters and configuration.
	 684  type sysListener struct {
	 685  	ListenConfig
	 686  	network, address string
	 687  }
	 688  
	 689  // Listen announces on the local network address.
	 690  //
	 691  // The network must be "tcp", "tcp4", "tcp6", "unix" or "unixpacket".
	 692  //
	 693  // For TCP networks, if the host in the address parameter is empty or
	 694  // a literal unspecified IP address, Listen listens on all available
	 695  // unicast and anycast IP addresses of the local system.
	 696  // To only use IPv4, use network "tcp4".
	 697  // The address can use a host name, but this is not recommended,
	 698  // because it will create a listener for at most one of the host's IP
	 699  // addresses.
	 700  // If the port in the address parameter is empty or "0", as in
	 701  // "127.0.0.1:" or "[::1]:0", a port number is automatically chosen.
	 702  // The Addr method of Listener can be used to discover the chosen
	 703  // port.
	 704  //
	 705  // See func Dial for a description of the network and address
	 706  // parameters.
	 707  //
	 708  // Listen uses context.Background internally; to specify the context, use
	 709  // ListenConfig.Listen.
	 710  func Listen(network, address string) (Listener, error) {
	 711  	var lc ListenConfig
	 712  	return lc.Listen(context.Background(), network, address)
	 713  }
	 714  
	 715  // ListenPacket announces on the local network address.
	 716  //
	 717  // The network must be "udp", "udp4", "udp6", "unixgram", or an IP
	 718  // transport. The IP transports are "ip", "ip4", or "ip6" followed by
	 719  // a colon and a literal protocol number or a protocol name, as in
	 720  // "ip:1" or "ip:icmp".
	 721  //
	 722  // For UDP and IP networks, if the host in the address parameter is
	 723  // empty or a literal unspecified IP address, ListenPacket listens on
	 724  // all available IP addresses of the local system except multicast IP
	 725  // addresses.
	 726  // To only use IPv4, use network "udp4" or "ip4:proto".
	 727  // The address can use a host name, but this is not recommended,
	 728  // because it will create a listener for at most one of the host's IP
	 729  // addresses.
	 730  // If the port in the address parameter is empty or "0", as in
	 731  // "127.0.0.1:" or "[::1]:0", a port number is automatically chosen.
	 732  // The LocalAddr method of PacketConn can be used to discover the
	 733  // chosen port.
	 734  //
	 735  // See func Dial for a description of the network and address
	 736  // parameters.
	 737  //
	 738  // ListenPacket uses context.Background internally; to specify the context, use
	 739  // ListenConfig.ListenPacket.
	 740  func ListenPacket(network, address string) (PacketConn, error) {
	 741  	var lc ListenConfig
	 742  	return lc.ListenPacket(context.Background(), network, address)
	 743  }
	 744  

View as plain text