Skip to content
Snippets Groups Projects
Commit 0565c469 authored by toy's avatar toy
Browse files

Document CMUCLs internet functions. From Mario Mommer.

parent 0459083b
No related branches found
No related tags found
No related merge requests found
\chapter{Networking Support}
\label{internet}
\credits{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.
\section{Byte Order Converters}
These are the functions that convert integers from host byte order to
network byte order (big-endian).
\begin{defun}{extensions:}{htonl}{%
\args{\var{integer}}}
Converts a $32$ bit integer from host byte order to network byte
order.
\end{defun}
\begin{defun}{extensions:}{htons}{%
\args{\var{integer}}}
Converts a $16$ bit integer from host byte order to network byte
order.
\end{defun}
\begin{defun}{extensions:}{ntohs}{%
\args{\var{integer}}}
Converts a $32$ bit integer from network byte order to host
byte order.
\end{defun}
\begin{defun}{extensions:}{ntohl}{%
\args{\var{integer}}}
Converts a $32$ bit integer from network byte order to host byte
order.
\end{defun}
\section{Domain Name Services (DNS)}
The networking support of \cmucl{} includes the possibility of doing
DNS lookups. The function
\begin{defun}{extensions:}{lookup-host-entry}{%
\args{\var{host}}}
returns a structure of type \var{host-entry} (explained below) for
the given \var{host}. If \var{host} is an integer, it will be
assumed to be the IP adress in host (byte-)order. If it is a string,
it can contain either the host name or the IP adress in dotted
format.
This function works by completing the structure \var{host-entry}.
That is, if the user provides the IP adress, 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 adresses along with the any aliases the host might have.
\end{defun}
\newpage
\begin{deftp}{structure}{host-entry}\args{\var{name} \var{aliases}
\var{addr-type} \var{addr-list}}
This structure holds all information available at request time on a
given host. The entries are selfexplanatory. Aliases is a list of
strings containing alternative names of the host, and addr-list a
list of adresses stored in host byte order. The field
\var{addr-type} contains the number of the adress family, as
specified in \var{socket.h}, to which the addresses belong. Since
only adresses of the IPv4 family are currently supported, this slot
allways has the value $2$.
\end{deftp}
\begin{defun}{extensions:}{ip-string}{%
\args{\var{addr}}}
This function takes an IP adress in host order and returns a string
containing it in dotted format.
\end{defun}
\section{Binding to Interfaces}
In this section, functions for creating sockets bound to an interface
are documented.
\begin{defun}{extensions:}{create-inet-listener}{%
\args{\var{port} \ampoptional{} \var{kind} %
\keys{\kwd{reuse-address} \kwd{backlog} \kwd{interface}}}}
Creates a socket and binds it to a port, prepared to recieve
connections of kind \var{kind} (which defaults to \kwd{stream}),
queuing up to \var{backlog} of them. If \kwd{reuse-address} \var{T}
is used, the option SO\_REUSEADDR is used in the call to \var{bind}.
If no value is given for \kwd{interface}, it will try to bind to the
default IP adress of the machine where the Lisp process is running.
\end{defun}
\begin{defun}{extensions:}{create-unix-listener}{%
\args{\var{path} \ampoptional{} \var{kind} \kwd{reuse-address}
\kwd{backlog}}}
Creates a socket and binds it to the file name given by \var{path},
prepared to recieve connections of kind \var{kind} (which defaults
to \kwd{stream}), queuing up to \var{backlog} of them. If
\kwd{reuse-address} \var{T} is used, then the file given by
\var{path} is unlinked first.
\end{defun}
\section{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.
\begin{defun}{extensions:}{accept-tcp-connection}{%
\args{\var{unconnected}}}
Waits until a connection arrives on the (internet family) socket
\var{unconnected}. Returns the file descriptor of the connection.
These can be conveniently encapsulated using file descriptor
streams; see \ref{sec:fds}.
\end{defun}
\begin{defun}{extensions:}{accept-unix-connection}{%
\args{\var{unconnected}}}
Waits until a connection arrives on the (unix family) socket
\var{unconnected}. Returns the file descriptor of the connection.
These can be conveniently encapsulated using file descriptor
streams; see \ref{sec:fds}.
\end{defun}
\section{Connecting}
The task performed by the functions we present next is connecting to
remote hosts.
\begin{defun}{extensions:}{connect-to-inet-socket}{%
\args{\var{host} \var{port} \ampoptional{} \var{kind}}}
Tries to open a connection to the remote host \var{host} (which may
be an IP adress in host order, or a string with either a host name
or an IP adress in dotted format). Returns the file descriptor of
the connection.
\end{defun}
\begin{defun}{extensions:}{connect-to-unix-socket}{%
\args{\var{path} \ampoptional{} \var{kind}}}
Opens a connection of type \var{kind} (default: \kwd{stream}) to the
unix ``adress'' given by \var{path}. Returns the file descriptor of
the connection.
\end{defun}
\section{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.
\begin{defun}{extensions:}{add-oob-handler}{%
\args{\var{fd} \var{char} \var{handler}}}
Sets the function passed in \var{handler} as a handler for the
character \var{char} on the connection whose descriptor is \var{fd}.
In case this character arrives, the function in \var{handler} is
called without any argument.
\end{defun}
\begin{defun}{extensions:}{remove-oob-handler}{%
\args{\var{fd} \var{char}}}
Removes the handler for the character \var{char} on the connection
with the file descriptor \var{fd}
\end{defun}
\begin{defun}{extensions:}{remove-all-oob-handlers}{%
\args{\var{fd}}}
After calling this function, the connection whose descriptor is
\var{fd} will ignore any out-of-band character it recieves.
\end{defun}
\begin{defun}{extensions:}{send-character-out-of-band}{%
\args{\var{fd} \var{char}}}
Sends the character \var{char} through the connection \var{fd} out
of band.
\end{defun}
\section{Unbound Sockets, Socket Options, and Closing Sockets}
These functions create unbound sockets. This is usually not necessary,
since conectors and listeners create their own.
\begin{defun}{extensions:}{create-unix-socket}{%
\args{\ampoptional{} \var{type}}}
Creates a unix socket for the unix adress family, of type
\var{:stream} and (on success) returns its file descriptor.
\end{defun}
\begin{defun}{extensions:}{create-inet-socket}{%
\args{\ampoptional{} \var{type}}}
Creates a unix socket for the internet adress family, of type
\var{:stream} and (on success) returns its file descriptor.
\end{defun}
Further, it is desirable to be able to change socket options. This is
performed by the following two functions:
\begin{defun}{extensions:}{get-socket-option}{%
\args{\var{socket} \var{level} \var{optname}}}
Gets the value of option \var{optname} from the socket \var{socket}.
\var{level} should have the value \var{sol-socket}.
\end{defun}
\begin{defun}{extensions:}{set-socket-option}{%
\args{\var{socket} \var{level} \var{optname} \var{optval}}}
Sets the value of option \var{optname} from the socket \var{socket}
to the value \var{optval}. As in get-socket-options, \var{level}
should have the value \var{sol-socket}.
\end{defun}
Finally, the function
\begin{defun}{extensions:}{close-socket}{%
\args{\var{socket}}}
Closes the socket given by the file descriptor \var{socket}.
\end{defun}
%(export '(htonl ntohl htons ntohs lookup-host-entry host-entry host-entry-name
% host-entry-aliases host-entry-addr-list host-entry-addr
% create-unix-socket connect-to-unix-socket create-inet-socket
% connect-to-inet-socket create-inet-listener accept-tcp-connection
% close-socket ipproto-tcp ipproto-udp inaddr-any add-oob-handler
% remove-oob-handler remove-all-oob-handlers
% send-character-out-of-band))
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment