OpenMCL Sockets

Overview

OpenMCL supports the socket abstraction for interprocess communication. A socket represents a connection to another process, typically (but not necessarily) a TCP/IP network connection to a client or server running on some other machine on the network.

All symbols mentioned in this documentation are exported from the CCL package.

A socket is created by make-socket. The type of socket created depends on the arguments to make-socket. Three types are currently supported:

tcp-stream
A buffered bi-directional stream over a TCP/IP connection. tcp-stream is a subclass of stream, and you can read and write to it using all the usual stream functions. Created by (make-socket :type :stream :connect :active ...) or by (accept-connection ...).
listener-socket
A passive socket used to listen for incoming TCP/IP connections on a particular port. A listener-socket is not a stream. It doesn't support I/O. It can only be used to create new tcp-stream's by accept-connection. Created by (make-socket :type :stream :connect :passive ...)
udp-socket
A socket representing a packet-based UDP/IP connection. A udp-socket supports I/O but it is not a stream. Instead, you must use the special functions send-to and receive-from to read and write to it. Created by (make-socket :type :datagram ...)

Functional Reference

make-socket [Function]

Syntax
make-socket &key address-family type connect eol format
                 remote-host remote-port local-host local-port
                 keepalive reuse-address nodelay broadcast linger backlog
Description Creates and returns a new socket
Arguments
address-family
The address/protocol family of this socket. Currently only :internet (the default), meaning IP, is supported.
type
One of :stream (the default) to request a TCP socket, or :datagram to request a UDP socket. The default is :stream
connect
This argument is only relevant to TCP sockets. One of :active (the default) to request a connected tcp stream or :passive to request a listener socket.
eol
This argument is currently ignored (it is accepted for compatibility with Franz Allegro).
format
One of :text (the default), :binary, or :bivalent. This argument is ignored for TCP sockets for now, as TCP sockets are currently always bivalent (i.e. they support both character and byte I/O). For UDP sockets, the format determines the type of buffer created by receive-from.
remote-host
Required for TCP streams, it specifies the host to connect to (in any format acceptable to lookup-hostname). Ignored for listener sockets. For UDP sockets, it can be used to specify a default host for subsequent calls to sent-to or receive-from
remote-port
Required for TCP streams, it specifies the port to connect to (in any format acceptable to lookup-port). Ignored for listener sockets. For UDP sockets, it can be used to specify a default port for subsequent calls to sent-to or receive-from
local-host
Allows you to specify a local host address for a listener or UDP socket, for the rare case where you want to restrict connections to those coming to a specific local address for security reasons.
local-port
Specify a local port for a socket. Most useful for listener sockets, where it is the port on which the socket will listen for connections.
keepalive
If true, enables the periodic transmission of "keepalive" messages.
reuse-address
If true, allows the reuse of local ports in listener sockets, overriding some TCP/IP protocol specifications. You will need this if you are debugging a server..
nodelay
If true, disables Nagle's algorithm, which tries to minimize TCP packet fragmentation by introducing transmission delays in the absence of replies. Try setting this if you are using a protocol which involves sending a steady stream of data with no replies and are seeing significant degradations in throughput.
broadcast
If true, requests permission to broadcast datagrams on a UDP socket.
linger
If specified and non-nil, should be the number of seconds the OS is allowed to wait for data to be pushed through when a close is done. Only relevant for TCP sockets.
backlog
For a listener socket, specifies the number of connections which can be pending but not accepted. The default is 5, which is also the maximum on some operating systems.

accept-connection [Function]

Syntax
accept-connection (socket listener-socket) &key wait
Description Extracts the first connection on the queue of pending connections, accepts it (i.e. completes the connection startup protocol) and returns a new tcp-stream representing the newly established connection. The tcp stream inherits any properties of the listener socket that are relevant (e.g. :keepalive, :nodelay, etc.) The original listener socket continues to be open listening for more connections, so you can call accept-connection on it again.
Arguments
socket
The socket to listen on.
wait
If true (the default), and there are no connections waiting to be accepted, waits until one arrives. If false, returns NIL immediately in that case.

dotted-to-ipaddr [Function]

Syntax
dotted-to-ipaddr dotted &key errorp
Description Converts a dotted-string representation of a host address to a 32-bit unsigned IP address.
Arguments
dotted
A string representing an IP address in the "nn.nn.nn.nn" format
errorp
If true (the default) an error is signaled if dotted is invalid. If false, NIL is returned in that case.

ipaddr-to-dotted [Function]

Syntax
ipaddr-to-dotted ipaddr &key values
Description Converts a 32-bit unsigned IP address into octets.
Arguments
ipaddr
A 32-bit integer representing an internet host address
values
If false (the default), returns a string in the form "nn.nn.nn.nn". If true, returns four values representing the four octets of the address as unsigned 8-bit integers.

ipaddr-to-hostname [Function]

Syntax
ipaddr-to-hostname ipaddr &key ignore-cache
Description Converts a 32-bit unsigned IP address into a host name string
Arguments
ipaddr
a 32-bit integer representing an internet host address
ignore-cache
This argument is ignored (it is accepted for compatibility with Franz Allegro)

lookup-hostname [Function]

Syntax
lookup-hostname host
Description Converts a host spec in any of the acceptable formats into a 32-bit unsigned IP address
Arguments
host
Specifies the host. It can be either a host name string such as "clozure.com", or a dotted address string such as "192.168.0.1", or a 32-bit unsigned IP address such as 3232235521.

