libgo/go/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 }