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 // 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 "errors"
  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 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 error)
  31
  32         // Close closes the connection.
  33         Close() 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) 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) 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) error
  56 }
  57
  58 // An Error represents a network error.
  59 type Error interface {
  60         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 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 error)
  82
  83         // Close closes the connection.
  84         Close() 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) 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) 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) 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 error)
 110
 111         // Close closes the listener.
 112         Close() error
 113
 114         // Addr returns the listener's network address.
 115         Addr() Addr
 116 }
 117
 118 var errMissingAddress = errors.New("missing address")
 119
 120 type OpError struct {
 121         Op   string
 122         Net  string
 123         Addr Addr
 124         Err  error
 125 }
 126
 127 func (e *OpError) Error() 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.Err.Error()
 139         return s
 140 }
 141
 142 type temporary interface {
 143         Temporary() bool
 144 }
 145
 146 func (e *OpError) Temporary() bool {
 147         t, ok := e.Err.(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.Err.(timeout)
 157         return ok && t.Timeout()
 158 }
 159
 160 type timeoutError struct{}
 161
 162 func (e *timeoutError) Error() string   { return "i/o timeout" }
 163 func (e *timeoutError) Timeout() bool   { return true }
 164 func (e *timeoutError) Temporary() bool { return true }
 165
 166 var errTimeout error = &timeoutError{}
 167
 168 type AddrError struct {
 169         Err  string
 170         Addr string
 171 }
 172
 173 func (e *AddrError) Error() string {
 174         if e == nil {
 175                 return "<nil>"
 176         }
 177         s := e.Err
 178         if e.Addr != "" {
 179                 s += " " + e.Addr
 180         }
 181         return s
 182 }
 183
 184 func (e *AddrError) Temporary() bool {
 185         return false
 186 }
 187
 188 func (e *AddrError) Timeout() bool {
 189         return false
 190 }
 191
 192 type UnknownNetworkError string
 193
 194 func (e UnknownNetworkError) Error() string   { return "unknown network " + string(e) }
 195 func (e UnknownNetworkError) Temporary() bool { return false }
 196 func (e UnknownNetworkError) Timeout() bool   { return false }