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.
6 Package net provides a portable interface for network I/O, including
7 TCP/IP, UDP, domain name resolution, and Unix domain sockets.
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.
15 The Dial function connects to a server:
17 conn, err := net.Dial("tcp", "google.com:80")
21 fmt.Fprintf(conn, "GET / HTTP/1.0\r\n\r\n")
22 status, err := bufio.NewReader(conn).ReadString('\n')
25 The Listen function creates servers:
27 ln, err := net.Listen("tcp", ":8080")
32 conn, err := ln.Accept()
37 go handleConnection(conn)
43 // support for raw ethernet sockets
53 // Addr represents a network end point address.
55 Network() string // name of the network
56 String() string // string form of address
59 // Conn is a generic stream-oriented network connection.
61 // Multiple goroutines may invoke methods on a Conn simultaneously.
63 // Read reads data from the connection.
64 // Read can be made to time out and return a Error with Timeout() == true
65 // after a fixed time limit; see SetDeadline and SetReadDeadline.
66 Read(b
[]byte) (n
int, err error
)
68 // Write writes data to the connection.
69 // Write can be made to time out and return a Error with Timeout() == true
70 // after a fixed time limit; see SetDeadline and SetWriteDeadline.
71 Write(b
[]byte) (n
int, err error
)
73 // Close closes the connection.
74 // Any blocked Read or Write operations will be unblocked and return errors.
77 // LocalAddr returns the local network address.
80 // RemoteAddr returns the remote network address.
83 // SetDeadline sets the read and write deadlines associated
84 // with the connection. It is equivalent to calling both
85 // SetReadDeadline and SetWriteDeadline.
87 // A deadline is an absolute time after which I/O operations
88 // fail with a timeout (see type Error) instead of
89 // blocking. The deadline applies to all future I/O, not just
90 // the immediately following call to Read or Write.
92 // An idle timeout can be implemented by repeatedly extending
93 // the deadline after successful Read or Write calls.
95 // A zero value for t means I/O operations will not time out.
96 SetDeadline(t time
.Time
) error
98 // SetReadDeadline sets the deadline for future Read calls.
99 // A zero value for t means Read will not time out.
100 SetReadDeadline(t time
.Time
) error
102 // SetWriteDeadline sets the deadline for future Write calls.
103 // Even if write times out, it may return n > 0, indicating that
104 // some of the data was successfully written.
105 // A zero value for t means Write will not time out.
106 SetWriteDeadline(t time
.Time
) error
113 func (c
*conn
) ok() bool { return c
!= nil && c
.fd
!= nil }
115 // Implementation of the Conn interface.
117 // Read implements the Conn Read method.
118 func (c
*conn
) Read(b
[]byte) (int, error
) {
120 return 0, syscall
.EINVAL
125 // Write implements the Conn Write method.
126 func (c
*conn
) Write(b
[]byte) (int, error
) {
128 return 0, syscall
.EINVAL
133 // Close closes the connection.
134 func (c
*conn
) Close() error
{
136 return syscall
.EINVAL
141 // LocalAddr returns the local network address.
142 func (c
*conn
) LocalAddr() Addr
{
149 // RemoteAddr returns the remote network address.
150 func (c
*conn
) RemoteAddr() Addr
{
157 // SetDeadline implements the Conn SetDeadline method.
158 func (c
*conn
) SetDeadline(t time
.Time
) error
{
160 return syscall
.EINVAL
162 return c
.fd
.setDeadline(t
)
165 // SetReadDeadline implements the Conn SetReadDeadline method.
166 func (c
*conn
) SetReadDeadline(t time
.Time
) error
{
168 return syscall
.EINVAL
170 return c
.fd
.setReadDeadline(t
)
173 // SetWriteDeadline implements the Conn SetWriteDeadline method.
174 func (c
*conn
) SetWriteDeadline(t time
.Time
) error
{
176 return syscall
.EINVAL
178 return c
.fd
.setWriteDeadline(t
)
181 // SetReadBuffer sets the size of the operating system's
182 // receive buffer associated with the connection.
183 func (c
*conn
) SetReadBuffer(bytes
int) error
{
185 return syscall
.EINVAL
187 return setReadBuffer(c
.fd
, bytes
)
190 // SetWriteBuffer sets the size of the operating system's
191 // transmit buffer associated with the connection.
192 func (c
*conn
) SetWriteBuffer(bytes
int) error
{
194 return syscall
.EINVAL
196 return setWriteBuffer(c
.fd
, bytes
)
199 // File sets the underlying os.File to blocking mode and returns a copy.
200 // It is the caller's responsibility to close f when finished.
201 // Closing c does not affect f, and closing f does not affect c.
203 // The returned os.File's file descriptor is different from the connection's.
204 // Attempting to change properties of the original using this duplicate
205 // may or may not have the desired effect.
206 func (c
*conn
) File() (f
*os
.File
, err error
) { return c
.fd
.dup() }
208 // An Error represents a network error.
209 type Error
interface {
211 Timeout() bool // Is the error a timeout?
212 Temporary() bool // Is the error temporary?
215 // PacketConn is a generic packet-oriented network connection.
217 // Multiple goroutines may invoke methods on a PacketConn simultaneously.
218 type PacketConn
interface {
219 // ReadFrom reads a packet from the connection,
220 // copying the payload into b. It returns the number of
221 // bytes copied into b and the return address that
222 // was on the packet.
223 // ReadFrom can be made to time out and return
224 // an error with Timeout() == true after a fixed time limit;
225 // see SetDeadline and SetReadDeadline.
226 ReadFrom(b
[]byte) (n
int, addr Addr
, err error
)
228 // WriteTo writes a packet with payload b to addr.
229 // WriteTo can be made to time out and return
230 // an error with Timeout() == true after a fixed time limit;
231 // see SetDeadline and SetWriteDeadline.
232 // On packet-oriented connections, write timeouts are rare.
233 WriteTo(b
[]byte, addr Addr
) (n
int, err error
)
235 // Close closes the connection.
236 // Any blocked ReadFrom or WriteTo operations will be unblocked and return errors.
239 // LocalAddr returns the local network address.
242 // SetDeadline sets the read and write deadlines associated
243 // with the connection.
244 SetDeadline(t time
.Time
) error
246 // SetReadDeadline sets the deadline for future Read calls.
247 // If the deadline is reached, Read will fail with a timeout
248 // (see type Error) instead of blocking.
249 // A zero value for t means Read will not time out.
250 SetReadDeadline(t time
.Time
) error
252 // SetWriteDeadline sets the deadline for future Write calls.
253 // If the deadline is reached, Write will fail with a timeout
254 // (see type Error) instead of blocking.
255 // A zero value for t means Write will not time out.
256 // Even if write times out, it may return n > 0, indicating that
257 // some of the data was successfully written.
258 SetWriteDeadline(t time
.Time
) error
261 var listenerBacklog
= maxListenerBacklog()
263 // A Listener is a generic network listener for stream-oriented protocols.
265 // Multiple goroutines may invoke methods on a Listener simultaneously.
266 type Listener
interface {
267 // Accept waits for and returns the next connection to the listener.
268 Accept() (c Conn
, err error
)
270 // Close closes the listener.
271 // Any blocked Accept operations will be unblocked and return errors.
274 // Addr returns the listener's network address.
278 // Various errors contained in OpError.
280 // For connection setup and write operations.
281 errMissingAddress
= errors
.New("missing address")
283 // For both read and write operations.
284 errTimeout error
= &timeoutError
{}
285 errClosing
= errors
.New("use of closed network connection")
286 ErrWriteToConnected
= errors
.New("use of WriteTo with pre-connected connection")
289 // OpError is the error type usually returned by functions in the net
290 // package. It describes the operation, network type, and address of
292 type OpError
struct {
293 // Op is the operation which caused the error, such as
294 // "read" or "write".
297 // Net is the network type on which this error occurred,
298 // such as "tcp" or "udp6".
301 // Addr is the network address on which this error occurred.
304 // Err is the error that occurred during the operation.
308 func (e
*OpError
) Error() string {
317 s
+= " " + e
.Addr
.String()
319 s
+= ": " + e
.Err
.Error()
323 type temporary
interface {
327 func (e
*OpError
) Temporary() bool {
328 t
, ok
:= e
.Err
.(temporary
)
329 return ok
&& t
.Temporary()
332 var noDeadline
= time
.Time
{}
334 type timeout
interface {
338 func (e
*OpError
) Timeout() bool {
339 t
, ok
:= e
.Err
.(timeout
)
340 return ok
&& t
.Timeout()
343 type timeoutError
struct{}
345 func (e
*timeoutError
) Error() string { return "i/o timeout" }
346 func (e
*timeoutError
) Timeout() bool { return true }
347 func (e
*timeoutError
) Temporary() bool { return true }
349 type AddrError
struct {
354 func (e
*AddrError
) Error() string {
365 func (e
*AddrError
) Temporary() bool {
369 func (e
*AddrError
) Timeout() bool {
373 type UnknownNetworkError
string
375 func (e UnknownNetworkError
) Error() string { return "unknown network " + string(e
) }
376 func (e UnknownNetworkError
) Temporary() bool { return false }
377 func (e UnknownNetworkError
) Timeout() bool { return false }
379 type InvalidAddrError
string
381 func (e InvalidAddrError
) Error() string { return string(e
) }
382 func (e InvalidAddrError
) Timeout() bool { return false }
383 func (e InvalidAddrError
) Temporary() bool { return false }
385 // DNSConfigError represents an error reading the machine's DNS configuration.
386 type DNSConfigError
struct {
390 func (e
*DNSConfigError
) Error() string {
391 return "error reading DNS config: " + e
.Err
.Error()
394 func (e
*DNSConfigError
) Timeout() bool { return false }
395 func (e
*DNSConfigError
) Temporary() bool { return false }
397 type writerOnly
struct {
401 // Fallback implementation of io.ReaderFrom's ReadFrom, when sendfile isn't
403 func genericReadFrom(w io
.Writer
, r io
.Reader
) (n
int64, err error
) {
404 // Use wrapper to hide existing r.ReadFrom from io.Copy.
405 return io
.Copy(writerOnly
{w
}, r
)
408 // Limit the number of concurrent cgo-using goroutines, because
409 // each will block an entire operating system thread. The usual culprit
410 // is resolving many DNS names in separate goroutines but the DNS
411 // server is not responding. Then the many lookups each use a different
412 // thread, and the system or the program runs out of threads.
414 var threadLimit
= make(chan struct{}, 500)
416 // Using send for acquire is fine here because we are not using this
417 // to protect any memory. All we care about is the number of goroutines
418 // making calls at a time.
420 func acquireThread() {
421 threadLimit
<- struct{}{}
424 func releaseThread() {