by Mario S. Mommer
This chapter documents the IPv4 networking and local sockets
support offered by CMUCL. It covers most of the basic sockets
interface functionality in a convenient and transparent way.
For reasons of space it would be impossible to include a thorough
introduction to network programming, so we assume some basic
knowledge of the matter.
10.1 Byte Order Converters
These are the functions that convert integers from host byte order
to network byte order (big-endian).
[Function]
extensions:htonl integer
Converts a 32 bit integer from host byte order to network byte
order.
[Function]
extensions:htons integer
Converts a 16 bit integer from host byte order to network byte
order.
[Function]
extensions:ntohs integer
Converts a 32 bit integer from network byte order to host byte
order.
[Function]
extensions:ntohl integer
Converts a 32 bit integer from network byte order to host byte
order.
10.2 Domain Name Services (DNS)
The networking support of CMUCL includes the possibility of doing
DNS lookups. The function
[Function]
extensions:lookup-host-entry host
returns a structure of type host-entry
(explained below) for the given host. If
host is an integer, it will be assumed to
be the IP address in host (byte-)order. If it is a string, it can
contain either the host name or the IP address in dotted
format.
This function works by completing the structure host-entry. That is, if the user provides the IP
address, then the structure will contain that information and also
the domain names. If the user provides the domain name, the
structure will be complemented with the IP addresses along with the
any aliases the host might have.
[structure]
host-entry
name aliases addr-type
addr-list
This structure holds all information available at request time on a
given host. The entries are self-explanatory. Aliases is a list of
strings containing alternative names of the host, and addr-list a
list of addresses stored in host byte order. The field addr-type contains the number of the address
family, as specified in socket.h, to which the addresses
belong. Since only addresses of the IPv4 family are currently
supported, this slot always has the value 2.
[Function]
extensions:ip-string addr
This function takes an IP address in host order and returns a
string containing it in dotted format.
10.3 Binding to Interfaces
In this section, functions for creating sockets bound to an
interface are documented.
[Function]
extensions:create-inet-listener port &optional kind &key :reuse-address :backlog
:host
Creates a socket and binds it to a port, prepared to receive
connections of kind kind (which defaults
to :stream), queuing up to backlog of them. If :reuse-address T is used, the
option SO_REUSEADDR is used in the call to bind. If no value is given for :host, it will try to bind to the default IP address of
the machine where the Lisp process is running.
[Function]
extensions:create-unix-listener path &optional kind :reuse-address
:backlog
Creates a socket and binds it to the file name given by path, prepared to receive connections of kind
kind (which defaults to :stream), queuing up to backlog of them. If :reuse-address T is used,
then the file given by path is unlinked
first.
10.4 Accepting Connections
Once a socket is bound to its interface, we have to explicitly
accept connections. This task is performed by the functions we
document here.
[Function]
extensions:accept-tcp-connection unconnected
Waits until a connection arrives on the (internet family) socket
unconnected. Returns the file descriptor
of the connection. These can be conveniently encapsulated using
file descriptor streams; see 6.7.
[Function]
extensions:accept-unix-connection unconnected
Waits until a connection arrives on the (unix family) socket
unconnected. Returns the file descriptor
of the connection. These can be conveniently encapsulated using
file descriptor streams; see 6.7.
10.5 Connecting
The task performed by the functions we present next is connecting
to remote hosts.
[Function]
extensions:connect-to-inet-socket host port &optional kind
Tries to open a connection to the remote host host (which may be an IP address in host order, or
a string with either a host name or an IP address in dotted format)
on port port. Returns the file descriptor
of the connection. The optional parameter kind can be either :stream
(the default) or :datagram.
[Function]
extensions:connect-to-unix-socket path &optional kind
Opens a connection to the unix “adress” given by
path. Returns the file descriptor of the
connection. The type of connection is given by kind, which can be either :stream (the default) or :datagram.
10.6 Out-of-Band Data
Out-of-band data is
data transmitted with a higher priority than ordinary data. This is
usually used by either side of the connection to signal exceptional
conditions. Due to the fact that most TCP/IP implementations are
broken in this respect, only single characters can reliably be sent
this way.
[Function]
extensions:add-oob-handler fd
char handler
Sets the function passed in handler as a
handler for the character char on the
connection whose descriptor is fd. In
case this character arrives, the function in handler is called without any
argument.
[Function]
extensions:remove-oob-handler fd char
Removes the handler for the character char from the connection with the file descriptor
fd
[Function]
extensions:remove-all-oob-handlers fd
After calling this function, the connection whose descriptor is
fd will ignore any out-of-band character
it receives.
[Function]
extensions:send-character-out-of-band fd char
Sends the character char through the
connection fd out of band.
10.7 Unbound Sockets, Socket Options, and
Closing Sockets
These functions create unbound sockets. This is usually not
necessary, since connectors and listeners create their own.
[Function]
extensions:create-unix-socket &optional type
Creates a unix socket for the unix address family, of type
:stream and (on success) returns its file
descriptor.
[Function]
extensions:create-inet-socket &optional type
Creates a unix socket for the internet address family, of type
:stream and (on success) returns its file
descriptor.
Further, it is desirable to be able to change socket options. This
is performed by the following two functions, which are essentially
wrappers for system calls to getsockopt and
setsockopt.
[Function]
extensions:get-socket-option socket level optname
Gets the value of option optname from the
socket socket.
[Function]
extensions:set-socket-option socket level optname optval
Sets the value of option optname from the
socket socket to the value optval.
For information on possible options and values we refer to the
manpages of getsockopt and setsockopt, and to
socket.h
Finally, the function
[Function]
extensions:close-socket socket
Closes the socket given by the file descriptor socket.
10.8 Unix Datagrams
Datagram network is supported with the following functions.
[Function]
unix:inet-recvfrom fd
buffer size
&key flags
A simple interface to the Unix recvfrom function.
[Function]
unix:inet-sendto fd
buffer size
port &key
flags
A simple interface to the Unix sendto function.
[Function]
unix:inet-shutdown fd
level
A simple interface to the Unix shutdown
function. For level, you may use the
following symbols to close one or both ends of a socket: shut-rd, shut-wr, shut-rdwr.
Errors that occur during socket operations signal a socket-error condition, a subtype of the error condition. Currently this condition includes just
the Unix errno associated with the error.