/usr/share/doc/cmucl-docs/internet.html is in cmucl-docs 20c-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>
<META http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<META name="GENERATOR" content="hevea 1.10">
<link rel="stylesheet" href="cmucl.css" type="text/css">
<meta http-equiv="Content-Language" content="en">
<LINK rel="stylesheet" type="text/css" href="cmu-user.css">
<TITLE>CMUCL User’s Manual: Networking Support</TITLE>
</HEAD>
<BODY >
<A HREF="ipc.html"><IMG SRC="previous_motif.gif" ALT="Previous"></A>
<A HREF="index.html"><IMG SRC="contents_motif.gif" ALT="Up"></A>
<A HREF="debug-internals.html"><IMG SRC="next_motif.gif" ALT="Next"></A>
<HR>
<H1 CLASS="chapter"><A NAME="htoc277">Chapter 10</A>  Networking Support</H1><UL>
<LI><A HREF="internet.html#toc281">Byte Order Converters</A>
</LI><LI><A HREF="internet.html#toc282">Domain Name Services (DNS)</A>
</LI><LI><A HREF="internet.html#toc283">Binding to Interfaces</A>
</LI><LI><A HREF="internet.html#toc284">Accepting Connections</A>
</LI><LI><A HREF="internet.html#toc285">Connecting</A>
</LI><LI><A HREF="internet.html#toc286">Out-of-Band Data</A>
</LI><LI><A HREF="internet.html#toc287">Unbound Sockets, Socket Options, and Closing Sockets</A>
</LI><LI><A HREF="internet.html#toc288">Unix Datagrams</A>
</LI><LI><A HREF="internet.html#toc289">Errors</A>
</LI></UL>
<P>
<A NAME="internet"></A></P><DIV CLASS="center">
<B>by Mario S. Mommer</B>
</DIV><P>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.</P><P>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.</P><H2 CLASS="section"><A NAME="toc281"></A><A NAME="htoc278">10.1</A>  Byte Order Converters</H2><P>These are the functions that convert integers from host byte order to
network byte order (big-endian).</P><P><BR>
<A NAME="@funs258"></A><A NAME="FN:htonl"></A></P><DIV align=left>
[Function]<BR>
<TT class=function-name>extensions:</TT><TT class=function-name>htonl</TT> <TT class=variable>integer</TT>
</DIV><BLOCKQUOTE CLASS="quote"><P>Converts a 32 bit integer from host byte order to network byte
order.</P></BLOCKQUOTE><P><BR>
<A NAME="@funs259"></A><A NAME="FN:htons"></A></P><DIV align=left>
[Function]<BR>
<TT class=function-name>extensions:</TT><TT class=function-name>htons</TT> <TT class=variable>integer</TT>
</DIV><BLOCKQUOTE CLASS="quote"><P>Converts a 16 bit integer from host byte order to network byte
order.</P></BLOCKQUOTE><P><BR>
<A NAME="@funs260"></A><A NAME="FN:ntohs"></A></P><DIV align=left>
[Function]<BR>
<TT class=function-name>extensions:</TT><TT class=function-name>ntohs</TT> <TT class=variable>integer</TT>
</DIV><BLOCKQUOTE CLASS="quote"><P>Converts a 32 bit integer from network byte order to host
byte order.</P></BLOCKQUOTE><P><BR>
<A NAME="@funs261"></A><A NAME="FN:ntohl"></A></P><DIV align=left>
[Function]<BR>
<TT class=function-name>extensions:</TT><TT class=function-name>ntohl</TT> <TT class=variable>integer</TT>
</DIV><BLOCKQUOTE CLASS="quote"><P>Converts a 32 bit integer from network byte order to host byte
order.</P></BLOCKQUOTE><H2 CLASS="section"><A NAME="toc282"></A><A NAME="htoc279">10.2</A>  Domain Name Services (DNS)</H2><P>The networking support of CMUCL includes the possibility of doing
DNS lookups. The function </P><P><BR>
<A NAME="@funs262"></A><A NAME="FN:lookup-host-entry"></A></P><DIV align=left>
[Function]<BR>
<TT class=function-name>extensions:</TT><TT class=function-name>lookup-host-entry</TT> <TT class=variable>host</TT>
</DIV><BLOCKQUOTE CLASS="quote"><P>returns a structure of type </P><TT class=variable>host-entry</TT><P> (explained below) for
the given </P><TT class=variable>host</TT><P>. If </P><TT class=variable>host</TT><P> 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.</P><P>This function works by completing the structure </P><TT class=variable>host-entry</TT><P>.
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.</P></BLOCKQUOTE><P><BR>
<BR>
<A NAME="@types46"></A></P><DIV align=left>
[structure]<BR>
<TT class=function-name>host-entry</TT>
</DIV><BLOCKQUOTE CLASS="quote"><TT class=variable>name</TT> <TT class=variable>aliases</TT>
<TT class=variable>addr-type</TT> <TT class=variable>addr-list</TT><P>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
</P><TT class=variable>addr-type</TT><P> contains the number of the address family, as
specified in <TT>socket.h</TT>, to which the addresses belong. Since
only addresses of the IPv4 family are currently supported, this slot
always has the value 2.</P></BLOCKQUOTE><P><BR>
<A NAME="@funs263"></A><A NAME="FN:ip-string"></A></P><DIV align=left>
[Function]<BR>
<TT class=function-name>extensions:</TT><TT class=function-name>ip-string</TT> <TT class=variable>addr</TT>
</DIV><BLOCKQUOTE CLASS="quote"><P>This function takes an IP address in host order and returns a string
containing it in dotted format.</P></BLOCKQUOTE><H2 CLASS="section"><A NAME="toc283"></A><A NAME="htoc280">10.3</A>  Binding to Interfaces</H2><P>In this section, functions for creating sockets bound to an interface
are documented.</P><P><BR>
<A NAME="@funs264"></A><A NAME="FN:create-inet-listener"></A></P><DIV align=left>
[Function]<BR>
<TT class=function-name>extensions:</TT><TT class=function-name>create-inet-listener</TT> <TT class=variable>port</TT> <TT class=code>&optional</TT> <TT class=variable>kind</TT> <TT class=code>&key</TT> <SPAN style="text-decoration:overline"><TT class=code>:reuse-address</TT> <TT class=code>:backlog</TT> <TT class=code>:host</TT></SPAN>
</DIV><BLOCKQUOTE CLASS="quote"><P>Creates a socket and binds it to a port, prepared to receive
connections of kind </P><TT class=variable>kind</TT><P> (which defaults to </P><TT class=code>:stream</TT><P>),
queuing up to </P><TT class=variable>backlog</TT><P> of them. If </P><TT class=code>:reuse-address</TT><TT class=variable>T</TT><P>
is used, the option SO_REUSEADDR is used in the call to </P><TT class=variable>bind</TT><P>.
If no value is given for </P><TT class=code>:host</TT><P>, it will try to bind to the
default IP address of the machine where the Lisp process is running.</P></BLOCKQUOTE><P><BR>
<A NAME="@funs265"></A><A NAME="FN:create-unix-listener"></A></P><DIV align=left>
[Function]<BR>
<TT class=function-name>extensions:</TT><TT class=function-name>create-unix-listener</TT> <TT class=variable>path</TT> <TT class=code>&optional</TT> <TT class=variable>kind</TT> <TT class=code>&key</TT> <SPAN style="text-decoration:overline">
<TT class=code>:backlog</TT></SPAN>
</DIV><BLOCKQUOTE CLASS="quote"><P>Creates a socket and binds it to the file name given by </P><TT class=variable>path</TT><P>,
prepared to receive connections of kind </P><TT class=variable>kind</TT><P> (which defaults
to </P><TT class=code>:stream</TT><P>), queuing up to </P><TT class=variable>backlog</TT><P> of them.
</P></BLOCKQUOTE><H2 CLASS="section"><A NAME="toc284"></A><A NAME="htoc281">10.4</A>  Accepting Connections</H2><P>Once a socket is bound to its interface, we have to explicitly accept
connections. This task is performed by the functions we document here.</P><P><BR>
<A NAME="@funs266"></A><A NAME="FN:accept-tcp-connection"></A></P><DIV align=left>
[Function]<BR>
<TT class=function-name>extensions:</TT><TT class=function-name>accept-tcp-connection</TT> <TT class=variable>unconnected</TT>
</DIV><BLOCKQUOTE CLASS="quote"><P>Waits until a connection arrives on the (internet family) socket
</P><TT class=variable>unconnected</TT><P>. Returns the file descriptor of the connection.
These can be conveniently encapsulated using file descriptor
streams; see <A HREF="unix.html#sec:fds">6.7</A>.</P></BLOCKQUOTE><P><BR>
<A NAME="@funs267"></A><A NAME="FN:accept-unix-connection"></A></P><DIV align=left>
[Function]<BR>
<TT class=function-name>extensions:</TT><TT class=function-name>accept-unix-connection</TT> <TT class=variable>unconnected</TT>
</DIV><BLOCKQUOTE CLASS="quote"><P>Waits until a connection arrives on the (unix family) socket
</P><TT class=variable>unconnected</TT><P>. Returns the file descriptor of the connection.
These can be conveniently encapsulated using file descriptor
streams; see <A HREF="unix.html#sec:fds">6.7</A>.</P></BLOCKQUOTE><P><BR>
<A NAME="@funs268"></A><A NAME="FN:accept-network-stream"></A></P><DIV align=left>
[Function]<BR>
<TT class=function-name>extensions:</TT><TT class=function-name>accept-network-stream</TT> <TT class=variable>socket</TT> <TT class=code>&key</TT> <SPAN style="text-decoration:overline"><TT class=code>:buffering</TT> <TT class=code>:timeout</TT> <TT class=code>:wait-max</TT></SPAN>
</DIV><BLOCKQUOTE CLASS="quote"><P>Accept a connect from the specified </P><TT class=variable>socket</TT><P> and returns a stream
connected to connection.
</P></BLOCKQUOTE><H2 CLASS="section"><A NAME="toc285"></A><A NAME="htoc282">10.5</A>  Connecting</H2><P>The task performed by the functions we present next is connecting to
remote hosts.</P><P><BR>
<A NAME="@funs269"></A><A NAME="FN:connect-to-inet-socket"></A></P><DIV align=left>
[Function]<BR>
<TT class=function-name>extensions:</TT><TT class=function-name>connect-to-inet-socket</TT> <TT class=variable>host</TT> <TT class=variable>port</TT> <TT class=code>&optional</TT> <TT class=variable>kind</TT>
<TT class=code>&key</TT> <SPAN style="text-decoration:overline"><TT class=code>:local-host</TT> <TT class=code>:local-port</TT></SPAN>
</DIV><BLOCKQUOTE CLASS="quote"><P>Tries to open a connection to the remote host </P><TT class=variable>host</TT><P> (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 </P><TT class=variable>port</TT><P>. Returns the
file descriptor of the connection. The optional parameter
</P><TT class=variable>kind</TT><P> can be either </P><TT class=code>:stream</TT><P> (the default) or </P><TT class=code>:datagram</TT><P>.</P><P>If </P><TT class=variable>local-host</TT><P> and </P><TT class=variable>local-port</TT><P> are specified, the socket
that is created is also bound to the specified </P><TT class=variable>local-host</TT><P> and
</P><TT class=variable>port</TT><P>.</P></BLOCKQUOTE><P><BR>
<A NAME="@funs270"></A><A NAME="FN:connect-to-unix-socket"></A></P><DIV align=left>
[Function]<BR>
<TT class=function-name>extensions:</TT><TT class=function-name>connect-to-unix-socket</TT> <TT class=variable>path</TT> <TT class=code>&optional</TT> <TT class=variable>kind</TT>
</DIV><BLOCKQUOTE CLASS="quote"><P>Opens a connection to the unix “address” given by </P><TT class=variable>path</TT><P>.
Returns the file descriptor of the connection. The type of
connection is given by </P><TT class=variable>kind</TT><P>, which can be either </P><TT class=code>:stream</TT><P>
(the default) or </P><TT class=code>:datagram</TT><P>.</P></BLOCKQUOTE><P><BR>
<A NAME="@funs271"></A><A NAME="FN:open-network-stream"></A></P><DIV align=left>
[Function]<BR>
<TT class=function-name>extensions:</TT><TT class=function-name>open-network-stream</TT> <TT class=variable>host</TT> <TT class=variable>port</TT> <TT class=code>&key</TT> <SPAN style="text-decoration:overline"><TT class=code>:buffering</TT> <TT class=code>:timeout</TT></SPAN>
</DIV><BLOCKQUOTE CLASS="quote"><P>Return a stream connected to the specified </P><TT class=variable>port</TT><P> on the given </P><TT class=variable>host</TT><P>.
</P></BLOCKQUOTE><H2 CLASS="section"><A NAME="toc286"></A><A NAME="htoc283">10.6</A>  Out-of-Band Data</H2><P>
<A NAME="internet-oob"></A></P><P>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.</P><P><BR>
<A NAME="@funs272"></A><A NAME="FN:add-oob-handler"></A></P><DIV align=left>
[Function]<BR>
<TT class=function-name>extensions:</TT><TT class=function-name>add-oob-handler</TT> <TT class=variable>fd</TT> <TT class=variable>char</TT> <TT class=variable>handler</TT>
</DIV><BLOCKQUOTE CLASS="quote"><P>Sets the function passed in </P><TT class=variable>handler</TT><P> as a handler for the
character </P><TT class=variable>char</TT><P> on the connection whose descriptor is </P><TT class=variable>fd</TT><P>.
In case this character arrives, the function in </P><TT class=variable>handler</TT><P> is
called without any argument.</P></BLOCKQUOTE><P><BR>
<A NAME="@funs273"></A><A NAME="FN:remove-oob-handler"></A></P><DIV align=left>
[Function]<BR>
<TT class=function-name>extensions:</TT><TT class=function-name>remove-oob-handler</TT> <TT class=variable>fd</TT> <TT class=variable>char</TT>
</DIV><BLOCKQUOTE CLASS="quote"><P>Removes the handler for the character </P><TT class=variable>char</TT><P> from the connection
with the file descriptor </P><TT class=variable>fd</TT></BLOCKQUOTE><P><BR>
<A NAME="@funs274"></A><A NAME="FN:remove-all-oob-handlers"></A></P><DIV align=left>
[Function]<BR>
<TT class=function-name>extensions:</TT><TT class=function-name>remove-all-oob-handlers</TT> <TT class=variable>fd</TT>
</DIV><BLOCKQUOTE CLASS="quote"><P>After calling this function, the connection whose descriptor is
</P><TT class=variable>fd</TT><P> will ignore any out-of-band character it receives.</P></BLOCKQUOTE><P><BR>
<A NAME="@funs275"></A><A NAME="FN:send-character-out-of-band"></A></P><DIV align=left>
[Function]<BR>
<TT class=function-name>extensions:</TT><TT class=function-name>send-character-out-of-band</TT> <TT class=variable>fd</TT> <TT class=variable>char</TT>
</DIV><BLOCKQUOTE CLASS="quote"><P>Sends the character </P><TT class=variable>char</TT><P> through the connection </P><TT class=variable>fd</TT><P> out
of band.</P></BLOCKQUOTE><H2 CLASS="section"><A NAME="toc287"></A><A NAME="htoc284">10.7</A>  Unbound Sockets, Socket Options, and Closing Sockets</H2><P>These functions create unbound sockets. This is usually not necessary,
since connectors and listeners create their own.</P><P><BR>
<A NAME="@funs276"></A><A NAME="FN:create-unix-socket"></A></P><DIV align=left>
[Function]<BR>
<TT class=function-name>extensions:</TT><TT class=function-name>create-unix-socket</TT> <TT class=code>&optional</TT> <TT class=variable>type</TT>
</DIV><BLOCKQUOTE CLASS="quote"><P>Creates a unix socket for the unix address family, of type
</P><TT class=variable>:stream</TT><P> and (on success) returns its file descriptor.</P></BLOCKQUOTE><P><BR>
<A NAME="@funs277"></A><A NAME="FN:create-inet-socket"></A></P><DIV align=left>
[Function]<BR>
<TT class=function-name>extensions:</TT><TT class=function-name>create-inet-socket</TT> <TT class=code>&optional</TT> <TT class=variable>kind</TT>
</DIV><BLOCKQUOTE CLASS="quote"><P>Creates a unix socket for the internet address family, of type
</P><TT class=variable>:stream</TT><P> and (on success) returns its file descriptor.</P></BLOCKQUOTE><P>
<BR>
<BR>
</P><P>Once a socket is created, it is sometimes useful to bind the socket to a
local address using </P><TT class=code>bind-inet-socket</TT><P>:</P><P><BR>
<A NAME="@funs278"></A><A NAME="FN:bind-inet-socket"></A></P><DIV align=left>
[Function]<BR>
<TT class=function-name>extensions:</TT><TT class=function-name>bind-inet-socket</TT> <TT class=variable>socket</TT> <TT class=variable>host</TT> <TT class=variable>port</TT>
</DIV><BLOCKQUOTE CLASS="quote"><P>Bind the </P><TT class=variable>socket</TT><P> to a local interface address specified
by </P><TT class=variable>host</TT><P> and </P><TT class=variable>port</TT><P>. </P></BLOCKQUOTE><P>
<BR>
<BR>
</P><P>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 <TT>getsockopt</TT> and <TT>setsockopt</TT>.</P><P><BR>
<A NAME="@funs279"></A><A NAME="FN:get-socket-option"></A></P><DIV align=left>
[Function]<BR>
<TT class=function-name>extensions:</TT><TT class=function-name>get-socket-option</TT> <TT class=variable>socket</TT> <TT class=variable>level</TT> <TT class=variable>optname</TT>
</DIV><BLOCKQUOTE CLASS="quote"><P>Gets the value of option </P><TT class=variable>optname</TT><P> from the socket </P><TT class=variable>socket</TT><P>.</P></BLOCKQUOTE><P><BR>
<A NAME="@funs280"></A><A NAME="FN:set-socket-option"></A></P><DIV align=left>
[Function]<BR>
<TT class=function-name>extensions:</TT><TT class=function-name>set-socket-option</TT> <TT class=variable>socket</TT> <TT class=variable>level</TT> <TT class=variable>optname</TT> <TT class=variable>optval</TT>
</DIV><BLOCKQUOTE CLASS="quote"><P>Sets the value of option </P><TT class=variable>optname</TT><P> from the socket </P><TT class=variable>socket</TT><P>
to the value </P><TT class=variable>optval</TT><P>.</P></BLOCKQUOTE><P>
<BR>
<BR>
</P><P>For information on possible options and values we refer to the
manpages of <TT>getsockopt</TT> and <TT>setsockopt</TT>, and to <TT>socket.h</TT></P><P>Finally, the function</P><P><BR>
<A NAME="@funs281"></A><A NAME="FN:close-socket"></A></P><DIV align=left>
[Function]<BR>
<TT class=function-name>extensions:</TT><TT class=function-name>close-socket</TT> <TT class=variable>socket</TT>
</DIV><BLOCKQUOTE CLASS="quote"><P>Closes the socket given by the file descriptor </P><TT class=variable>socket</TT><P>.</P></BLOCKQUOTE><H2 CLASS="section"><A NAME="toc288"></A><A NAME="htoc285">10.8</A>  Unix Datagrams</H2><P>Datagram network is supported with the following functions.</P><P><BR>
<A NAME="@funs282"></A><A NAME="FN:inet-recvfrom"></A></P><DIV align=left>
[Function]<BR>
<TT class=function-name>extensions:</TT><TT class=function-name>inet-recvfrom</TT> <TT class=variable>fd</TT> <TT class=variable>buffer</TT> <TT class=variable>size</TT>
<TT class=code>&key</TT> <SPAN style="text-decoration:overline"><TT class=code>:flags</TT></SPAN>
</DIV><BLOCKQUOTE CLASS="quote">
A simple interface to the Unix <TT class=code>recvfrom</TT> function. Returns
three values: bytecount, source address as integer, and source
port. Bytecount can of course be negative, to indicate faults.
</BLOCKQUOTE><P><BR>
<A NAME="@funs283"></A><A NAME="FN:inet-sendto"></A></P><DIV align=left>
[Function]<BR>
<TT class=function-name>extensions:</TT><TT class=function-name>inet-sendto</TT> <TT class=variable>fd</TT> <TT class=variable>buffer</TT> <TT class=variable>size</TT> <TT class=variable>addr</TT> <TT class=variable>port</TT>
<TT class=code>&key</TT> <SPAN style="text-decoration:overline"><TT class=code>:flags</TT></SPAN>
</DIV><BLOCKQUOTE CLASS="quote">
A simple interface to the Unix <TT class=code>sendto</TT> function.
</BLOCKQUOTE><P><BR>
<A NAME="@funs284"></A><A NAME="FN:inet-shutdown"></A></P><DIV align=left>
[Function]<BR>
<TT class=function-name>extensions:</TT><TT class=function-name>inet-shutdown</TT> <TT class=variable>fd</TT> <TT class=variable>level</TT>
</DIV><BLOCKQUOTE CLASS="quote"><P>A simple interface to the Unix </P><TT class=code>shutdown</TT><P> function. For
</P><TT class=code>level</TT><P>, you may use the following symbols to close one or
both ends of a socket: </P><TT class=code>shut-rd</TT><P>, </P><TT class=code>shut-wr</TT><P>,
</P><TT class=code>shut-rdwr</TT><P>.</P></BLOCKQUOTE><H2 CLASS="section"><A NAME="toc289"></A><A NAME="htoc286">10.9</A>  Errors</H2><P>Errors that occur during socket operations signal a
</P><TT class=code>socket-error</TT><P> condition, a subtype of the </P><TT class=code>error</TT><P>
condition. Currently this condition includes just the Unix
</P><TT class=code>errno</TT><P> associated with the error.
</P><HR>
<A HREF="ipc.html"><IMG SRC="previous_motif.gif" ALT="Previous"></A>
<A HREF="index.html"><IMG SRC="contents_motif.gif" ALT="Up"></A>
<A HREF="debug-internals.html"><IMG SRC="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
|