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