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 // Package net provides a portable interface to Unix networks sockets, 6 // including TCP/IP, UDP, domain name resolution, and Unix domain sockets. 7 package net 8 9 // TODO(rsc): 10 // support for raw ethernet sockets 11 12 import "os" 13 14 // Addr represents a network end point address. 15 type Addr interface { 16 Network() string // name of the network 17 String() string // string form of address 18 } 19 20 // Conn is a generic stream-oriented network connection. 21 type Conn interface { 22 // Read reads data from the connection. 23 // Read can be made to time out and return a net.Error with Timeout() == true 24 // after a fixed time limit; see SetTimeout and SetReadTimeout. 25 Read(b []byte) (n int, err os.Error) 26 27 // Write writes data to the connection. 28 // Write can be made to time out and return a net.Error with Timeout() == true 29 // after a fixed time limit; see SetTimeout and SetWriteTimeout. 30 Write(b []byte) (n int, err os.Error) 31 32 // Close closes the connection. 33 Close() os.Error 34 35 // LocalAddr returns the local network address. 36 LocalAddr() Addr 37 38 // RemoteAddr returns the remote network address. 39 RemoteAddr() Addr 40 41 // SetTimeout sets the read and write deadlines associated 42 // with the connection. 43 SetTimeout(nsec int64) os.Error 44 45 // SetReadTimeout sets the time (in nanoseconds) that 46 // Read will wait for data before returning an error with Timeout() == true. 47 // Setting nsec == 0 (the default) disables the deadline. 48 SetReadTimeout(nsec int64) os.Error 49 50 // SetWriteTimeout sets the time (in nanoseconds) that 51 // Write will wait to send its data before returning an error with Timeout() == true. 52 // Setting nsec == 0 (the default) disables the deadline. 53 // Even if write times out, it may return n > 0, indicating that 54 // some of the data was successfully written. 55 SetWriteTimeout(nsec int64) os.Error 56 } 57 58 // An Error represents a network error. 59 type Error interface { 60 os.Error 61 Timeout() bool // Is the error a timeout? 62 Temporary() bool // Is the error temporary? 63 } 64 65 // PacketConn is a generic packet-oriented network connection. 66 type PacketConn interface { 67 // ReadFrom reads a packet from the connection, 68 // copying the payload into b. It returns the number of 69 // bytes copied into b and the return address that 70 // was on the packet. 71 // ReadFrom can be made to time out and return 72 // an error with Timeout() == true after a fixed time limit; 73 // see SetTimeout and SetReadTimeout. 74 ReadFrom(b []byte) (n int, addr Addr, err os.Error) 75 76 // WriteTo writes a packet with payload b to addr. 77 // WriteTo can be made to time out and return 78 // an error with Timeout() == true after a fixed time limit; 79 // see SetTimeout and SetWriteTimeout. 80 // On packet-oriented connections, write timeouts are rare. 81 WriteTo(b []byte, addr Addr) (n int, err os.Error) 82 83 // Close closes the connection. 84 Close() os.Error 85 86 // LocalAddr returns the local network address. 87 LocalAddr() Addr 88 89 // SetTimeout sets the read and write deadlines associated 90 // with the connection. 91 SetTimeout(nsec int64) os.Error 92 93 // SetReadTimeout sets the time (in nanoseconds) that 94 // Read will wait for data before returning an error with Timeout() == true. 95 // Setting nsec == 0 (the default) disables the deadline. 96 SetReadTimeout(nsec int64) os.Error 97 98 // SetWriteTimeout sets the time (in nanoseconds) that 99 // Write will wait to send its data before returning an error with Timeout() == true. 100 // Setting nsec == 0 (the default) disables the deadline. 101 // Even if write times out, it may return n > 0, indicating that 102 // some of the data was successfully written. 103 SetWriteTimeout(nsec int64) os.Error 104 } 105 106 // A Listener is a generic network listener for stream-oriented protocols. 107 type Listener interface { 108 // Accept waits for and returns the next connection to the listener. 109 Accept() (c Conn, err os.Error) 110 111 // Close closes the listener. 112 Close() os.Error 113 114 // Addr returns the listener's network address. 115 Addr() Addr 116 } 117 118 var errMissingAddress = os.NewError("missing address") 119 120 type OpError struct { 121 Op string 122 Net string 123 Addr Addr 124 Error os.Error 125 } 126 127 func (e *OpError) String() string { 128 if e == nil { 129 return "<nil>" 130 } 131 s := e.Op 132 if e.Net != "" { 133 s += " " + e.Net 134 } 135 if e.Addr != nil { 136 s += " " + e.Addr.String() 137 } 138 s += ": " + e.Error.String() 139 return s 140 } 141 142 type temporary interface { 143 Temporary() bool 144 } 145 146 func (e *OpError) Temporary() bool { 147 t, ok := e.Error.(temporary) 148 return ok && t.Temporary() 149 } 150 151 type timeout interface { 152 Timeout() bool 153 } 154 155 func (e *OpError) Timeout() bool { 156 t, ok := e.Error.(timeout) 157 return ok && t.Timeout() 158 } 159 160 type AddrError struct { 161 Error string 162 Addr string 163 } 164 165 func (e *AddrError) String() string { 166 if e == nil { 167 return "<nil>" 168 } 169 s := e.Error 170 if e.Addr != "" { 171 s += " " + e.Addr 172 } 173 return s 174 } 175 176 func (e *AddrError) Temporary() bool { 177 return false 178 } 179 180 func (e *AddrError) Timeout() bool { 181 return false 182 } 183 184 type UnknownNetworkError string 185 186 func (e UnknownNetworkError) String() string { return "unknown network " + string(e) } 187 func (e UnknownNetworkError) Temporary() bool { return false } 188 func (e UnknownNetworkError) Timeout() bool { return false }