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.
These are the functions that convert integers from host byte order to network byte order (big-endian).
Converts a 32 bit integer from host byte order to network byte order.
Converts a 16 bit integer from host byte order to network byte order.
Converts a 32 bit integer from network byte order to host byte order.
Converts a 32 bit integer from network byte order to host byte order.
The networking support of cmucl includes the possibility of doing DNS lookups. The function
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.
name aliases addr-type addr-listThis 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.
This function takes an IP address in host order and returns a string containing it in dotted format.
In this section, functions for creating sockets bound to an interface are documented.
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.
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.
Once a socket is bound to its interface, we have to explicitly accept connections. This task is performed by the functions we document here.
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.
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.
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.
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.
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.
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.
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.
Removes the handler for the character char from the connection with the file descriptor fd
After calling this function, the connection whose descriptor is fd will ignore any out-of-band character it receives.
Sends the character char through the connection fd out of band.
These functions create unbound sockets. This is usually not necessary, since connectors and listeners create their own.
Creates a unix socket for the unix address family, of type :stream and (on success) returns its file descriptor.
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:
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.
Gets the value of option optname from the socket socket.
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
Closes the socket given by the file descriptor socket.
Datagram network is supported with the following functions.
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.
A simple interface to the Unix sendto function.
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.