usocket

API Reference

usocket

Universal socket library for Common Lisp

USOCKET

  • Variable *WILDCARD-HOST*
    #(0 0 0 0)
    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.
  • Variable *AUTO-PORT*
    0
    Port number to pass when an auto-assigned port number is wanted.
  • Variable *VERSION*
    "0.7.0.1"
  • Variable +MAX-DATAGRAM-PACKET-SIZE+
    65507
    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)
  • Class USOCKET
    The main socket class. Sockets should be closed using the `socket-close' method.
    SOCKET   Accessor: SOCKET
    Implementation specific socket object instance.'
    WAIT-LIST   Accessor: WAIT-LIST
    WAIT-LIST the object is associated with.
    STATE   Accessor: STATE
    Per-socket return value for the `wait-for-input' function. The value stored in this slot can be any of NIL - not ready :READ - ready to read :READ-WRITE - ready to read and write :WRITE - ready to write The last two remain unused in the current version.
  • Generic-Function SOCKET-STATE (socket)
    NIL - not ready :READ - ready to read :READ-WRITE - ready to read and write :WRITE - ready to write
  • Method SOCKET-STATE ((socket usocket))
  • Class STREAM-USOCKET  (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).
    STREAM   Accessor: SOCKET-STREAM
    Stream instance associated with the socket.
  • Class STREAM-SERVER-USOCKET  (USOCKET)
    Socket which listens for stream connections to be initiated from remote sockets.
    ELEMENT-TYPE   Reader: ELEMENT-TYPE
    Default element type for streams created by `socket-accept'.
  • Class DATAGRAM-USOCKET  (USOCKET)
    UDP (inet-datagram) socket
    CONNECTED-P   Accessor: CONNECTED-P
  • Function USOCKET-P (socket)
  • Function STREAM-USOCKET-P (socket)
  • Function STREAM-SERVER-USOCKET-P (socket)
  • Function DATAGRAM-USOCKET-P (socket)
  • 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-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-SEND (usocket buffer length &key host port)
    Send packets through a previously opend `usocket'.
  • Generic-Function SOCKET-RECEIVE (usocket buffer length &key)
    Receive packets from a previously opend `usocket'. Returns 4 values: (values buffer size host port)
  • Generic-Function GET-LOCAL-ADDRESS (socket)
    Returns the IP address of the socket.
  • Generic-Function GET-PEER-ADDRESS (socket)
    Returns the IP address of the peer the socket is connected to.
  • 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-PORT (socket)
    Returns the IP port of the peer the socket to.
  • 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-PEER-NAME (socket)
    Returns the IP address and port of the peer the socket is connected to as values.
  • 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-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-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'.
  • Function MAKE-WAIT-LIST (waiters)
  • Function ADD-WAITER (wait-list input)
  • Function REMOVE-WAITER (wait-list input)
  • Function REMOVE-ALL-WAITERS (wait-list)
  • Function WAIT-FOR-INPUT (socket-or-sockets &key timeout ready-only)
    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.
  • Function INTEGER-TO-OCTET-BUFFER (integer buffer octets &key (start 0))
  • Function OCTET-BUFFER-TO-INTEGER (buffer octets &key (start 0))
  • Macro PORT-TO-OCTET-BUFFER (port buffer &key (start 0))
  • Macro IP-TO-OCTET-BUFFER (ip buffer &key (start 0))
  • Macro PORT-FROM-OCTET-BUFFER (buffer &key (start 0))
  • Macro IP-FROM-OCTET-BUFFER (buffer &key (start 0))
  • 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 VECTOR-QUAD-TO-DOTTED-QUAD (vector)
  • Function DOTTED-QUAD-TO-VECTOR-QUAD (string)
  • Generic-Function HOST-BYTE-ORDER (address)
  • Method HOST-BYTE-ORDER ((string string))
    Convert a string, such as 192.168.1.1, to host-byte-order, such as 3232235777.
  • Method HOST-BYTE-ORDER ((vector vector))
    Convert a vector, such as #(192 168 1 1), to host-byte-order, such as 3232235777.
  • Function VECTOR-TO-IPV6-HOST (vector)
  • Function IPV6-HOST-TO-VECTOR (string)
  • Function IP= (ip1 ip2)
  • Function IP/= (ip1 ip2)
  • Condition INSUFFICIENT-IMPLEMENTATION  (ERROR)
    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 UNSUPPORTED  (INSUFFICIENT-IMPLEMENTATION)
    Signalled when the underlying implementation doesn't allow supporting the requested feature. When you see this error, go bug your vendor/implementation developer!
  • Condition UNIMPLEMENTED  (INSUFFICIENT-IMPLEMENTATION)
    Signalled if a certain feature might be implemented, based on the features of the underlying implementation, but hasn't been implemented yet.
  • Condition SOCKET-CONDITION  (CONDITION)
    Parent condition for all socket related conditions.
  • Condition SOCKET-ERROR  (SOCKET-CONDITION, ERROR)
    Parent error for all socket related errors
  • Condition NS-CONDITION  (CONDITION)
    Parent condition for all name resolution conditions.
  • Condition NS-ERROR  (NS-CONDITION, ERROR)
    Parent error for all name resolution errors.
  • Condition INTERRUPTED-CONDITION  (SOCKET-CONDITION)
  • Condition UNKNOWN-CONDITION  (SOCKET-CONDITION)
    Condition raised when there's no other - more applicable - condition available.
  • Condition ADDRESS-IN-USE-ERROR  (SOCKET-ERROR)
  • Condition ADDRESS-NOT-AVAILABLE-ERROR  (SOCKET-ERROR)
  • Condition BAD-FILE-DESCRIPTOR-ERROR  (SOCKET-ERROR)
  • Condition CONNECTION-REFUSED-ERROR  (SOCKET-ERROR)
  • Condition CONNECTION-ABORTED-ERROR  (SOCKET-ERROR)
  • Condition CONNECTION-RESET-ERROR  (SOCKET-ERROR)
  • Condition INVALID-ARGUMENT-ERROR  (SOCKET-ERROR)
  • Condition NO-BUFFERS-ERROR  (SOCKET-ERROR)
  • Condition OPERATION-NOT-SUPPORTED-ERROR  (SOCKET-ERROR)
  • Condition OPERATION-NOT-PERMITTED-ERROR  (SOCKET-ERROR)
  • Condition PROTOCOL-NOT-SUPPORTED-ERROR  (SOCKET-ERROR)
  • Condition SOCKET-TYPE-NOT-SUPPORTED-ERROR  (SOCKET-ERROR)
  • Condition NETWORK-UNREACHABLE-ERROR  (SOCKET-ERROR)
  • Condition NETWORK-DOWN-ERROR  (SOCKET-ERROR)
  • Condition NETWORK-RESET-ERROR  (SOCKET-ERROR)
  • Condition HOST-DOWN-ERROR  (SOCKET-ERROR)
  • Condition HOST-UNREACHABLE-ERROR  (SOCKET-ERROR)
  • Condition SHUTDOWN-ERROR  (SOCKET-ERROR)
  • Condition TIMEOUT-ERROR  (SOCKET-ERROR)
  • Condition DEADLINE-TIMEOUT-ERROR  (SOCKET-ERROR)
  • Condition INVALID-SOCKET-ERROR  (SOCKET-ERROR)
  • Condition INVALID-SOCKET-STREAM-ERROR  (SOCKET-ERROR)
  • Condition UNKNOWN-ERROR  (SOCKET-ERROR)
    Error raised when there's no other - more applicable - error available.
  • Condition NS-TRY-AGAIN-CONDITION  (NS-CONDITION)
  • Condition NS-UNKNOWN-CONDITION  (NS-CONDITION)
    Condition raised when there's no other - more applicable - condition available.
  • Condition NS-HOST-NOT-FOUND-ERROR  (NS-ERROR)
  • Condition NS-NO-RECOVERY-ERROR  (NS-ERROR)
  • Condition NS-UNKNOWN-ERROR  (NS-ERROR)
    Error raised when there's no other - more applicable - error available.
  • Macro WITH-MAPPED-CONDITIONS ((&optional socket) &body body)
  • Macro UNSUPPORTED (feature context &key minimum)
  • Macro UNIMPLEMENTED (feature context)
  • Function SOCKET-CONNECT (host port &key (protocol :stream) (element-type 'character) timeout deadline (nodelay t nodelay-specified) local-host local-port &aux (sockopt-tcp-nodelay-p (fboundp 'sb-bsd-sockets:sockopt-tcp-nodelay)))
  • Function SOCKET-LISTEN (host port &key reuseaddress (reuse-address nil reuse-address-supplied-p) (backlog 5) (element-type 'character))
  • Method SOCKET-ACCEPT ((usocket stream-server-usocket) &key element-type)
  • Method SOCKET-CLOSE ((usocket usocket))
  • Method SOCKET-CLOSE ((usocket stream-usocket))
  • Method SOCKET-SHUTDOWN ((usocket stream-usocket) direction)
  • Method SOCKET-SEND ((usocket datagram-usocket) buffer size &key host port (offset 0))
  • Method SOCKET-RECEIVE ((socket datagram-usocket) buffer length &key (element-type '(unsigned-byte 8)))
  • Method GET-LOCAL-NAME ((usocket usocket))
  • Method GET-PEER-NAME ((usocket stream-usocket))
  • Method GET-LOCAL-ADDRESS ((usocket usocket))
  • Method GET-PEER-ADDRESS ((usocket stream-usocket))
  • Method GET-LOCAL-PORT ((usocket usocket))
  • Method GET-PEER-PORT ((usocket stream-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
  • Method SOCKET-OPTION ((socket usocket) (option t) &key)
  • Method (setf SOCKET-OPTION) (new-value (socket usocket) (option t) &key)
  • Method SOCKET-OPTION ((socket usocket) (option symbol) &key)
  • Method (setf SOCKET-OPTION) (new-value (socket usocket) (option symbol) &key)
  • Method SOCKET-OPTION ((usocket stream-usocket) (option (eql :receive-timeout)) &key)
  • Method (setf SOCKET-OPTION) (new-value (usocket stream-usocket) (option (eql :receive-timeout)) &key)
  • Method SOCKET-OPTION ((usocket stream-usocket) (option (eql :send-timeout)) &key)
  • Method (setf SOCKET-OPTION) (new-value (usocket stream-usocket) (option (eql :send-timeout)) &key)
  • Method SOCKET-OPTION ((usocket stream-server-usocket) (option (eql :reuse-address)) &key)
  • Method (setf SOCKET-OPTION) (new-value (usocket stream-server-usocket) (option (eql :reuse-address)) &key)
  • Method SOCKET-OPTION ((usocket datagram-usocket) (option (eql :broadcast)) &key)
  • Method (setf SOCKET-OPTION) (new-value (usocket datagram-usocket) (option (eql :broadcast)) &key)
  • Method SOCKET-OPTION ((usocket stream-usocket) (option (eql :tcp-no-delay)) &key)
  • Method SOCKET-OPTION ((usocket stream-usocket) (option (eql :tcp-nodelay)) &key)
  • Method (setf SOCKET-OPTION) (new-value (usocket stream-usocket) (option (eql :tcp-no-delay)) &key)
  • Method (setf SOCKET-OPTION) (new-value (usocket stream-usocket) (option (eql :tcp-nodelay)) &key)

usocket-server

Universal socket library for Common Lisp (server side)

No packages.

usocket-test

Tests for usocket

USOCKET-TEST

  • Function RUN-USOCKET-TESTS

Also exports

  • REGRESSION-TEST:DO-TESTS