src/sockets/base-sockets.lisp

   1 ;;;; -*- Mode: Lisp; indent-tabs-mode: nil -*-
   2 ;;;
   3 ;;; --- Base socket classes.
   4 ;;;
   5
   6 (in-package :iolib.sockets)
   7
   8 ;;;; Sockets
   9
  10 (defclass socket (dual-channel-fd-mixin)
  11   ((address-family :initarg :address-family :accessor socket-address-family)
  12    (protocol :initarg :protocol :accessor socket-protocol)
  13    (bound    :initform nil      :reader   socket-bound-p :type boolean))
  14   (:documentation "Base class for sockets."))
  15 (unset-method-docstring #'socket-address-family () '(socket))
  16 (set-function-docstring 'socket-address-family "Return the address family of a socket.")
  17 (unset-method-docstring #'socket-protocol () '(socket))
  18 (set-function-docstring 'socket-protocol "Return the protocol of a socket.")
  19
  20 (defgeneric make-socket (&key address-family type connect ipv6 external-format
  21                               &allow-other-keys)
  22   (:documentation "Create an instance of a subclass of SOCKET. ADDRESS-FAMILY, TYPE, CONNECT and IPV6
  23 are used to specify the kind of socket to create.
  24
  25 * ADDRESS-FAMILY - :INTERNET, :LOCAL (or :FILE as synonim), or :NETLINK(on Linux)
  26 * TYPE - :STREAM, :DATAGRAM or :RAW
  27 * CONNECT - :ACTIVE or :PASSIVE
  28 * IPV6 - if NIL, create an IPv4 socket, otherwise an IPv6 socket.
  29
  30 To initialize the socket, the following keyword arguments can be used depending on ADDRESS-FAMILY, TYPE and CONNECT:
  31 * :local-host - a hostname designator or NIL. If non-null the socket will be bound to this address
  32 * :local-port - a port designator or NIL. If LOCAL-HOST is non-null, bind the socket to this port. If NIL, choose a random port
  33 * :remote-host - a hostname designator or NIL. If non-null the socket will be connected to this address
  34 * :remote-port - a port designator. If REMOTE-HOST is non-null, connect the socket to this port
  35 * :local-filename - a string or NIL. If non-null the socket will be bound to this file
  36 * :remote-filename - a string or NIL. If non-null the socket will be connected to this file
  37 * :backlog - a positive integer or NIL. Specifies the length of the incomming connection queue and can't be larger than +MAX-BACKLOG-SIZE+. If NIL, default is *DEFAULT-BACKLOG-SIZE*
  38 * :reuse-address: a boolean(default T). set option SO_REUSEADDR if LOCAL-HOST is non-null
  39 * :keepalive - a boolean. set option SO_KEEPALIVE
  40 * :nodelay - a boolean. set option SO_NODELAY
  41 * :interface - a string. set option SO_BINDTODEVICE to this interface
  42 * :input-buffer-size - a positive integer. Create the stream input buffer of this size
  43 * :output-buffer-size - a positive integer. Create the stream output buffer of this size
  44 * :multicast-groups - a non-negative integer. Accept messages sent to those multicast groups
  45
  46 Glossary:
  47 * hostname designator: an instance of INET-ADDRESS or any object accepted by LOOKUP-HOST. IPV6 is passed to LOOKUP-HOST as is
  48 * port designator: any object accepted by LOOKUP-SERVICE
  49
  50 :address-family :INTERNET :type :STREAM :connect :ACTIVE
  51 * Valid keyword args: :LOCAL-HOST, :LOCAL-PORT, :REMOTE-HOST, :REMOTE-PORT, :REUSE-ADDRESS, :KEEPALIVE, :NODELAY, :INPUT-BUFFER-SIZE and :OUTPUT-BUFFER-SIZE
  52
  53 :address-family :INTERNET :type :STREAM :connect :PASSIVE
  54 * Valid keyword args: :LOCAL-HOST, :LOCAL-PORT, :BACKLOG, :REUSE-ADDRESS, :INTERFACE and :NODELAY
  55
  56 :address-family :INTERNET :type :STREAM :connect :ACTIVE
  57 * Valid keyword args: :LOCAL-FILENAME, :REMOTE-FILENAME, :INPUT-BUFFER-SIZE and :OUTPUT-BUFFER-SIZE
  58
  59 :address-family :INTERNET :type :STREAM :connect :PASSIVE
  60 * Valid keyword args: :LOCAL-FILENAME, :REMOTE-FILENAME, :BACKLOG and :REUSE-ADDRESS
  61
  62 :address-family :INTERNET :type :DATAGRAM
  63 * Valid keyword args: :LOCAL-HOST, :LOCAL-PORT, :REMOTE-HOST, :REMOTE-PORT, :REUSE-ADDRESS, :INTERFACE and :BROADCAST
  64
  65 :address-family :LOCAL :type :DATAGRAM
  66 * Valid keyword args: :LOCAL-FILENAME and :REMOTE-FILENAME
  67
  68 :address-family :INTERNET :type :RAW
  69 * Valid keyword args: :INCLUDE-HEADERS
  70
  71 :address-family :NETLINK :type :RAW
  72 * Valid keyword args: :LOCAL-PORT and :MULTICAST-GROUPS"))
  73
  74 (defgeneric make-socket-from-fd (fd &key dup connect external-format
  75                                     input-buffer-size output-buffer-size)
  76   (:documentation "Create a socket instance of the appropriate subclass of SOCKET using FD.
  77 The connection type of the socket must be specified - :ACTIVE or :PASSIVE.
  78 The address family and type of the socket are automatically discovered using OS functions. Buffer sizes
  79 for the new socket can also be specified using INPUT-BUFFER-SIZE and OUTPUT-BUFFER-SIZE."))
  80
  81 (defgeneric make-socket-pair (&key type protocol external-format
  82                                    input-buffer-size output-buffer-size)
  83   (:documentation "Create a pair of sockets connected to each other.
  84 The socket type must be either :STREAM or :DATAGRAM. Currently OSes can only create :LOCAL sockets this way.
  85 Buffer sizes for the new sockets can also be specified using INPUT-BUFFER-SIZE and OUTPUT-BUFFER-SIZE."))
  86
  87 (defgeneric socket-os-fd (socket)
  88   (:documentation "Returns the OS file descriptor of SOCKET."))
  89
  90 (defgeneric socket-type (socket)
  91   (:documentation "Returns the socket type of SOCKET - :STREAM or :DATAGRAM."))
  92
  93 (defgeneric socket-open-p (socket)
  94   (:documentation "Returns a boolean indicating whether or not the file descriptor of SOCKET is open."))
  95
  96 (defgeneric local-name (socket)
  97   (:documentation "For INTERNET sockets, returns two values: the local host and the local port.
  98 For LOCAL sockets, returns the local filename."))
  99
 100 (defgeneric local-host (socket)
 101   (:documentation "Returns the local host of SOCKET.
 102 Works only on INTERNET sockets."))
 103
 104 (defgeneric local-port (socket)
 105   (:documentation "Returns the local port of SOCKET - an (UNSIGNED-BYTE 16).
 106 Works only on INTERNET sockets."))
 107
 108 (defgeneric local-filename (socket)
 109   (:documentation "Returns the local filename of SOCKET.
 110 Works only on LOCAL sockets."))
 111
 112 (defgeneric remote-name (socket)
 113   (:documentation "For INTERNET sockets, returns two values: the remote host and the remote port.
 114 For REMOTE sockets, returns the remote filename."))
 115
 116 (defgeneric remote-host (socket)
 117   (:documentation "Returns the remote host of SOCKET.
 118 Works only on INTERNET sockets."))
 119
 120 (defgeneric remote-port (socket)
 121   (:documentation "Returns the remote port of SOCKET - an (UNSIGNED-BYTE 16).
 122 Works only on INTERNET sockets."))
 123
 124 (defgeneric remote-filename (socket)
 125   (:documentation "Returns the remote filename of SOCKET.
 126 Works only on LOCAL sockets."))
 127
 128 (defgeneric socket-option (socket option-name)
 129   (:documentation "Returns the value(s) of OS option OPTION-NAME on SOCKET.
 130 For a complete list of supported options see src/sockets/socket-options.lisp."))
 131
 132 (defclass stream-socket (socket) ()
 133   (:default-initargs :type :stream)
 134   (:documentation "Mixin for sockets of type SOCK_STREAM."))
 135
 136 (defclass datagram-socket (socket) ()
 137   (:default-initargs :type :datagram)
 138   (:documentation "Mixin for sockets of type SOCK_DGRAM."))
 139
 140 (defclass raw-socket (socket) ()
 141   (:default-initargs :type :raw)
 142   (:documentation "Mixin for sockets of type SOCK_RAW."))
 143
 144 (defgeneric disconnect (socket)
 145   (:documentation "Disassociates SOCKET from any remote address.
 146 Works only on DATAGRAM sockets."))
 147
 148 (define-symbol-macro +default-inet-address-family+
 149   (if *ipv6* :ipv6 :ipv4))
 150
 151 (defclass internet-socket (socket) ()
 152   (:default-initargs :address-family +default-inet-address-family+)
 153   (:documentation "Mixin for sockets of domain AF_INET or AF_INET6."))
 154
 155 (defclass local-socket (socket) ()
 156   (:default-initargs :address-family :local)
 157   (:documentation "Mixin for sockets of domain AF_LOCAL."))
 158
 159 (defclass netlink-socket (socket) ()
 160   (:default-initargs :address-family :netlink)
 161   (:documentation "Mixin for sockets of domain AF_NETLINK."))
 162
 163 (defgeneric send-file-descriptor (socket file-descriptor)
 164   (:documentation "Send FILE-DESCRIPTOR through SOCKET.
 165 The receiving process must use RECEIVE-FILE-DESCRIPTOR to receive the
 166 file descriptor in order for it to be valid in the receiving process."))
 167
 168 (defgeneric receive-file-descriptor (socket)
 169   (:documentation "Receive a file descriptor as ancillary data through SOCKET."))
 170
 171 (defun socket-read-fn (fd buffer nbytes)
 172   (debug-only
 173     (assert buffer)
 174     (assert fd))
 175   (%recvfrom fd buffer nbytes 0 (null-pointer) (null-pointer)))
 176
 177 (defun socket-write-fn (fd buffer nbytes)
 178   (debug-only
 179     (assert buffer)
 180     (assert fd))
 181   (%sendto fd buffer nbytes 0 (null-pointer) 0))
 182
 183 (defclass active-socket (socket dual-channel-gray-stream) ()
 184   (:default-initargs :read-fn #'socket-read-fn
 185                      :write-fn #'socket-write-fn)
 186   (:documentation "Mixin class for active(client) sockets."))
 187
 188 (defgeneric connect (socket address &key &allow-other-keys)
 189   (:documentation "Connects SOCKET to ADDRESS. For INTERNET sockets you can specify
 190 the port to connect to using keyword argument PORT. The default value of PORT is 0,
 191 which usually means letting the OS choose a random port to connect to.
 192 WAIT specifies how long to wait for a connection: NIL means \"return immediately\", a non-negative real
 193 specifies a timeout in seconds and T means \"wait forever\"."))
 194
 195 (defgeneric socket-connected-p (socket)
 196   (:documentation "Returns a boolean specifying whether or not SOCKET is connected."))
 197
 198 (defgeneric shutdown (socket &key read write)
 199   (:documentation "Shut down all or part of a connection. If READ it non-NIL, further receptions are
 200 disallowed; if WRITE is non-NIL, further transmissions are disallowed. CLOSE must still be called on
 201 SOCKET in order to release OS resources."))
 202
 203 (defgeneric receive-from (socket &rest args &key &allow-other-keys)
 204   (:documentation "Receives data from SOCKET. If BUFFER is specified
 205 START and END are used as bounding index. In that case BUFFER must be
 206 an array and its ARRAY-ELEMENT-TYPE be either (UNSIGNED-BYTE 8) or T.
 207 If BUFFER is not specified an (UNSIGNED-BYTE 8) buffer of size SIZE
 208 will be allocated.
 209
 210 Some flags can also be passed to recvfrom(2):
 211 * :OUT-OF-BAND for receiving out-of-band data - only for STREAM sockets
 212 * :PEEK for keeping the returned data in the kernel buffers
 213 * :WAIT-ALL for waiting until the entire buffer can be filled
 214 * :DONT-WAIT for making only the current call non-blocking
 215
 216 The first two values returned are the buffer and the number of elements that have been copied into the buffer.
 217 For INTERNET DATAGRAM sockets, two additional values are returned: the host and port of the remote peer
 218 from which the data was received.
 219 For LOCAL DATAGRAM sockets, one additional values is returned: the filename of the remote peer
 220 from which the data was received."))
 221
 222 (defgeneric send-to (socket buffer &rest args &key &allow-other-keys)
 223   (:documentation "Send the contents of BUFFER to SOCKET.
 224 BUFFER must be a vector that can be coerced to a (SIMPLE-ARRAY (UNSIGNED-BYTE 8) (*)).
 225 START and END are used a bounding index on BUFFER.
 226 For disconnected datagram sockets, REMOTE-HOST and REMOTE-PORT or REMOTE-FILENAME are used
 227 as destination for the data.
 228
 229 Some flags can also be passed to sendto(2):
 230 * :OUT-OF-BAND for receiving out-of-band data - only for stream sockets
 231 * :DONT-WAIT for making only the current call non-blocking
 232 * :DONT-ROUTE for sending only to hosts on directly connected networks, not using gateways
 233 * :CONFIRM for signalling progress on the link layer - only available on Linux and only with DATAGRAM sockets
 234 * :MORE for telling the kernel that there is more data to send - only available on Linux
 235
 236 Returns the number of bytes sent."))
 237
 238 (defclass passive-socket (socket)
 239   ((listening :initform nil :reader socket-listening-p :type boolean)
 240    (external-format :initarg :external-format :reader external-format-of)
 241    (active-class :initarg :active-class :reader active-class
 242                  :type symbol :allocation :class))
 243   (:default-initargs :external-format :default)
 244   (:documentation "Mixin class for PASSIVE(server) sockets."))
 245
 246 (defgeneric bind-address (socket address &key &allow-other-keys)
 247   (:documentation "Sets the local address of SOCKET to ADDRESS(and PORT for INTERNET sockets).
 248 REUSE-ADDRESS sets the SO_REUSEADDR socket option on SOCKET."))
 249
 250 (defgeneric listen-on (socket &key &allow-other-keys)
 251   (:documentation "Start allowing incoming connections on SOCKET.
 252 BACKLOG specifies the maximum length of the queue of pending connections."))
 253
 254 (defgeneric accept-connection (passive-socket &key &allow-other-keys)
 255   (:documentation "Extracts the first connection from the queue of pending connections on SOCKET.
 256 WAIT specifies how long to wait for a connection: NIL means \"return immediately\", a non-negative real
 257 specifies a timeout in seconds and T means \"wait forever\".
 258 EXTERNAL-FORMAT optionally specifies the external format of the new socket - the default being
 259 that of SOCKET. Buffer sizes for the new socket can also be specified using INPUT-BUFFER-SIZE
 260 and OUTPUT-BUFFER-SIZE.
 261 If a connection is received, returns two or three values: the newly created socket, the remote peer
 262 address and the remote port if applicable."))
 263
 264 (defclass socket-stream-internet-active
 265     (active-socket stream-socket internet-socket) ()
 266   (:documentation "Class representing active sockets of type SOCK_STREAM and domain AF_INET or AF_INET6."))
 267
 268 (defclass socket-stream-internet-passive
 269     (passive-socket stream-socket internet-socket) ()
 270   (:default-initargs :active-class 'socket-stream-internet-active)
 271   (:documentation "Class representing passive sockets of type SOCK_STREAM and domain AF_INET or AF_INET6."))
 272
 273 (defclass socket-stream-local-active
 274     (active-socket stream-socket local-socket) ()
 275   (:documentation "Class representing active sockets of type SOCK_STREAM and domain AF_LOCAL."))
 276
 277 (defclass socket-stream-local-passive
 278     (passive-socket stream-socket local-socket) ()
 279   (:default-initargs :active-class 'socket-stream-local-active)
 280   (:documentation "Class representing passive sockets of type SOCK_STREAM and domain AF_LOCAL."))
 281
 282 (defclass socket-datagram-internet
 283     (datagram-socket internet-socket) ()
 284   (:documentation "Class representing active sockets of type SOCK_DGRAM and domain AF_INET or AF_INET6."))
 285
 286 (defclass socket-datagram-local
 287     (datagram-socket local-socket) ()
 288   (:documentation "Class representing active sockets of type SOCK_DGRAM and domain AF_LOCAL."))
 289
 290 (defclass socket-raw-internet
 291     (internet-socket raw-socket) ()
 292   (:default-initargs :type :raw)
 293   (:documentation "Class representing active sockets of type SOCK_RAW and domain AF_LOCAL."))
 294
 295 (defclass socket-raw-netlink
 296     (netlink-socket raw-socket) ()
 297   (:default-initargs :type :raw)
 298   (:documentation "Class representing active sockets of type SOCK_RAW and domain AF_NETLINK."))