lookup-port [Function]

Syntax
lookup-port port protocol
Description Finds the port number for the specified port and protocol
Arguments
port
Specifies the port. It can be either a string, such as "http" or a symbol, such as :http, or an unsigned port number. Note that a string is case-sensitive. A symbol is lowercased before lookup.
protocol
Must be one of "tcp" or "udp".

receive-from [Function]

Syntax
receive-from (socket udp-socket) size
             &key buffer extract offset
Description Reads a UDP packet from a socket. If no packets are available, waits for a packet to arrive. Returns four values:
  1. The buffer with the data
  2. The number of bytes read
  3. The 32-bit unsigned IP address of the sender of the data
  4. The port number of the sender of the data
Arguments
socket
The socket to read from
size
Maximum number of bytes to read. If the packet is larger than this, any extra bytes are discarded.
buffer
If specified, must be either a string or a byte vector which will be used to read in the data. If not specified, a new buffer will be created (of type determined by socket-format).
extract
If true, the subsequence of the buffer corresponding only to the data read in is extracted and returned as the first value. If false (the default) the original buffer is returned even if it is only partially filled.
offset
Specifies the start offset into the buffer at which data is to be stored. The default is 0

send-to [Function]

Syntax
send-to (socket udp-socket) buffer size
        &key remote-host remote-port offset
Description Send a UDP packet over a socket.
Arguments
socket
The socket to write to
buffer
A vector containing the data to send. It must be either a string or a byte vector (either one is acceptable regardless of the stream format).
size
Number of bytes to send
remote-host
The host to send the packet to, in any format acceptable to lookup-hostname. The default is the remote host specified in the call to make-socket.
remote-port
The port to send the packet to, in any format acceptable to lookup-port. The default is the remote port specified in the call to make-socket.
offset
The offset in the buffer where the packet data starts

shutdown [Function]

Syntax
shutdown socket &key direction
Description Shuts down part of a bidirectional connection. This is useful if e.g. you need to read responses after sending an end-of-file signal.
Arguments
socket
The socket to shut down (typically a tcp-stream)
direction
One of :input to disallow further input, or :output to disallow further output.

socket-os-fd [Function]

Syntax
socket-os-fd socket
Description Returns the native OS's representation of the socket, or NIL if the socket is closed. On Unix, this is the Unix 'file descriptor', a small non-negative integer. Note that it is rather dangerous to mess around with tcp-stream fd's, as there is all sorts of buffering and asynchronous I/O going on above the OS level. listener-socket and udp-socket fd's are safer to mess with directly as there is less magic going on.
Arguments
socket
The socket

remote-host [Function]

Syntax
remote-host socket
Description Returns the 32-bit unsigned IP address of the remote host, or NIL if the socket is not connected.
Arguments
socket
The socket

remote-port [Function]

Syntax
remote-port socket
Description Returns the remote port number, or NIL if the socket is not connected.
Arguments
socket
The socket

local-host [Function]

Syntax
local-host socket
Description Returns 32-bit unsigned IP address of the local host.
Arguments
socket
The socket

local-port [Function]

Syntax
local-port socket
Description Returns the local port number
Arguments
socket
The socket

socket-address-family [Function]

Syntax
socket-address-family socket
Description Returns :internet
Arguments
socket
The socket

socket-connect [Function]

Syntax
socket-connect
Description Returns :active for tcp-stream, :passive for listener-socket, and NIL for udp-socket
Arguments
socket
The socket

socket-format [Function]

Syntax
socket-format socket
Description Returns the socket format as specified by the :format argument to make-socket.
Arguments
socket
The socket

socket-type [Function]

Syntax
socket-type socket
Description returns :stream for tcp-stream and listener-socket, and :datagram for udp-socket.
Arguments
socket
The socket

socket-error [Class]

Description The class of OS errors signaled by socket functions
Superclasses simple-error

socket-error-code [Function]

Syntax
socket-error-code socket-error
Description The OS error code of the error
Arguments
socket-error
the condition

socket-error-identifier [Function]

Syntax
socket-error-identifier socket-error
Description A symbol representing the error code in a more OS-independent way. One of: :address-in-use :connection-aborted :no-buffer-space :connection-timed-out :connection-refused :host-unreachable :host-down :network-down :address-not-available :network-reset :connection-reset :shutdown :access-denied or :unknown.
Arguments
socket-error
the condition

socket-error-situation [Function]

Syntax
socket-error-situation socket-error
Description A string describing the context where the error happened. On Linux, this is the name of the system call which returned the error.
Arguments
socket-error
the condition

close [method]

Syntax
close (socket socket) &key abort
Description The close generic function can be applied to sockets. It releases the operating system resources associated with the socket.
Arguments
socket
The socket to close
abort
If false (the default), closes the socket in an orderly fashion, finishing up any buffered pending I/O, before closing the connection. If true, aborts/ignores pending I/O. (For listener and udp sockets, this argument is effectively ignored since there is never any buffered I/O to clean up).

with-open-socket [Macro]

Syntax
with-open-socket (var . make-socket-args) &body body
Description executes body with var bound to the result of applying make-socket to make-socket-args. The socket gets closed on exit.
Arguments
var
variable to bind
make-socket-args
arguments suitable for passing to make-socket
body
body to execute
Last modified: Sun Sep 16 17:40:36 PDT 2001