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
50 // Addr represents a network end point address.
52 Network() string // name of the network
53 String() string // string form of address
56 // Conn is a generic stream-oriented network connection.
58 // Read reads data from the connection.
59 // Read can be made to time out and return a Error with Timeout() == true
60 // after a fixed time limit; see SetDeadline and SetReadDeadline.
61 Read(b []byte) (n int, err error)
63 // Write writes data to the connection.
64 // Write can be made to time out and return a Error with Timeout() == true
65 // after a fixed time limit; see SetDeadline and SetWriteDeadline.
66 Write(b []byte) (n int, err error)
68 // Close closes the connection.
71 // LocalAddr returns the local network address.
74 // RemoteAddr returns the remote network address.
77 // SetDeadline sets the read and write deadlines associated
78 // with the connection. It is equivalent to calling both
79 // SetReadDeadline and SetWriteDeadline.
81 // A deadline is an absolute time after which I/O operations
82 // fail with a timeout (see type Error) instead of
83 // blocking. The deadline applies to all future I/O, not just
84 // the immediately following call to Read or Write.
86 // An idle timeout can be implemented by repeatedly extending
87 // the deadline after successful Read or Write calls.
89 // A zero value for t means I/O operations will not time out.
90 SetDeadline(t time.Time) error
92 // SetReadDeadline sets the deadline for Read calls.
93 // A zero value for t means Read will not time out.
94 SetReadDeadline(t time.Time) error
96 // SetWriteDeadline sets the deadline for Write calls.
97 // Even if write times out, it may return n > 0, indicating that
98 // some of the data was successfully written.
99 // A zero value for t means Write will not time out.
100 SetWriteDeadline(t time.Time) error
103 // An Error represents a network error.
104 type Error interface {
106 Timeout() bool // Is the error a timeout?
107 Temporary() bool // Is the error temporary?
110 // PacketConn is a generic packet-oriented network connection.
111 type PacketConn interface {
112 // ReadFrom reads a packet from the connection,
113 // copying the payload into b. It returns the number of
114 // bytes copied into b and the return address that
115 // was on the packet.
116 // ReadFrom can be made to time out and return
117 // an error with Timeout() == true after a fixed time limit;
118 // see SetDeadline and SetReadDeadline.
119 ReadFrom(b []byte) (n int, addr Addr, err error)
121 // WriteTo writes a packet with payload b to addr.
122 // WriteTo can be made to time out and return
123 // an error with Timeout() == true after a fixed time limit;
124 // see SetDeadline and SetWriteDeadline.
125 // On packet-oriented connections, write timeouts are rare.
126 WriteTo(b []byte, addr Addr) (n int, err error)
128 // Close closes the connection.
131 // LocalAddr returns the local network address.
134 // SetDeadline sets the read and write deadlines associated
135 // with the connection.
136 SetDeadline(t time.Time) error
138 // SetReadDeadline sets the deadline for all Read calls to return.
139 // If the deadline is reached, Read will fail with a timeout
140 // (see type Error) instead of blocking.
141 // A zero value for t means Read will not time out.
142 SetReadDeadline(t time.Time) error
144 // SetWriteDeadline sets the deadline for all Write calls to return.
145 // If the deadline is reached, Write will fail with a timeout
146 // (see type Error) instead of blocking.
147 // A zero value for t means Write will not time out.
148 // Even if write times out, it may return n > 0, indicating that
149 // some of the data was successfully written.
150 SetWriteDeadline(t time.Time) error
153 // A Listener is a generic network listener for stream-oriented protocols.
154 type Listener interface {
155 // Accept waits for and returns the next connection to the listener.
156 Accept() (c Conn, err error)
158 // Close closes the listener.
161 // Addr returns the listener's network address.
165 var errMissingAddress = errors.New("missing address")
167 type OpError struct {
174 func (e *OpError) Error() string {
183 s += " " + e.Addr.String()
185 s += ": " + e.Err.Error()
189 type temporary interface {
193 func (e *OpError) Temporary() bool {
194 t, ok := e.Err.(temporary)
195 return ok && t.Temporary()
198 type timeout interface {
202 func (e *OpError) Timeout() bool {
203 t, ok := e.Err.(timeout)
204 return ok && t.Timeout()
207 type timeoutError struct{}
209 func (e *timeoutError) Error() string { return "i/o timeout" }
210 func (e *timeoutError) Timeout() bool { return true }
211 func (e *timeoutError) Temporary() bool { return true }
213 var errTimeout error = &timeoutError{}
215 type AddrError struct {
220 func (e *AddrError) Error() string {
231 func (e *AddrError) Temporary() bool {
235 func (e *AddrError) Timeout() bool {
239 type UnknownNetworkError string
241 func (e UnknownNetworkError) Error() string { return "unknown network " + string(e) }
242 func (e UnknownNetworkError) Temporary() bool { return false }
243 func (e UnknownNetworkError) Timeout() bool { return false }
245 // DNSConfigError represents an error reading the machine's DNS configuration.
246 type DNSConfigError struct {
250 func (e *DNSConfigError) Error() string {
251 return "error reading DNS config: " + e.Err.Error()
254 func (e *DNSConfigError) Timeout() bool { return false }
255 func (e *DNSConfigError) Temporary() bool { return false }