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