Introduction
One of the Great Complaints about Lisp is it's lack of standard sockets. As Lisp was born before the Internet became a big deal sockets did not make it into the CL standard. The current status of Lisp sockets is every Lisp has it's own implementation and various "universal" socket libraries go through each implementation's socket library. The Lisp Sockets project exists to make open source projects more shareable, by eliminating an implementation dependency. CLS aims to create single socket library with a standard interface for all Lisp implementations in all environments.
Support
CLS currently supports the following systems and implementations:
Windows:AllegroCL
Mac OS X:CMUCL, SBCL
FreeBSD:CMUCL, SBCL
Download CLS
You need to download the UFFI package from its web home http://common-lisp.net/project/cl-sockets/. You also need to have
a copy of ASDF. If you need a copy of ASDF.
Loading
After downloading and installing ASDF, whenever you want to load the CLS package, use the form
(asdf:operate 'asdf:load-op :cls)
Conventions
IP addresses are referred to by a vector such as (127 0 0 1) for 127.0.0.1. All functions return a list. In the event of an error the first item will be the value t and the second a lisp string describing the error. If no error occurred the the first argument is nil and the second argument will be a list containing the return value(s). For the remainder of this manual when a function is said to return x if successful, it means the actual return value of the function is (nil x).
Function Reference
cls-socket domain type protocol
cls-socket creates an endpoint for communication and returns a descriptor.
Valid arguments for domain: 'AF_INET
Valid arguments for type: 'SOCK_STREAM, 'SOCK_DGRAM, 'SOCK_RAW, 'SOCK_RDM, 'SOCK_SEQPACKET
protocol is a number from /etc/protocols. eg: 6 for tcp
returns a socket
cls-bind s name
cls-bind assigns a name to an unnamed socket.
s is a socket returned by cls-socket.
name depends on the type of socket family. For name use the form ((127 0 0 1) 80) to refer to port 80 of the address 127.0.0.1. (INADDR_ANY 80) is also defined.
no return value
cls-connect s name
Connects socket s to name.
name is defined as in cls-bind.
no return value
cls-listen s backlog
A willingness to accept incoming connections and a queue limit for incoming connections are specified with cls-listen. cls-listen applies only to sockets of type SOCK_STREAM or SOCK_SEQPACKET.
s is a socket returned by cls-socket.
The backlog parameter defines the maximum length the queue of pending connections may grow to.
no return value
cls-accept s
cls-accept extracts the first connection request on the queue of pending connections, creates a new socket with the same properties of s and allocates a new file descriptor for the socket.
s is a socket returned by cls-socket.
returns a socket.
cls-send s msg len flags
cls-send is used to transmit a message to another socket.
s is a socket.
msg is a lisp string.
len refers to the number of bytes from the string to send, must be less than or equal to the length of the string.
The flags parameter may be one or more of the following:
'MSG_OOB process out-of-band data
'MSG_DONTROUTE bypass routing, use direct interface
cls-recv s len flags
cls-recv is used to receive messages from a socket.
s is a socket.
len is the maximum number of octets to receive.
flags:
'MSG_OOB: process out-of-band data
'MSG_PEEK: peek at incoming message
'MSG_WAITALL: wait for full request or error
returns (len data) len indicates how many bytes were returned in the lisp string data
cls-shutdown s how
cls-shutdown causes all or part of a full-duplex connection on the socket associated with s to be shut down.
s is a socket
how may be one of: 'SHUT_RD, 'SHUT_WR or SHUT_RDWR'
cls-sockopt s level keyval
cls-sockopt retrieves and optionally sets socket options.
s is a socket
level is 'SOL_SOCKET
keyval is a list of one or two items. The first item indicates the option to in question. The second option if present is a boolean value to indicate setting or unsetting the option. In either case cls-sockopt returns the value of that option.
valid options include:
'SO_DEBUG
'SO_REUSEADDR
'SO_KEEPALIVE
'SO_DONTROUTE
'SO_BROADCAST
'SO_LINGER
'SO_OOBINLINE
cls-peername s
cls-peername returns the name of the peer connected to socket s
cls-sockname s
sockname system call returns the current name for the specified socket s
cls-gethostbyname hostname
looks up hostname and returns (name aliases addr_list) where
name is the official name of hostname
aliases is a list of alternative names for hostname
addr_list is a list of network addresses for hostname
cls-gethostbyaddr quad
performs gethostbyaddr on the IP refered to by the quad.
returns (name aliases addr_list) where
name is the official name of the host
aliases is a list of alternative names for the host
addr_list is a list of network addresses for the host
cls-quad-to-string quad
returns a string such as "127.0.0.1" for argument (127 0 0 1)