— Generic Function: sockets:make-socket &key address-family type connect ipv6 external-format address-family type connect ipv6 external-format &allow-other-keys

Create an instance of a subclass of socket. address-family, type, connect and IPV6 are used to specify the kind of socket to create.

• address-family - :internet or :local (or :file as synonim)
• type - :stream or :datagram
• connect - :active or :passive
• IPV6 - if nil, create an IPv4 socket, otherwise an IPv6 socket.

To initialize the socket, the following keyword arguments can be used depending on address-family, type and connect:

• :local-host - a hostname designator or nil. If non-null the socket will be bound to this address
• :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
• :remote-host - a hostname designator or nil. If non-null the socket will be connected to this address
• :remote-port - a port designator. If remote-host is non-null, connect the socket to this port
• :local-filename - a string or nil. If non-null the socket will be bound to this file
• :remote-filename - a string or nil. If non-null the socket will be connected to this file
• :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*
• :reuse-address: a boolean(default T). set option SO_REUSEADDR if local-host is non-null
• :keepalive - a boolean. set option SO_KEEPALIVE
• :nodelay - a boolean. set option SO_NODELAY
• :interface - a string. set option SO_BINDTODEVICE to this interface
• :input-buffer-size - a positive integer. Create the stream input buffer of this size
• :output-buffer-size - a positive integer. Create the stream output buffer of this size

Glossary:

• hostname designator: an instance of inet-address or any object accepted by lookup-host. IPV6 is passed to lookup-host as is
• port designator: any object accepted by lookup-service

:address-family :internet :type :stream :connect :active

• Valid keyword args: :local-host, :local-port, :remote-host, :remote-port, :reuse-address, :keepalive, :nodelay, :input-buffer-size and :output-buffer-size

:address-family :internet :type :stream :connect :passive

• Valid keyword args: :local-host, :local-port, :backlog, :reuse-address, :interface and :nodelay

:address-family :internet :type :stream :connect :active

• Valid keyword args: :local-filename, :remote-filename, :input-buffer-size and :output-buffer-size

:address-family :internet :type :stream :connect :passive

• Valid keyword args: :local-filename, :remote-filename, :backlog and :reuse-address

:address-family :internet :type :datagram

• Valid keyword args: :local-host, :local-port, :remote-host, :remote-port, :reuse-address, :interface and :broadcast

:address-family :local :type :datagram

• Valid keyword args: :local-filename and :remote-filename

— Macro: sockets:with-open-socket (var &rest args) &body body

Bind var to a socket created by passing args to make-socket and execute body as implicit progn. The socket is automatically closed upon exit.

— Generic Function: sockets:make-socket-from-fd fd &key connect external-format input-buffer-size output-buffer-size connect external-format

Create a socket instance of the appropriate subclass of socket using fd. The connection type of the socket must be specified - :active or :passive. The address family and type of the socket are automatically discovered using os functions. Buffer sizes for the new socket can also be specified using input-buffer-size and output-buffer-size.

— Generic Function: sockets:make-socket-pair &key type protocol external-format input-buffer-size output-buffer-size type protocol external-format

Create a pair of sockets connected to each other. The socket type must be either :stream or :datagram. Currently OSes can only create :local sockets this way. Buffer sizes for the new sockets can also be specified using input-buffer-size and output-buffer-size.

— Generic Function: sockets:send-to socket buffer &rest args &key start end remote-filename flags remote-host remote-port ipv6 &allow-other-keys

Send the contents of buffer to socket. buffer must be a vector that can be coerced to a (SIMPLE-ARRAY (UNSIGNED-BYTE 8) (*)). start and end are used a bounding index on buffer. For disconnected datagram sockets, remote-host and remote-port or remote-filename are used as destination for the data.

Some flags can also be passed to sendto(2):

• :out-of-band for receiving out-of-band data - only for stream sockets
• :dont-wait for making only the current call non-blocking
• :dont-route for sending only to hosts on directly connected networks, not using gateways
• :confirm for signalling progress on the link layer - only available on Linux and only with datagram sockets
• :more for telling the kernel that there is more data to send - only available on Linux

Returns the number of bytes sent.

— Generic Function: sockets:receive-from socket &rest args &key flags end start buffer size &allow-other-keys

Receives data from socket. If buffer is specified start and end are used as bounding index. In that case buffer must be an array and its array-element-type be either (UNSIGNED-BYTE 8) or t. If buffer is not specified an (UNSIGNED-BYTE 8) buffer of size size will be allocated.

Some flags can also be passed to recvfrom(2):

• :out-of-band for receiving out-of-band data - only for stream sockets
• :peek for keeping the returned data in the kernel buffers
• :wait-all for waiting until the entire buffer can be filled
• :dont-wait for making only the current call non-blocking

The first two values returned are the buffer and the number of elements that have been copied into the buffer. For internet datagram sockets, two additional values are returned: the host and port of the remote peer from which the data was received. For local datagram sockets, one additional values is returned: the filename of the remote peer from which the data was received.

— Generic Function: sockets:bind-address socket address &key reuse-address port &allow-other-keys

Sets the local address of socket to ADDRESS(and port for internet sockets). reuse-address sets the SO_REUSEADDR socket option on socket.

— Generic Function: sockets:listen-on socket &key backlog &allow-other-keys

Start allowing incoming connections on socket. backlog specifies the maximum length of the queue of pending connections.

— Generic Function: sockets:accept-connection passive-socket &key timeout wait output-buffer-size input-buffer-size external-format &allow-other-keys

Returns one connection from the queue of pending connections on socket. If wait is true, waits until a connection is received or timeout expires in which case returns nil. If wait is false and there are no pending connections return nil. external-format optionally specifies the external format of the new socket - the default being that of socket. Buffer sizes for the new socket can also be specified using input-buffer-size and output-buffer-size.

— Macro: sockets:with-accept-connection (var passive-socket &rest args) &body body

Bind var to a socket created by passing passive-socket and args to accept-connection and execute body as implicit progn. The socket is automatically closed upon exit.

— Generic Function: sockets:connect socket address &key port wait timeout &allow-other-keys

Connects socket to address. For internet sockets you can specify the port to connect to using keyword argument port. The default value of port is 0, which usually means letting the os choose a random port to connect to. For internet sockets, if wait is true and a connection cannot be established within timeout seconds signal iomux:poll-timeout, but it works only with non-blocking sockets.

— Generic Function: sockets:disconnect socket

Disassociates socket from any remote address. Works only on datagram sockets.

— Generic Function: sockets:shutdown socket &key read write

Shut down all or part of a connection. If read it non-NIL, further receptions are disallowed; if write is non-NIL, further transmissions are disallowed. close must still be called on socket in order to release os resources.

— Generic Function: sockets:send-file-descriptor socket file-descriptor

Send file-descriptor through socket. The receiving process must use receive-file-descriptor to receive the file descriptor in order for it to be valid in the receiving process.

— Generic Function: sockets:receive-file-descriptor socket

Receive a file descriptor as ancillary data through socket.