Previous Up Next
Chapter 10 Networking Support

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.
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 &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.
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 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.
10.8 Unix Datagrams

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.
10.9 Errors

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.
Previous Up Next