Source file src/pkg/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 continue 36 } 37 go handleConnection(conn) 38 } 39 */ 40 package net 41 42 // TODO(rsc): 43 // support for raw ethernet sockets 44 45 import ( 46 "errors" 47 "time" 48 ) 49 50 // Addr represents a network end point address. 51 type Addr interface { 52 Network() string // name of the network 53 String() string // string form of address 54 } 55 56 // Conn is a generic stream-oriented network connection. 57 // 58 // Multiple goroutines may invoke methods on a Conn simultaneously. 59 type Conn interface { 60 // Read reads data from the connection. 61 // Read can be made to time out and return a Error with Timeout() == true 62 // after a fixed time limit; see SetDeadline and SetReadDeadline. 63 Read(b []byte) (n int, err error) 64 65 // Write writes data to the connection. 66 // Write can be made to time out and return a Error with Timeout() == true 67 // after a fixed time limit; see SetDeadline and SetWriteDeadline. 68 Write(b []byte) (n int, err error) 69 70 // Close closes the connection. 71 // Any blocked Read or Write operations will be unblocked and return errors. 72 Close() error 73 74 // LocalAddr returns the local network address. 75 LocalAddr() Addr 76 77 // RemoteAddr returns the remote network address. 78 RemoteAddr() Addr 79 80 // SetDeadline sets the read and write deadlines associated 81 // with the connection. It is equivalent to calling both 82 // SetReadDeadline and SetWriteDeadline. 83 // 84 // A deadline is an absolute time after which I/O operations 85 // fail with a timeout (see type Error) instead of 86 // blocking. The deadline applies to all future I/O, not just 87 // the immediately following call to Read or Write. 88 // 89 // An idle timeout can be implemented by repeatedly extending 90 // the deadline after successful Read or Write calls. 91 // 92 // A zero value for t means I/O operations will not time out. 93 SetDeadline(t time.Time) error 94 95 // SetReadDeadline sets the deadline for future Read calls. 96 // A zero value for t means Read will not time out. 97 SetReadDeadline(t time.Time) error 98 99 // SetWriteDeadline sets the deadline for future Write calls. 100 // Even if write times out, it may return n > 0, indicating that 101 // some of the data was successfully written. 102 // A zero value for t means Write will not time out. 103 SetWriteDeadline(t time.Time) error 104 } 105 106 // An Error represents a network error. 107 type Error interface { 108 error 109 Timeout() bool // Is the error a timeout? 110 Temporary() bool // Is the error temporary? 111 } 112 113 // PacketConn is a generic packet-oriented network connection. 114 // 115 // Multiple goroutines may invoke methods on a PacketConn simultaneously. 116 type PacketConn interface { 117 // ReadFrom reads a packet from the connection, 118 // copying the payload into b. It returns the number of 119 // bytes copied into b and the return address that 120 // was on the packet. 121 // ReadFrom can be made to time out and return 122 // an error with Timeout() == true after a fixed time limit; 123 // see SetDeadline and SetReadDeadline. 124 ReadFrom(b []byte) (n int, addr Addr, err error) 125 126 // WriteTo writes a packet with payload b to addr. 127 // WriteTo can be made to time out and return 128 // an error with Timeout() == true after a fixed time limit; 129 // see SetDeadline and SetWriteDeadline. 130 // On packet-oriented connections, write timeouts are rare. 131 WriteTo(b []byte, addr Addr) (n int, err error) 132 133 // Close closes the connection. 134 // Any blocked ReadFrom or WriteTo operations will be unblocked and return errors. 135 Close() error 136 137 // LocalAddr returns the local network address. 138 LocalAddr() Addr 139 140 // SetDeadline sets the read and write deadlines associated 141 // with the connection. 142 SetDeadline(t time.Time) error 143 144 // SetReadDeadline sets the deadline for future Read calls. 145 // If the deadline is reached, Read will fail with a timeout 146 // (see type Error) instead of blocking. 147 // A zero value for t means Read will not time out. 148 SetReadDeadline(t time.Time) error 149 150 // SetWriteDeadline sets the deadline for future Write calls. 151 // If the deadline is reached, Write will fail with a timeout 152 // (see type Error) instead of blocking. 153 // A zero value for t means Write will not time out. 154 // Even if write times out, it may return n > 0, indicating that 155 // some of the data was successfully written. 156 SetWriteDeadline(t time.Time) error 157 } 158 159 // A Listener is a generic network listener for stream-oriented protocols. 160 // 161 // Multiple goroutines may invoke methods on a Listener simultaneously. 162 type Listener interface { 163 // Accept waits for and returns the next connection to the listener. 164 Accept() (c Conn, err error) 165 166 // Close closes the listener. 167 // Any blocked Accept operations will be unblocked and return errors. 168 Close() error 169 170 // Addr returns the listener's network address. 171 Addr() Addr 172 } 173 174 var errMissingAddress = errors.New("missing address") 175 176 type OpError struct { 177 Op string 178 Net string 179 Addr Addr 180 Err error 181 } 182 183 func (e *OpError) Error() string { 184 if e == nil { 185 return "<nil>" 186 } 187 s := e.Op 188 if e.Net != "" { 189 s += " " + e.Net 190 } 191 if e.Addr != nil { 192 s += " " + e.Addr.String() 193 } 194 s += ": " + e.Err.Error() 195 return s 196 } 197 198 type temporary interface { 199 Temporary() bool 200 } 201 202 func (e *OpError) Temporary() bool { 203 t, ok := e.Err.(temporary) 204 return ok && t.Temporary() 205 } 206 207 type timeout interface { 208 Timeout() bool 209 } 210 211 func (e *OpError) Timeout() bool { 212 t, ok := e.Err.(timeout) 213 return ok && t.Timeout() 214 } 215 216 type timeoutError struct{} 217 218 func (e *timeoutError) Error() string { return "i/o timeout" } 219 func (e *timeoutError) Timeout() bool { return true } 220 func (e *timeoutError) Temporary() bool { return true } 221 222 var errTimeout error = &timeoutError{} 223 224 type AddrError struct { 225 Err string 226 Addr string 227 } 228 229 func (e *AddrError) Error() string { 230 if e == nil { 231 return "<nil>" 232 } 233 s := e.Err 234 if e.Addr != "" { 235 s += " " + e.Addr 236 } 237 return s 238 } 239 240 func (e *AddrError) Temporary() bool { 241 return false 242 } 243 244 func (e *AddrError) Timeout() bool { 245 return false 246 } 247 248 type UnknownNetworkError string 249 250 func (e UnknownNetworkError) Error() string { return "unknown network " + string(e) } 251 func (e UnknownNetworkError) Temporary() bool { return false } 252 func (e UnknownNetworkError) Timeout() bool { return false } 253 254 // DNSConfigError represents an error reading the machine's DNS configuration. 255 type DNSConfigError struct { 256 Err error 257 } 258 259 func (e *DNSConfigError) Error() string { 260 return "error reading DNS config: " + e.Err.Error() 261 } 262 263 func (e *DNSConfigError) Timeout() bool { return false } 264 func (e *DNSConfigError) Temporary() bool { return false }