Skip to content
GitLab
Explore
Sign in
Register
Primary navigation
Search or go to…
Project
cmucl
Manage
Activity
Members
Labels
Plan
Issues
Issue boards
Milestones
Wiki
Code
Merge requests
Repository
Branches
Commits
Tags
Repository graph
Compare revisions
Snippets
Build
Pipelines
Jobs
Pipeline schedules
Artifacts
Deploy
Releases
Package registry
Model registry
Operate
Environments
Terraform modules
Monitor
Incidents
Service Desk
Analyze
Value stream analytics
Contributor analytics
CI/CD analytics
Repository analytics
Model experiments
Help
Help
Support
GitLab documentation
Compare GitLab plans
Community forum
Contribute to GitLab
Provide feedback
Terms and privacy
Keyboard shortcuts
?
Snippets
Groups
Projects
Show more breadcrumbs
Carl Shapiro
cmucl
Commits
0565c469
Commit
0565c469
authored
22 years ago
by
toy
Browse files
Options
Downloads
Patches
Plain Diff
Document CMUCLs internet functions. From Mario Mommer.
parent
0459083b
No related branches found
No related tags found
No related merge requests found
Changes
1
Hide whitespace changes
Inline
Side-by-side
Showing
1 changed file
docs/cmu-user/internet.tex
+272
-0
272 additions, 0 deletions
docs/cmu-user/internet.tex
with
272 additions
and
0 deletions
docs/cmu-user/internet.tex
0 → 100644
+
272
−
0
View file @
0565c469
\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))
This diff is collapsed.
Click to expand it.
Preview
0%
Loading
Try again
or
attach a new file
.
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Save comment
Cancel
Please
register
or
sign in
to comment