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 "internal/poll" 85 "io" 86 "os" 87 "sync" 88 "syscall" 89 "time" 90 ) 91 92 // netGo and netCgo contain the state of the build tags used 93 // to build this binary, and whether cgo is available. 94 // conf.go mirrors these into conf for easier testing. 95 var ( 96 netGo bool // set true in cgo_stub.go for build tag "netgo" (or no cgo) 97 netCgo bool // set true in conf_netcgo.go for build tag "netcgo" 98 ) 99 100 // Addr represents a network end point address. 101 // 102 // The two methods Network and String conventionally return strings 103 // that can be passed as the arguments to Dial, but the exact form 104 // and meaning of the strings is up to the implementation. 105 type Addr interface { 106 Network() string // name of the network (for example, "tcp", "udp") 107 String() string // string form of address (for example, "192.0.2.1:25", "[2001:db8::1]:80") 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 an 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 an 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 and pending 141 // I/O, not just the immediately following call to Read or 142 // Write. After a deadline has been exceeded, the connection 143 // can be refreshed by setting a deadline in the future. 144 // 145 // An idle timeout can be implemented by repeatedly extending 146 // the deadline after successful Read or Write calls. 147 // 148 // A zero value for t means I/O operations will not time out. 149 SetDeadline(t time.Time) error 150 151 // SetReadDeadline sets the deadline for future Read calls 152 // and any currently-blocked Read call. 153 // A zero value for t means Read will not time out. 154 SetReadDeadline(t time.Time) error 155 156 // SetWriteDeadline sets the deadline for future Write calls 157 // and any currently-blocked Write call. 158 // Even if write times out, it may return n > 0, indicating that 159 // some of the data was successfully written. 160 // A zero value for t means Write will not time out. 161 SetWriteDeadline(t time.Time) error 162 } 163 164 type conn struct { 165 fd *netFD 166 } 167 168 func (c *conn) ok() bool { return c != nil && c.fd != nil } 169 170 // Implementation of the Conn interface. 171 172 // Read implements the Conn Read method. 173 func (c *conn) Read(b []byte) (int, error) { 174 if !c.ok() { 175 return 0, syscall.EINVAL 176 } 177 n, err := c.fd.Read(b) 178 if err != nil && err != io.EOF { 179 err = &OpError{Op: "read", Net: c.fd.net, Source: c.fd.laddr, Addr: c.fd.raddr, Err: err} 180 } 181 return n, err 182 } 183 184 // Write implements the Conn Write method. 185 func (c *conn) Write(b []byte) (int, error) { 186 if !c.ok() { 187 return 0, syscall.EINVAL 188 } 189 n, err := c.fd.Write(b) 190 if err != nil { 191 err = &OpError{Op: "write", Net: c.fd.net, Source: c.fd.laddr, Addr: c.fd.raddr, Err: err} 192 } 193 return n, err 194 } 195 196 // Close closes the connection. 197 func (c *conn) Close() error { 198 if !c.ok() { 199 return syscall.EINVAL 200 } 201 err := c.fd.Close() 202 if err != nil { 203 err = &OpError{Op: "close", Net: c.fd.net, Source: c.fd.laddr, Addr: c.fd.raddr, Err: err} 204 } 205 return err 206 } 207 208 // LocalAddr returns the local network address. 209 // The Addr returned is shared by all invocations of LocalAddr, so 210 // do not modify it. 211 func (c *conn) LocalAddr() Addr { 212 if !c.ok() { 213 return nil 214 } 215 return c.fd.laddr 216 } 217 218 // RemoteAddr returns the remote network address. 219 // The Addr returned is shared by all invocations of RemoteAddr, so 220 // do not modify it. 221 func (c *conn) RemoteAddr() Addr { 222 if !c.ok() { 223 return nil 224 } 225 return c.fd.raddr 226 } 227 228 // SetDeadline implements the Conn SetDeadline method. 229 func (c *conn) SetDeadline(t time.Time) error { 230 if !c.ok() { 231 return syscall.EINVAL 232 } 233 if err := c.fd.SetDeadline(t); err != nil { 234 return &OpError{Op: "set", Net: c.fd.net, Source: nil, Addr: c.fd.laddr, Err: err} 235 } 236 return nil 237 } 238 239 // SetReadDeadline implements the Conn SetReadDeadline method. 240 func (c *conn) SetReadDeadline(t time.Time) error { 241 if !c.ok() { 242 return syscall.EINVAL 243 } 244 if err := c.fd.SetReadDeadline(t); err != nil { 245 return &OpError{Op: "set", Net: c.fd.net, Source: nil, Addr: c.fd.laddr, Err: err} 246 } 247 return nil 248 } 249 250 // SetWriteDeadline implements the Conn SetWriteDeadline method. 251 func (c *conn) SetWriteDeadline(t time.Time) error { 252 if !c.ok() { 253 return syscall.EINVAL 254 } 255 if err := c.fd.SetWriteDeadline(t); err != nil { 256 return &OpError{Op: "set", Net: c.fd.net, Source: nil, Addr: c.fd.laddr, Err: err} 257 } 258 return nil 259 } 260 261 // SetReadBuffer sets the size of the operating system's 262 // receive buffer associated with the connection. 263 func (c *conn) SetReadBuffer(bytes int) error { 264 if !c.ok() { 265 return syscall.EINVAL 266 } 267 if err := setReadBuffer(c.fd, bytes); err != nil { 268 return &OpError{Op: "set", Net: c.fd.net, Source: nil, Addr: c.fd.laddr, Err: err} 269 } 270 return nil 271 } 272 273 // SetWriteBuffer sets the size of the operating system's 274 // transmit buffer associated with the connection. 275 func (c *conn) SetWriteBuffer(bytes int) error { 276 if !c.ok() { 277 return syscall.EINVAL 278 } 279 if err := setWriteBuffer(c.fd, bytes); err != nil { 280 return &OpError{Op: "set", Net: c.fd.net, Source: nil, Addr: c.fd.laddr, Err: err} 281 } 282 return nil 283 } 284 285 // File returns a copy of the underlying os.File 286 // It is the caller's responsibility to close f when finished. 287 // Closing c does not affect f, and closing f does not affect c. 288 // 289 // The returned os.File's file descriptor is different from the connection's. 290 // Attempting to change properties of the original using this duplicate 291 // may or may not have the desired effect. 292 func (c *conn) File() (f *os.File, err error) { 293 f, err = c.fd.dup() 294 if err != nil { 295 err = &OpError{Op: "file", Net: c.fd.net, Source: c.fd.laddr, Addr: c.fd.raddr, Err: err} 296 } 297 return 298 } 299 300 // PacketConn is a generic packet-oriented network connection. 301 // 302 // Multiple goroutines may invoke methods on a PacketConn simultaneously. 303 type PacketConn interface { 304 // ReadFrom reads a packet from the connection, 305 // copying the payload into p. It returns the number of 306 // bytes copied into p and the return address that 307 // was on the packet. 308 // It returns the number of bytes read (0 <= n <= len(p)) 309 // and any error encountered. Callers should always process 310 // the n > 0 bytes returned before considering the error err. 311 // ReadFrom can be made to time out and return 312 // an Error with Timeout() == true after a fixed time limit; 313 // see SetDeadline and SetReadDeadline. 314 ReadFrom(p []byte) (n int, addr Addr, err error) 315 316 // WriteTo writes a packet with payload p to addr. 317 // WriteTo can be made to time out and return 318 // an Error with Timeout() == true after a fixed time limit; 319 // see SetDeadline and SetWriteDeadline. 320 // On packet-oriented connections, write timeouts are rare. 321 WriteTo(p []byte, addr Addr) (n int, err error) 322 323 // Close closes the connection. 324 // Any blocked ReadFrom or WriteTo operations will be unblocked and return errors. 325 Close() error 326 327 // LocalAddr returns the local network address. 328 LocalAddr() Addr 329 330 // SetDeadline sets the read and write deadlines associated 331 // with the connection. It is equivalent to calling both 332 // SetReadDeadline and SetWriteDeadline. 333 // 334 // A deadline is an absolute time after which I/O operations 335 // fail with a timeout (see type Error) instead of 336 // blocking. The deadline applies to all future and pending 337 // I/O, not just the immediately following call to ReadFrom or 338 // WriteTo. After a deadline has been exceeded, the connection 339 // can be refreshed by setting a deadline in the future. 340 // 341 // An idle timeout can be implemented by repeatedly extending 342 // the deadline after successful ReadFrom or WriteTo calls. 343 // 344 // A zero value for t means I/O operations will not time out. 345 SetDeadline(t time.Time) error 346 347 // SetReadDeadline sets the deadline for future ReadFrom calls 348 // and any currently-blocked ReadFrom call. 349 // A zero value for t means ReadFrom will not time out. 350 SetReadDeadline(t time.Time) error 351 352 // SetWriteDeadline sets the deadline for future WriteTo calls 353 // and any currently-blocked WriteTo call. 354 // Even if write times out, it may return n > 0, indicating that 355 // some of the data was successfully written. 356 // A zero value for t means WriteTo will not time out. 357 SetWriteDeadline(t time.Time) error 358 } 359 360 var listenerBacklogCache struct { 361 sync.Once 362 val int 363 } 364 365 // listenerBacklog is a caching wrapper around maxListenerBacklog. 366 func listenerBacklog() int { 367 listenerBacklogCache.Do(func() { listenerBacklogCache.val = maxListenerBacklog() }) 368 return listenerBacklogCache.val 369 } 370 371 // A Listener is a generic network listener for stream-oriented protocols. 372 // 373 // Multiple goroutines may invoke methods on a Listener simultaneously. 374 type Listener interface { 375 // Accept waits for and returns the next connection to the listener. 376 Accept() (Conn, error) 377 378 // Close closes the listener. 379 // Any blocked Accept operations will be unblocked and return errors. 380 Close() error 381 382 // Addr returns the listener's network address. 383 Addr() Addr 384 } 385 386 // An Error represents a network error. 387 type Error interface { 388 error 389 Timeout() bool // Is the error a timeout? 390 Temporary() bool // Is the error temporary? 391 } 392 393 // Various errors contained in OpError. 394 var ( 395 // For connection setup operations. 396 errNoSuitableAddress = errors.New("no suitable address found") 397 398 // For connection setup and write operations. 399 errMissingAddress = errors.New("missing address") 400 401 // For both read and write operations. 402 errCanceled = errors.New("operation was canceled") 403 ErrWriteToConnected = errors.New("use of WriteTo with pre-connected connection") 404 ) 405 406 // mapErr maps from the context errors to the historical internal net 407 // error values. 408 // 409 // TODO(bradfitz): get rid of this after adjusting tests and making 410 // context.DeadlineExceeded implement net.Error? 411 func mapErr(err error) error { 412 switch err { 413 case context.Canceled: 414 return errCanceled 415 case context.DeadlineExceeded: 416 return poll.ErrTimeout 417 default: 418 return err 419 } 420 } 421 422 // OpError is the error type usually returned by functions in the net 423 // package. It describes the operation, network type, and address of 424 // an error. 425 type OpError struct { 426 // Op is the operation which caused the error, such as 427 // "read" or "write". 428 Op string 429 430 // Net is the network type on which this error occurred, 431 // such as "tcp" or "udp6". 432 Net string 433 434 // For operations involving a remote network connection, like 435 // Dial, Read, or Write, Source is the corresponding local 436 // network address. 437 Source Addr 438 439 // Addr is the network address for which this error occurred. 440 // For local operations, like Listen or SetDeadline, Addr is 441 // the address of the local endpoint being manipulated. 442 // For operations involving a remote network connection, like 443 // Dial, Read, or Write, Addr is the remote address of that 444 // connection. 445 Addr Addr 446 447 // Err is the error that occurred during the operation. 448 Err error 449 } 450 451 func (e *OpError) Error() string { 452 if e == nil { 453 return "<nil>" 454 } 455 s := e.Op 456 if e.Net != "" { 457 s += " " + e.Net 458 } 459 if e.Source != nil { 460 s += " " + e.Source.String() 461 } 462 if e.Addr != nil { 463 if e.Source != nil { 464 s += "->" 465 } else { 466 s += " " 467 } 468 s += e.Addr.String() 469 } 470 s += ": " + e.Err.Error() 471 return s 472 } 473 474 var ( 475 // aLongTimeAgo is a non-zero time, far in the past, used for 476 // immediate cancelation of dials. 477 aLongTimeAgo = time.Unix(1, 0) 478 479 // nonDeadline and noCancel are just zero values for 480 // readability with functions taking too many parameters. 481 noDeadline = time.Time{} 482 noCancel = (chan struct{})(nil) 483 ) 484 485 type timeout interface { 486 Timeout() bool 487 } 488 489 func (e *OpError) Timeout() bool { 490 if ne, ok := e.Err.(*os.SyscallError); ok { 491 t, ok := ne.Err.(timeout) 492 return ok && t.Timeout() 493 } 494 t, ok := e.Err.(timeout) 495 return ok && t.Timeout() 496 } 497 498 type temporary interface { 499 Temporary() bool 500 } 501 502 func (e *OpError) Temporary() bool { 503 // Treat ECONNRESET and ECONNABORTED as temporary errors when 504 // they come from calling accept. See issue 6163. 505 if e.Op == "accept" && isConnError(e.Err) { 506 return true 507 } 508 509 if ne, ok := e.Err.(*os.SyscallError); ok { 510 t, ok := ne.Err.(temporary) 511 return ok && t.Temporary() 512 } 513 t, ok := e.Err.(temporary) 514 return ok && t.Temporary() 515 } 516 517 // A ParseError is the error type of literal network address parsers. 518 type ParseError struct { 519 // Type is the type of string that was expected, such as 520 // "IP address", "CIDR address". 521 Type string 522 523 // Text is the malformed text string. 524 Text string 525 } 526 527 func (e *ParseError) Error() string { return "invalid " + e.Type + ": " + e.Text } 528 529 type AddrError struct { 530 Err string 531 Addr string 532 } 533 534 func (e *AddrError) Error() string { 535 if e == nil { 536 return "<nil>" 537 } 538 s := e.Err 539 if e.Addr != "" { 540 s = "address " + e.Addr + ": " + s 541 } 542 return s 543 } 544 545 func (e *AddrError) Timeout() bool { return false } 546 func (e *AddrError) Temporary() bool { return false } 547 548 type UnknownNetworkError string 549 550 func (e UnknownNetworkError) Error() string { return "unknown network " + string(e) } 551 func (e UnknownNetworkError) Timeout() bool { return false } 552 func (e UnknownNetworkError) Temporary() bool { return false } 553 554 type InvalidAddrError string 555 556 func (e InvalidAddrError) Error() string { return string(e) } 557 func (e InvalidAddrError) Timeout() bool { return false } 558 func (e InvalidAddrError) Temporary() bool { return false } 559 560 // DNSConfigError represents an error reading the machine's DNS configuration. 561 // (No longer used; kept for compatibility.) 562 type DNSConfigError struct { 563 Err error 564 } 565 566 func (e *DNSConfigError) Error() string { return "error reading DNS config: " + e.Err.Error() } 567 func (e *DNSConfigError) Timeout() bool { return false } 568 func (e *DNSConfigError) Temporary() bool { return false } 569 570 // Various errors contained in DNSError. 571 var ( 572 errNoSuchHost = errors.New("no such host") 573 ) 574 575 // DNSError represents a DNS lookup error. 576 type DNSError struct { 577 Err string // description of the error 578 Name string // name looked for 579 Server string // server used 580 IsTimeout bool // if true, timed out; not all timeouts set this 581 IsTemporary bool // if true, error is temporary; not all errors set this 582 } 583 584 func (e *DNSError) Error() string { 585 if e == nil { 586 return "<nil>" 587 } 588 s := "lookup " + e.Name 589 if e.Server != "" { 590 s += " on " + e.Server 591 } 592 s += ": " + e.Err 593 return s 594 } 595 596 // Timeout reports whether the DNS lookup is known to have timed out. 597 // This is not always known; a DNS lookup may fail due to a timeout 598 // and return a DNSError for which Timeout returns false. 599 func (e *DNSError) Timeout() bool { return e.IsTimeout } 600 601 // Temporary reports whether the DNS error is known to be temporary. 602 // This is not always known; a DNS lookup may fail due to a temporary 603 // error and return a DNSError for which Temporary returns false. 604 func (e *DNSError) Temporary() bool { return e.IsTimeout || e.IsTemporary } 605 606 type writerOnly struct { 607 io.Writer 608 } 609 610 // Fallback implementation of io.ReaderFrom's ReadFrom, when sendfile isn't 611 // applicable. 612 func genericReadFrom(w io.Writer, r io.Reader) (n int64, err error) { 613 // Use wrapper to hide existing r.ReadFrom from io.Copy. 614 return io.Copy(writerOnly{w}, r) 615 } 616 617 // Limit the number of concurrent cgo-using goroutines, because 618 // each will block an entire operating system thread. The usual culprit 619 // is resolving many DNS names in separate goroutines but the DNS 620 // server is not responding. Then the many lookups each use a different 621 // thread, and the system or the program runs out of threads. 622 623 var threadLimit chan struct{} 624 625 var threadOnce sync.Once 626 627 func acquireThread() { 628 threadOnce.Do(func() { 629 threadLimit = make(chan struct{}, concurrentThreadsLimit()) 630 }) 631 threadLimit <- struct{}{} 632 } 633 634 func releaseThread() { 635 <-threadLimit 636 } 637 638 // buffersWriter is the interface implemented by Conns that support a 639 // "writev"-like batch write optimization. 640 // writeBuffers should fully consume and write all chunks from the 641 // provided Buffers, else it should report a non-nil error. 642 type buffersWriter interface { 643 writeBuffers(*Buffers) (int64, error) 644 } 645 646 // Buffers contains zero or more runs of bytes to write. 647 // 648 // On certain machines, for certain types of connections, this is 649 // optimized into an OS-specific batch write operation (such as 650 // "writev"). 651 type Buffers [][]byte 652 653 var ( 654 _ io.WriterTo = (*Buffers)(nil) 655 _ io.Reader = (*Buffers)(nil) 656 ) 657 658 func (v *Buffers) WriteTo(w io.Writer) (n int64, err error) { 659 if wv, ok := w.(buffersWriter); ok { 660 return wv.writeBuffers(v) 661 } 662 for _, b := range *v { 663 nb, err := w.Write(b) 664 n += int64(nb) 665 if err != nil { 666 v.consume(n) 667 return n, err 668 } 669 } 670 v.consume(n) 671 return n, nil 672 } 673 674 func (v *Buffers) Read(p []byte) (n int, err error) { 675 for len(p) > 0 && len(*v) > 0 { 676 n0 := copy(p, (*v)[0]) 677 v.consume(int64(n0)) 678 p = p[n0:] 679 n += n0 680 } 681 if len(*v) == 0 { 682 err = io.EOF 683 } 684 return 685 } 686 687 func (v *Buffers) consume(n int64) { 688 for len(*v) > 0 { 689 ln0 := int64(len((*v)[0])) 690 if ln0 > n { 691 (*v)[0] = (*v)[0][n:] 692 return 693 } 694 n -= ln0 695 *v = (*v)[1:] 696 } 697 } 698