The usocket Reference Manual

Table of Contents

The usocket Reference Manual

This is the usocket Reference Manual, version 0.8.2, generated automatically by Declt version 2.4 patchlevel 1 "Will Decker" on Mon Jul 29 16:54:50 2019 GMT+0.

1 Introduction

USOCKET - Universal socket library for Common Lisp

https://common-lisp.net/project/usocket/

This is the usocket Common Lisp sockets library: a library to bring sockets access to the broadest of common lisp implementations as possible.

The library currently supports:

• Allegro CL
• ABCL (ArmedBear)
• Clasp
• Clozure CL
• Corman Lisp
• GNU CLISP
• CMUCL
• ECL
• LispWorks (4.3 and up)
• Digitool MCL and RMCL (5.0 and up)
• MOCL
• SBCL
• Scieneer CL
• Symbolics Genera

If your favorite common lisp misses in the list above, please contact usocket-devel@common-lisp.net and submit a request. Please include references to available sockets functions in your lisp implementation.

The library has been ASDF (http://cliki.net/ASDF) enabled, meaning that you can tar up a checkout and use that to ASDF-INSTALL:INSTALL the package in your system package site. (Or use your usual ASDF tricks to use the checkout directly.)

Remarks on licensing

Even though the source code has an MIT style license attached to it, when compiling this code with some of the supported lisp implementations you may not end up with an MIT style binary version due to the licensing of the implementations themselves. ECL is such an example and - when it will become supported - GCL is like that too.

Non-support of :external-format

Because of its definition in the hyperspec, there's no common external-format between lisp implementations: every vendor has chosen a different way to solve the problem of newline translation or character set recoding.

Because there's no way to avoid platform specific code in the application when using external-format, the purpose of a portability layer gets defeated. So, for now, usocket doesn't support external-format.

The workaround to get reasonably portable external-format support is to layer a flexi-stream (from flexi-streams) on top of a usocket stream.

API definition

• usocket (class)
• stream-usocket (class; usocket derivative)
• stream-server-usocket (class; usocket derivative)
• socket-connect (function) [ to create an active/connected socket ] socket-connect host port &key element-type where `host' is a vectorized ip or a string representation of a dotted ip address or a hostname for lookup in the DNS system
• socket-listen (function) [ to create a passive/listening socket ] socket-listen host port &key reuseaddress backlog element-type where `host' has the same definition as above
• socket-accept (method) [ to create an active/connected socket ] socket-accept socket &key element-type returns (server side) a connected socket derived from a listening/passive socket.
• socket-close (method) socket-close socket where socket a previously returned socket
• socket (usocket slot accessor), the internal/implementation defined socket representation
• socket-stream (usocket slot accessor), socket-stream socket the return value of which satisfies the normal stream interface
• socket-shutdown

Errors:

• address-in-use-error
• address-not-available-error
• bad-file-descriptor-error
• connection-refused-error
• connection-aborted-error
• connection-reset-error
• invalid-argument-error
• no-buffers-error
• operation-not-supported-error
• operation-not-permitted-error
• protocol-not-supported-error
• socket-type-not-supported-error
• network-unreachable-error
• network-down-error
• network-reset-error
• host-down-error
• host-unreachable-error
• shutdown-error
• timeout-error
• unkown-error

Non-fatal conditions:

• interrupted-condition
• unkown-condition

(for a description of the API methods and functions see https://common-lisp.net/project/usocket/api-docs.shtml)

Test suite

The test suite unfortunately isn't mature enough yet to run without some manual configuration. Several elements are required which are hard to programatically detect. Please adjust the test file before running the tests, for these variables:

• +non-existing-host+: The stringified IP address of a host on the same subnet. No physical host may be present.
• +unused-local-port+: A port number of a port not in use on the machine the tests run on.
• +common-lisp-net+: A vector with 4 integer elements which make up an IP address. This must be the IP "common-lisp.net" resolves to.

Known problems

• CMUCL error reporting wrt sockets raises only simple-errors meaning there's no way to tell different error conditions apart. All errors are mapped to unknown-error on CMUCL.

• The ArmedBear backend doesn't do any error mapping (yet). Java defines exceptions at the wrong level (IMO), since the exception reported bares a relation to the function failing, not the actual error that occurred: for example 'Address already in use' (when creating a passive socket) is reported as a BindException with an error text of 'Address already in use'. There's no way to sanely map 'BindException' to a meaningfull error in usocket. [This does not mean the backend should not at least map to 'unknown-error'!]

• When using the library with ECL, you need the C compiler installed to be able to compile and load the Foreign Function Interface. Not all ECL targets support DFFI yet, so on some targets this would be the case anyway. By depending on this technique, usocket can reuse the FFI code on all platforms (including Windows). This benefit currently outweighs the additional requirement. (hey, it's Embeddable Common Lisp, so, you probably wanted to embed it all along, right?)

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 usocket

3 Modules

Modules are listed depth-first from the system components tree.

3.1 usocket/vendor

3.2 usocket/backend

4 Files

Files are sorted by type and then listed depth-first from the systems components trees.

4.1 Lisp

4.1.1 usocket.asd

4.1.2 usocket/package.lisp

4.1.3 usocket/usocket.lisp

4.1.4 usocket/condition.lisp

4.1.5 usocket/backend/sbcl.lisp

4.1.6 usocket/option.lisp

5 Packages

Packages are listed by definition order.

5.1 usocket

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

6.1 Exported definitions

6.1.1 Constants

Constant: +max-datagram-packet-size+

The theoretical maximum amount of data in a UDP datagram.

The IPv4 UDP packets have a 16-bit length constraint, and IP+UDP header has 28-byte.

IP_MAXPACKET = 65535, /* netinet/ip.h */
sizeof(struct ip) = 20, /* netinet/ip.h */
sizeof(struct udphdr) = 8, /* netinet/udp.h */

65535 - 20 - 8 = 65507

(But for UDP broadcast, the maximum message size is limited by the MTU size of the underlying link)

6.1.2 Special variables

Special Variable: *auto-port*

Port number to pass when an auto-assigned port number is wanted.

Special Variable: *backend*

Special Variable: *version*

usocket version string

Special Variable: *wildcard-host*

Hostname to pass when all interfaces in the current system are to be bound. If this variable is passed to socket-listen, IPv6 capable systems will also listen for IPv6 connections.

6.1.3 Macros

Macro: ip-from-octet-buffer BUFFER &key START

Macro: ip-to-octet-buffer IP BUFFER &key START

Macro: port-from-octet-buffer BUFFER &key START

Macro: port-to-octet-buffer PORT BUFFER &key START

Macro: unimplemented FEATURE CONTEXT

Macro: unsupported FEATURE CONTEXT &key MINIMUM

Macro: with-client-socket (SOCKET-VAR STREAM-VAR &rest SOCKET-CONNECT-ARGS) &body BODY

Bind the socket resulting from a call to ‘socket-connect’ with
the arguments ‘socket-connect-args’ to ‘socket-var’ and if ‘stream-var’ is non-nil, bind the associated socket stream to it.

Macro: with-connected-socket (VAR SOCKET) &body BODY

Bind ‘socket’ to ‘var’, ensuring socket destruction on exit.

‘body’ is only evaluated when ‘var’ is bound to a non-null value.

The ‘body’ is an implied progn form.

Macro: with-mapped-conditions (&optional SOCKET HOST-OR-IP) &body BODY

Macro: with-server-socket (VAR SERVER-SOCKET) &body BODY

Bind ‘server-socket’ to ‘var’, ensuring socket destruction on exit.

‘body’ is only evaluated when ‘var’ is bound to a non-null value.

The ‘body’ is an implied progn form.

Macro: with-socket-listener (SOCKET-VAR &rest SOCKET-LISTEN-ARGS) &body BODY

Bind the socket resulting from a call to ‘socket-listen’ with arguments ‘socket-listen-args’ to ‘socket-var’.

6.1.4 Functions

Function: add-waiter WAIT-LIST INPUT

Function: datagram-usocket-p SOCKET

Function: dotted-quad-to-vector-quad STRING

Function: get-host-by-name NAME

0.7.1+: if there’re IPv4 addresses, return the first IPv4 address.

Function: get-hosts-by-name NAME

Function: get-random-host-by-name NAME

0.7.1+: if there’re IPv4 addresses, only return a random IPv4 address.

Function: hbo-to-dotted-quad INTEGER

Host-byte-order integer to dotted-quad string conversion utility.

Function: hbo-to-vector-quad INTEGER

Host-byte-order integer to dotted-quad string conversion utility.

Function: host-to-hostname HOST

Translate a string, vector quad or 16 byte IPv6 address to a stringified hostname.

Function: integer-to-octet-buffer INTEGER BUFFER OCTETS &key START

Function: ip/= IP1 IP2

Function: ip= IP1 IP2

Function: ipv6-host-to-vector STRING

Function: make-wait-list WAITERS

Function: octet-buffer-to-integer BUFFER OCTETS &key START

Function: remove-all-waiters WAIT-LIST

Function: remove-waiter WAIT-LIST INPUT

Function: socket-connect HOST PORT &key PROTOCOL ELEMENT-TYPE TIMEOUT DEADLINE NODELAY LOCAL-HOST LOCAL-PORT &aux SOCKOPT-TCP-NODELAY-P

Connect to ‘host’ on ‘port’. ‘host’ is assumed to be a string or
an IP address represented in vector notation, such as #(192 168 1 1).
‘port’ is assumed to be an integer.

‘element-type’ specifies the element type to use when constructing the
stream associated with the socket. The default is ’character.

‘nodelay’ Allows to disable/enable Nagle’s algorithm (http://en.wikipedia.org/wiki/Nagle%27s_algorithm). If this parameter is omitted, the behaviour is inherited from the
CL implementation (in most cases, Nagle’s algorithm is
enabled by default, but for example in ACL it is disabled).
If the parameter is specified, one of these three values is possible:
T - Disable Nagle’s algorithm; signals an UNSUPPORTED
condition if the implementation does not support explicit
manipulation with that option.
NIL - Leave Nagle’s algorithm enabled on the socket;
signals an UNSUPPORTED condition if the implementation does
not support explicit manipulation with that option.
:IF-SUPPORTED - Disables Nagle’s algorithm if the implementation
allows this, otherwises just ignore this option.

Returns a usocket object.

Function: socket-listen HOST PORT &key REUSEADDRESS REUSE-ADDRESS BACKLOG ELEMENT-TYPE

Bind to interface ‘host’ on ‘port’. ‘host’ should be the representation of an ready-interface address. The implementation is not required to do an address lookup, making no guarantees that hostnames will be correctly resolved. If ‘*wildcard-host*’ or NIL is passed for ‘host’, the socket will be bound to all available interfaces for the system. ‘port’ can be selected by the IP stack by passing ‘*auto-port*’.

Returns an object of type ‘stream-server-usocket’.

‘reuse-address’ and ‘backlog’ are advisory parameters for setting socket options at creation time. ‘element-type’ is the element type of the streams to be created by ‘socket-accept’. ‘reuseaddress’ is supported for backward compatibility (but deprecated); when both ‘reuseaddress’ and ‘reuse-address’ have been specified, the latter takes precedence.

Function: stream-server-usocket-p SOCKET

Function: stream-usocket-p SOCKET

Function: usocket-p SOCKET

Function: vector-quad-to-dotted-quad VECTOR

Function: vector-to-ipv6-host VECTOR

Function: wait-for-input SOCKET-OR-SOCKETS &key TIMEOUT READY-ONLY &aux SINGLE-SOCKET-P

Waits for one or more streams to become ready for reading from
the socket. When ‘timeout’ (a non-negative real number) is specified, wait ‘timeout’ seconds, or wait indefinitely when
it isn’t specified. A ‘timeout’ value of 0 (zero) means polling.

Returns two values: the first value is the list of streams which are readable (or in case of server streams acceptable). NIL may
be returned for this value either when waiting timed out or when
it was interrupted (EINTR). The second value is a real number indicating the time remaining within the timeout period or NIL if none.

Without the READY-ONLY arg, WAIT-FOR-INPUT will return all sockets in the original list you passed it. This prevents a new list from being consed up. Some users of USOCKET were reluctant to use it if it wouldn’t behave that way, expecting it to cost significant performance to do the associated garbage collection.

Without the READY-ONLY arg, you need to check the socket STATE slot for the values documented in usocket.lisp in the usocket class.

6.1.5 Generic functions

Generic Function: get-local-address SOCKET

Returns the IP address of the socket.

Generic Function: get-local-name SOCKET

Returns the IP address and port of the socket as values.

This function applies to both ‘stream-usocket’ and ‘server-stream-usocket’ type objects.

Generic Function: get-local-port SOCKET

Returns the IP port of the socket.

This function applies to both ‘stream-usocket’ and ‘server-stream-usocket’ type objects.

Generic Function: get-peer-address SOCKET

Returns the IP address of the peer the socket is connected to.

Generic Function: get-peer-name SOCKET

Returns the IP address and port of the peer the socket is connected to as values.

Generic Function: get-peer-port SOCKET

Returns the IP port of the peer the socket to.

Generic Function: host-byte-order ADDRESS

Generic Function: host-or-ip CONDITION

Generic Function: (setf host-or-ip) NEW-VALUE CONDITION

Generic Function: socket OBJECT

Generic Function: (setf socket) NEW-VALUE OBJECT

Generic Function: socket-accept SOCKET &key ELEMENT-TYPE

Accepts a connection from ‘socket’, returning a ‘stream-socket’.

The stream associated with the socket returned has ‘element-type’ when explicitly specified, or the element-type passed to ‘socket-listen’ otherwise.

Generic Function: socket-close USOCKET

Close a previously opened ‘usocket’.

Generic Function: socket-option SOCKET OPTION &key

Get a socket’s internal options

Generic Function: (setf socket-option) NEW-VALUE SOCKET OPTION &key

Set a socket’s internal options

Generic Function: socket-receive USOCKET BUFFER LENGTH &key ELEMENT-TYPE

Receive packets from a previously opend ‘usocket’.

Returns 4 values: (values buffer size host port)

Generic Function: socket-send USOCKET BUFFER LENGTH &key HOST PORT OFFSET

Send packets through a previously opend ‘usocket’.

Generic Function: socket-shutdown USOCKET DIRECTION

Shutdown communication on the socket in DIRECTION.

After a shutdown no input and/or output of the indicated DIRECTION can be performed on the ‘usocket’.

DIRECTION should be either :INPUT or :OUTPUT or :IO

Generic Function: socket-state SOCKET

NIL - not ready
:READ - ready to read :READ-WRITE - ready to read and write :WRITE - ready to write

Generic Function: socket-stream OBJECT

Generic Function: (setf socket-stream) NEW-VALUE OBJECT

6.1.6 Conditions

Condition: address-in-use-error ()

Condition: address-not-available-error ()

Condition: bad-file-descriptor-error ()

Condition: connection-aborted-error ()

Condition: connection-refused-error ()

Condition: connection-reset-error ()

Condition: deadline-timeout-error ()

Condition: host-down-error ()

Condition: host-unreachable-error ()

Condition: insufficient-implementation ()

The ancestor of all errors usocket may generate
because of insufficient support from the underlying implementation with respect to the arguments given to ‘function’.

One call may signal several errors, if the caller allows processing to continue.

Condition: interrupted-condition ()

Condition: invalid-argument-error ()

Condition: invalid-socket-error ()

Condition: invalid-socket-stream-error ()

Condition: network-down-error ()

Condition: network-reset-error ()

Condition: network-unreachable-error ()

Condition: no-buffers-error ()

Condition: ns-condition ()

Parent condition for all name resolution conditions.

Condition: ns-error ()

Parent error for all name resolution errors.

Condition: ns-host-not-found-error ()

Condition: ns-no-recovery-error ()

Condition: ns-try-again-condition ()

Condition: ns-unknown-condition ()

Condition raised when there’s no other - more applicable - condition available.

Condition: ns-unknown-error ()

Error raised when there’s no other - more applicable - error available.

Condition: operation-not-permitted-error ()

Condition: operation-not-supported-error ()

Condition: protocol-not-supported-error ()

Condition: shutdown-error ()

Condition: socket-condition ()

Parent condition for all socket related conditions.

Condition: socket-error ()

Parent error for all socket related errors

Condition: socket-type-not-supported-error ()

Condition: timeout-error ()

Condition: unimplemented ()

Signalled if a certain feature might be implemented,
based on the features of the underlying implementation, but hasn’t been implemented yet.

Condition: unknown-condition ()

Condition raised when there’s no other - more applicable - condition available.

Condition: unknown-error ()

Error raised when there’s no other - more applicable - error available.

Condition: unsupported ()

Signalled when the underlying implementation
doesn’t allow supporting the requested feature.

When you see this error, go bug your vendor/implementation developer!

6.1.7 Classes

Class: datagram-usocket ()

UDP (inet-datagram) socket

Class: stream-server-usocket ()

Socket which listens for stream connections to be initiated from remote sockets.

Class: stream-usocket ()

Stream socket class.
’
Contrary to other sockets, these sockets may be closed either with the ‘socket-close’ method or by closing the associated stream (which can be retrieved with the ‘socket-stream’ accessor).

Class: usocket ()

The main socket class.

Sockets should be closed using the ‘socket-close’ method.

6.2 Internal definitions

6.2.1 Special variables

Special Variable: *dummy-stream*

Special Variable: +sbcl-condition-map+

Special Variable: +sbcl-error-map+

Special Variable: +unix-errno-condition-map+

Special Variable: +unix-errno-error-map+

Special Variable: +unix-ns-error-map+

6.2.2 Macros

Macro: %with-timeout (SECONDS TIMEOUT-FORM) &body BODY

Runs BODY as an implicit PROGN with timeout of SECONDS. If timeout occurs before BODY has finished, BODY is unwound and TIMEOUT-FORM is executed with its values returned instead.

Note that BODY is unwound asynchronously when a timeout occurs, so unless all code executed during it – including anything down the call chain – is asynch unwind safe, bad things will happen. Use with care.

Macro: define-usocket-condition-classes CLASS-LIST PARENTS

Macro: ignore-unsupported-warnings &body BODY

6.2.3 Functions

Function: %add-waiter WAIT-LIST WAITER

Function: %make-wait-list &key (%WAIT %WAIT) (WAITERS WAITERS) (MAP MAP)

Function: %remove-waiter WAIT-LIST WAITER

Function: %setup-wait-list WAIT-LIST

Function: bool->int BOOL

Function: copy-wait-list INSTANCE

Function: define-usocket-condition-class CLASS &rest PARENTS

Function: get-host-by-address ADDRESS

Function: get-host-name ()

Function: handle-condition CONDITION &optional SOCKET HOST-OR-IP

Dispatch correct usocket condition.

Function: host-to-hbo HOST

Function: host-to-vector-quad HOST

Translate a host specification (vector quad, dotted quad or domain name) to a vector quad.

Function: int->bool INT

Function: ip-address-string-p STRING

Return a true value if the given string could be an IP address.

Function: list-of-strings-to-integers LIST

Take a list of strings and return a new list of integers (from parse-integer) on each of the string elements.

Function: make-datagram-socket SOCKET &key CONNECTED-P

Function: make-socket &key SOCKET

Create a usocket socket type from implementation specific socket.

Function: make-stream-server-socket SOCKET &key ELEMENT-TYPE

Create a usocket-server socket type from an implementation-specific socket object.

The returned value is a subtype of ‘stream-server-usocket’.

Function: make-stream-socket &key SOCKET STREAM

Create a usocket socket type from implementation specific socket and stream objects.

Sockets returned should be closed using the ‘socket-close’ method or by closing the stream associated with the socket.

Function: map-errno-condition ERRNO

Function: map-errno-error ERRNO

Function: map-socket-error SOCK-ERR

Function: split-ipv6-address STRING

Function: split-timeout TIMEOUT &optional FRACTIONAL

Split real value timeout into seconds and microseconds. Optionally, a different fractional part can be specified.

Function: wait-for-input-internal SOCKETS &key TIMEOUT

Function: wait-list-%wait INSTANCE

Function: (setf wait-list-%wait) VALUE INSTANCE

Function: wait-list-map INSTANCE

Function: (setf wait-list-map) VALUE INSTANCE

Function: wait-list-p OBJECT

Function: wait-list-waiters INSTANCE

Function: (setf wait-list-waiters) VALUE INSTANCE

6.2.4 Generic functions

Generic Function: connected-p OBJECT

Generic Function: (setf connected-p) NEW-VALUE OBJECT

Generic Function: context CONDITION

Generic Function: element-type OBJECT

Generic Function: feature CONDITION

Generic Function: minimum CONDITION

Generic Function: ns-real-condition CONDITION

Generic Function: (setf ns-real-condition) NEW-VALUE CONDITION

Generic Function: ns-real-error CONDITION

Generic Function: (setf ns-real-error) NEW-VALUE CONDITION

Generic Function: state OBJECT

Generic Function: (setf state) NEW-VALUE OBJECT

Generic Function: usocket-errno CONDITION

Generic Function: usocket-real-condition CONDITION

Generic Function: (setf usocket-real-condition) NEW-VALUE CONDITION

Generic Function: usocket-real-error CONDITION

Generic Function: (setf usocket-real-error) NEW-VALUE CONDITION

Generic Function: usocket-socket CONDITION

Generic Function: (setf usocket-socket) NEW-VALUE CONDITION

Generic Function: wait-list OBJECT

Generic Function: (setf wait-list) NEW-VALUE OBJECT

6.2.5 Structures

Structure: wait-list ()

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types