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
:interface
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 :interface, 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.
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.
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.