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 &key
: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.
| 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.
[Function]
extensions:accept-network-stream socket &key :buffering :timeout :wait-max
Accept a connect from the specified socket and returns a stream
connected to connection.
The task performed by the functions we present next is connecting to
remote hosts.
[Function]
extensions:connect-to-inet-socket host port &optional kind
&key :local-host :local-port
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.
If local-host and local-port are specified, the socket
that is created is also bound to the specified local-host and
port.
[Function]
extensions:connect-to-unix-socket path &optional kind
Opens a connection to the unix ``address'' 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.
[Function]
extensions:open-network-stream host port &key :buffering :timeout
Return a stream connected to the specified port on the given host.
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 kind
Creates a unix socket for the internet address family, of type
:stream and (on success) returns its file descriptor.
Once a socket is created, it is sometimes useful to bind the socket to a
local address using bind-inet-socket:
[Function]
extensions:bind-inet-socket socket host port
Bind the socket to a local interface address specified
by host and port.
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.
Datagram network is supported with the following functions.
[Function]
extensions:inet-recvfrom fd buffer size
&key :flags
A simple interface to the Unix recvfrom function. Returns
three values: bytecount, source address as integer, and source
port. Bytecount can of course be negative, to indicate faults.
[Function]
extensions:inet-sendto fd buffer size addr port
&key :flags
A simple interface to the Unix sendto function.
[Function]
extensions: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.