source: trunk/source/doc/src/sockets.xml @ 8820

Last change on this file since 8820 was 8820, checked in by jaj, 12 years ago

This commit includes support for docbook 4.5, stylesheet changes, and updated documentation.

In order to support docbook 4.5 in nXML mode, I have added a new directory called docbook-rng-4.5 and changed schemas.xml to point to it. This should just work when editing the documentation in EMACS.

The two most obvious changes to the stylesheets are that the table of contents for each chapter now occurs at the beginning of the chapter, and the format for refentries is cleaner and more concise.

I think that we should consistently use refentry elements for all of the definitions of functions, macros, variables, etc. This retains the structured data for the definitions that can be reformatted to have different appearences by the stylesheets. We should also consistently use other docbook elements such as function and varname. I'm not really happy with their appearance right now, but that can be easily tweaked in the stylesheets as long as they are consistently used throughout the documentation.

File size: 36.2 KB
Line 
1<?xml version="1.0" encoding="utf-8"?>
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
3<!ENTITY rest "<varname>&amp;rest</varname>">
4<!ENTITY key "<varname>&amp;key</varname>">
5<!ENTITY optional "<varname>&amp;optional</varname>">
6<!ENTITY body "<varname>&amp;body</varname>">
7<!ENTITY aux "<varname>&amp;aux</varname>">
8<!ENTITY allow-other-keys "<varname>&amp;allow-other-keys</varname>">
9<!ENTITY CCL "Clozure CL">
10]>
11
12  <chapter id="Programming-with-Sockets">
13    <title>Programming with Sockets</title>
14
15    <sect1 id="Sockets-Overview">
16      <title>Overview</title>
17
18      <para>&CCL; supports the socket abstraction for
19      interprocess communication. A socket represents a connection to
20      another process, typically (but not necessarily) a TCP/IP
21      network connection to a client or server running on some other
22      machine on the network.</para>
23      <para>All symbols mentioned in this chapter are exported from
24      the CCL package. As of version 0.13, these symbols are
25      additionally exported from the OPENMCL-SOCKET package.</para>
26      <para>&CCL; supports three types of sockets: TCP sockets, UDP
27      sockets, and Unix-domain sockets.  This should be enough for all
28      but the most esoteric network situations.  All sockets are
29      created by <xref linkend="f_make-socket"/>.  The type of socket
30      depends on the arguments to it, as follows:</para>
31
32      <variablelist>
33        <varlistentry>
34          <term>tcp-stream</term>
35
36          <listitem>
37            <para>A buffered bi-directional stream over a TCP/IP connection.
38            tcp-stream is a subclass of stream, and you can read and write to it
39            using all the usual stream functions. Created by (make-socket
40            :addess-family :internet :type :stream :connect :active ...) or by
41            (accept-connection ...).</para>
42          </listitem>
43        </varlistentry>
44
45        <varlistentry>
46          <term>file-socket-stream</term>
47
48          <listitem>
49            <para>A buffered bi-directional stream over a &#34;UNIX domain&#34;
50            connection. file-socket-stream is a subclass of stream, and you can
51            read and write to it using all the usual stream functions. Created
52            by (make-socket :address-family :file :type :stream :connect :active
53            ...) or by (accept-connection ...),</para>
54          </listitem>
55        </varlistentry>
56
57        <varlistentry>
58          <term>listener-socket</term>
59
60          <listitem>
61            <para>A passive socket used to listen for incoming TCP/IP
62            connections on a particular port. A listener-socket is not a stream.
63            It doesn&#39;t support I/O. It can only be used to create new
64            tcp-streams by accept-connection. Created by (make-socket :type
65            :stream :connect :passive ...)</para>
66          </listitem>
67        </varlistentry>
68
69        <varlistentry>
70          <term>file-listener-socket</term>
71
72          <listitem>
73            <para>A passive socket used to listen for incoming UNIX domain
74            connections named by a file in the local filesystem. A
75            listener-socket is not a stream. It doesn&#39;t support I/O. It can
76            only be used to create new file-socket-streams by accept-connection.
77            Created by (make-socket :address-family :file :type :stream :connect
78            :passive ...)</para>
79          </listitem>
80        </varlistentry>
81
82        <varlistentry>
83          <term>udp-socket</term>
84
85          <listitem>
86            <para>A socket representing a packet-based UDP/IP connection. A
87            udp-socket supports I/O but it is not a stream. Instead, you must
88            use the special functions send-to and receive-from to read and write
89            to it. Created by (make-socket :type :datagram ...)</para>
90          </listitem>
91        </varlistentry>
92      </variablelist>
93    </sect1>
94
95    <sect1 id="Sockets-Dictionary">
96      <title>Sockets Dictionary</title>
97      <refentry id="f_make-socket">
98        <indexterm zone="f_make-socket">
99          <primary>make-socket</primary>
100        </indexterm>
101        <refnamediv>
102          <refname>MAKE-SOCKET</refname>
103          <refpurpose></refpurpose>
104          <refclass>Function</refclass>
105        </refnamediv>
106
107        <refsynopsisdiv>
108          <synopsis><function>make-socket</function> &key;
109          address-family type connect eol format remote-host
110          remote-port local-host local-port local-filename
111          remote-filename keepalive reuse-address nodelay broadcast
112          linger backlog input-timeout output-timeout connect-timeout
113          auto-close deadline</synopsis>
114        </refsynopsisdiv>
115
116        <refsect1>
117          <title>Arguments and Values</title>
118
119          <variablelist>
120            <varlistentry>
121              <term>address-family</term>
122
123              <listitem>
124                <para>The address/protocol family of this socket. Currently
125                only :internet (the default), meaning IP, and :file,
126                referring to UNIX domain addresses, are supported.</para>
127              </listitem>
128            </varlistentry>
129
130            <varlistentry>
131              <term>type</term>
132
133              <listitem>
134                <para>One of :stream (the default) to request a
135                connection-oriented socket, or :datagram to request a
136                connectionless socket. The default is :stream.</para>
137              </listitem>
138            </varlistentry>
139
140            <varlistentry>
141              <term>connect</term>
142
143              <listitem>
144                <para>This argument is only relevant to sockets of type
145                :stream. One of :active (the default) to request a :passive
146                to request a file or TCP listener socket.</para>
147              </listitem>
148            </varlistentry>
149
150            <varlistentry>
151              <term>eol</term>
152
153              <listitem>
154                <para>This argument is currently ignored (it is accepted for
155                compatibility with Franz Allegro).</para>
156              </listitem>
157            </varlistentry>
158
159            <varlistentry>
160              <term>format</term>
161
162              <listitem>
163                <para>One of :text (the default), :binary, or :bivalent.
164                This argument is ignored for :stream sockets for now, as
165                :stream sockets are currently always bivalent (i.e. they
166                support both character and byte I/O). For :datagram sockets,
167                the format determines the type of buffer created by
168                receive-from.</para>
169              </listitem>
170            </varlistentry>
171
172            <varlistentry>
173              <term>remote-host</term>
174
175              <listitem>
176                <para>Required for TCP streams, it specifies the host to
177                connect to (in any format acceptable to lookup-hostname).
178                Ignored for listener sockets. For UDP sockets, it can be
179                used to specify a default host for subsequent calls to
180                send-to or receive-from.</para>
181              </listitem>
182            </varlistentry>
183
184            <varlistentry>
185              <term>remote-port</term>
186
187              <listitem>
188                <para>Required for TCP streams, it specifies the port to
189                connect to (in any format acceptable to lookup-port).
190                Ignored for listener sockets. For UDP sockets, it can be
191                used to specify a default port for subsequent calls to for
192                subsequent calls to send-to or receive-from.</para>
193              </listitem>
194            </varlistentry>
195
196            <varlistentry>
197              <term>remote-filename</term>
198
199              <listitem>
200                <para>Required for file-socket streams, it specifies the
201                name of a file in the local filesystem (e.g., NOT mounted
202                via NFS, AFP, SMB, ...) which names and controls access to a
203                UNIX-domain socket.</para>
204              </listitem>
205            </varlistentry>
206
207            <varlistentry>
208              <term>local-host</term>
209
210              <listitem>
211                <para>Allows you to specify a local host address for a
212                listener or UDP socket, for the rare case where you want to
213                restrict connections to those coming to a specific local
214                address for security reasons.</para>
215              </listitem>
216            </varlistentry>
217
218            <varlistentry>
219              <term>local-port</term>
220
221              <listitem>
222                <para>Specify a local port for a socket. Most useful for
223                listener sockets, where it is the port on which the socket
224                will listen for connections.</para>
225              </listitem>
226            </varlistentry>
227
228            <varlistentry>
229              <term>local-filename</term>
230
231              <listitem>
232                <para>Required for file-listener-sockets. Specifies the name
233                of a file in the local filesystem which is used to name a
234                UNIX-domain socket. The actual filesystem file should not
235                previously exist when the file-listener-socket is created;
236                its parent directory should exist and be writable by the
237                caller. The file used to name the socket will be deleted
238                when the file-listener-socket is closed.</para>
239              </listitem>
240            </varlistentry>
241
242            <varlistentry>
243              <term>keepalive</term>
244
245              <listitem>
246                <para>If true, enables the periodic transmission of
247                &#34;keepalive&#34; messages.</para>
248              </listitem>
249            </varlistentry>
250
251            <varlistentry>
252              <term>reuse-address</term>
253
254              <listitem>
255                <para>If true, allows the reuse of local ports in listener
256                sockets, overriding some TCP/IP protocol specifications. You
257                will need this if you are debugging a server..</para>
258              </listitem>
259            </varlistentry>
260
261            <varlistentry>
262              <term>nodelay</term>
263
264              <listitem>
265                <para>If true, disables Nagle&#39;s algorithm, which tries
266                to minimize TCP packet fragmentation by introducing
267                transmission delays in the absence of replies. Try setting
268                this if you are using a protocol which involves sending a
269                steady stream of data with no replies and are seeing
270                significant degradations in throughput.</para>
271              </listitem>
272            </varlistentry>
273
274            <varlistentry>
275              <term>broadcast</term>
276
277              <listitem>
278                <para>If true, requests permission to broadcast datagrams on
279                a UDP socket.</para>
280              </listitem>
281            </varlistentry>
282
283            <varlistentry>
284              <term>linger</term>
285
286              <listitem>
287                <para>If specified and non-nil, should be the number of
288                seconds the OS is allowed to wait for data to be pushed
289                through when a close is done. Only relevant for TCP sockets.</para>
290              </listitem>
291            </varlistentry>
292
293            <varlistentry>
294              <term>backlog</term>
295
296              <listitem>
297                <para>For a listener socket, specifies the number of
298                connections which can be pending but not accepted. The
299                default is 5, which is also the maximum on some operating
300                systems.</para>
301              </listitem>
302            </varlistentry>
303
304            <varlistentry>
305              <term>input-timeout</term>
306
307              <listitem>
308                <para>The number of seconds before an input operation
309                times out.  Must be a real number between zero and one
310                million.  If an input operation takes longer than the
311                specified number of seconds, an
312                <literal>input-timeout</literal> error is signalled.
313                (see <xref
314                linkend="Stream-Timeouts-And-Deadlines"/>)</para>
315              </listitem>
316            </varlistentry>
317
318            <varlistentry>
319              <term>output-timeout</term>
320
321              <listitem>
322                <para>The number of seconds before an output operation
323                times out.  Must be a real number between zero and one
324                million.  If an output operation takes longer than the
325                specified number of seconds, an
326                <literal>output-timeout</literal> error is signalled.
327                (see <xref
328                linkend="Stream-Timeouts-And-Deadlines"/>)</para>
329              </listitem>
330            </varlistentry>
331
332            <varlistentry>
333              <term>connect-timeout</term>
334
335              <listitem>
336                <para>The number of seconds before a connection
337                attempt times out. [TODO: what are acceptable values?]
338                If a connection attempt takes longer than the
339                specified number of seconds, a
340                <literal>socket-error</literal> is signalled.  This
341                can be useful if the specified interval is shorter
342                than the interval that the OS's socket layer imposes,
343                which is sometimes a minute or two.</para>
344              </listitem>
345            </varlistentry>
346
347            <varlistentry>
348              <term>auto-close</term>
349
350              <listitem>
351                <para>When non-nil, any resulting socket stream will
352                be closed when the GC can prove that the stream is
353                unreferenced.  This is done via CCL's termination
354                mechanism [TODO add xref].</para>
355              </listitem>
356            </varlistentry>
357            <varlistentry>
358              <term>deadline</term>
359
360              <listitem>
361                <para>Specifies an absolute time in
362                internal-time-units.  If an I/O operation on the
363                stream does not complete before the deadline then a
364                <literal>COMMUNICATION-DEADLINE-EXPIRED</literal>
365                error is signalled.  A deadline takes precedence over
366                any input/output timeouts that may be set.  (see <xref
367                linkend="Stream-Timeouts-And-Deadlines"/>)</para>
368              </listitem>
369            </varlistentry>
370
371          </variablelist>
372        </refsect1>
373
374        <refsect1>
375          <title>Description</title>
376
377          <para>Creates and returns a new socket</para>
378        </refsect1>
379      </refentry>
380
381      <refentry id="f_accept-connection">
382        <indexterm zone="f_accept-connection">
383          <primary>accept-connection</primary>
384        </indexterm>
385        <refnamediv>
386          <refname>ACCEPT-CONNECTION</refname>
387          <refpurpose></refpurpose>
388          <refclass>Function</refclass>
389        </refnamediv>
390
391        <refsynopsisdiv>
392          <synopsis><function>accept-connection</function>
393          (socket listener-socket) &key; wait</synopsis>
394        </refsynopsisdiv>
395
396        <refsect1>
397          <title>Arguments and Values</title>
398
399          <variablelist>
400            <varlistentry>
401              <term>socket</term>
402
403              <listitem>
404                <para>The listener-socket to listen on.</para>
405              </listitem>
406            </varlistentry>
407
408            <varlistentry>
409              <term>wait</term>
410
411              <listitem>
412                <para>If true (the default), and there are no connections
413                waiting to be accepted, waits until one arrives. If false,
414                returns NIL immediately.</para>
415              </listitem>
416            </varlistentry>
417          </variablelist>
418        </refsect1>
419
420        <refsect1>
421          <title>Description</title>
422
423          <para>Extracts the first connection on the queue of pending
424          connections, accepts it (i.e. completes the connection startup
425          protocol) and returns a new tcp-stream or file-socket-stream
426          representing the newly established connection. The tcp stream
427          inherits any properties of the listener socket that are relevant
428          (e.g. :keepalive, :nodelay, etc.) The original listener socket
429          continues to be open listening for more connections, so you can
430          call accept-connection on it again.</para>
431        </refsect1>
432      </refentry>
433
434      <refentry id="f_dotted-to-ipaddr">
435        <indexterm zone="f_dotted-to-ipaddr">
436          <primary>dotted-to-ipaddr</primary>
437        </indexterm>
438        <refnamediv>
439          <refname>DOTTED-TO-IPADDR</refname>
440          <refpurpose></refpurpose>
441          <refclass>Function</refclass>
442        </refnamediv>
443
444        <refsynopsisdiv>
445          <synopsis><function>dotted-to-ipaddr</function>
446          dotted &key; errorp</synopsis>
447        </refsynopsisdiv>
448
449        <refsect1>
450          <title>Arguments and Values</title>
451
452          <variablelist>
453            <varlistentry>
454              <term>dotted</term>
455
456              <listitem>
457                <para>A string representing an IP address in the
458                &#34;nn.nn.nn.nn&#34; format</para>
459              </listitem>
460            </varlistentry>
461
462            <varlistentry>
463              <term>errorp</term>
464
465              <listitem>
466                <para>If true (the default) an error is signaled if dotted
467                is invalid. If false, NIL is returned.</para>
468              </listitem>
469            </varlistentry>
470          </variablelist>
471        </refsect1>
472
473        <refsect1>
474          <title>Description</title>
475
476          <para>Converts a dotted-string representation of a host address to
477          a 32-bit unsigned IP address.</para>
478        </refsect1>
479      </refentry>
480
481      <refentry id="f_ipaddr-to-dotted">
482        <indexterm zone="f_ipaddr-to-dotted">
483          <primary>ipaddr-to-dotted</primary>
484        </indexterm>
485        <refnamediv>
486          <refname>IPADDR-TO-DOTTED</refname>
487          <refpurpose></refpurpose>
488          <refclass>Function</refclass>
489        </refnamediv>
490
491        <refsynopsisdiv>
492          <synopsis><function>ipaddr-to-dotted</function>
493          ipaddr &key; values</synopsis>
494        </refsynopsisdiv>
495
496        <refsect1>
497          <title>Arguments and Values</title>
498
499          <variablelist>
500            <varlistentry>
501              <term>ipaddr</term>
502
503              <listitem>
504                <para>A 32-bit integer representing an internet host address</para>
505              </listitem>
506            </varlistentry>
507
508            <varlistentry>
509              <term>values</term>
510
511              <listitem>
512                <para>If false (the default), returns a string in the form
513                &#34;nn.nn.nn.nn&#34;. If true, returns four values
514                representing the four octets of the address as unsigned
515                8-bit integers.</para>
516              </listitem>
517            </varlistentry>
518          </variablelist>
519        </refsect1>
520
521        <refsect1>
522          <title>Description</title>
523
524          <para>Converts a 32-bit unsigned IP address into octets.</para>
525        </refsect1>
526      </refentry>
527
528      <refentry id="f_ipaddr-to-hostname">
529        <indexterm zone="f_ipaddr-to-hostname">
530          <primary>ipaddr-to-hostname</primary>
531        </indexterm>
532        <refnamediv>
533          <refname>IPADDR-TO-HOSTNAME</refname>
534          <refpurpose></refpurpose>
535          <refclass>Function</refclass>
536        </refnamediv>
537
538        <refsynopsisdiv>
539          <synopsis><function>ipaddr-to-hostname</function>
540          ipaddr &key; ignore-cache</synopsis>
541        </refsynopsisdiv>
542
543        <refsect1>
544          <title>Arguments and Values</title>
545
546          <variablelist>
547            <varlistentry>
548              <term>ipaddr</term>
549
550              <listitem>
551                <para>a 32-bit integer representing an internet host address</para>
552              </listitem>
553            </varlistentry>
554
555            <varlistentry>
556              <term>ignore-cache</term>
557
558              <listitem>
559                <para>This argument is ignored (it is accepted for
560                compatibility with Franz Allegro)</para>
561              </listitem>
562            </varlistentry>
563          </variablelist>
564        </refsect1>
565
566        <refsect1>
567          <title>Description</title>
568
569          <para>Converts a 32-bit unsigned IP address into a host name
570          string</para>
571        </refsect1>
572      </refentry>
573
574      <refentry id="f_lookup-hostname">
575        <indexterm zone="f_lookup-hostname">
576          <primary>lookup-hostname</primary>
577        </indexterm>
578        <refnamediv>
579          <refname>LOOKUP-HOSTNAME</refname>
580          <refpurpose></refpurpose>
581          <refclass>Function</refclass>
582        </refnamediv>
583
584        <refsynopsisdiv>
585          <synopsis><function>lookup-hostname</function>
586          host</synopsis>
587        </refsynopsisdiv>
588
589        <refsect1>
590          <title>Arguments and Values</title>
591
592          <variablelist>
593            <varlistentry>
594              <term>host</term>
595
596              <listitem>
597                <para>Specifies the host. It can be either a host name
598                string such as &#34;clozure.com&#34;, or a dotted address
599                string such as &#34;192.168.0.1&#34;, or a 32-bit unsigned
600                IP address such as 3232235521.</para>
601              </listitem>
602            </varlistentry>
603          </variablelist>
604        </refsect1>
605
606        <refsect1>
607          <title>Description</title>
608
609          <para>Converts a host spec in any of the acceptable formats into a
610          32-bit unsigned IP address</para>
611        </refsect1>
612      </refentry>
613
614      <refentry id="f_lookup-port">
615        <indexterm zone="f_lookup-port">
616          <primary>lookup-port</primary>
617        </indexterm>
618        <refnamediv>
619          <refname>LOOKUP-PORT</refname>
620          <refpurpose></refpurpose>
621          <refclass>Function</refclass>
622        </refnamediv>
623
624        <refsynopsisdiv>
625          <synopsis><function>lookup-port</function>
626          port protocol</synopsis>
627        </refsynopsisdiv>
628
629        <refsect1>
630          <title>Arguments and Values</title>
631
632          <variablelist>
633            <varlistentry>
634              <term>port</term>
635
636              <listitem>
637                <para>Specifies the port. It can be either a string, such as
638                &#34;http&#34; or a symbol, such as :http, or an unsigned
639                port number. Note that a string is case-sensitive. A symbol
640                is lowercased before lookup.</para>
641              </listitem>
642            </varlistentry>
643
644            <varlistentry>
645              <term>protocol</term>
646
647              <listitem>
648                <para>Must be one of &#34;tcp&#34; or &#34;udp&#34;.</para>
649              </listitem>
650            </varlistentry>
651          </variablelist>
652        </refsect1>
653
654        <refsect1>
655          <title>Description</title>
656
657          <para>Finds the port number for the specified port and protocol</para>
658        </refsect1>
659      </refentry>
660
661      <refentry id="f_receive-from">
662        <indexterm zone="f_receive-from">
663          <primary>receive-from</primary>
664        </indexterm>
665        <refnamediv>
666          <refname>RECEIVE-FROM</refname>
667          <refpurpose></refpurpose>
668          <refclass>Function</refclass>
669        </refnamediv>
670
671        <refsynopsisdiv>
672          <synopsis><function>receive-from</function>
673          (socket udp-socket) size &key; buffer
674          extract offset</synopsis>
675        </refsynopsisdiv>
676
677        <refsect1>
678          <title>Arguments and Values</title>
679
680          <variablelist>
681            <varlistentry>
682              <term>socket</term>
683
684              <listitem>
685                <para>The socket to read from</para>
686              </listitem>
687            </varlistentry>
688
689            <varlistentry>
690              <term>size</term>
691
692              <listitem>
693                <para>Maximum number of bytes to read. If the packet is
694                larger than this, any extra bytes are discarded.</para>
695              </listitem>
696            </varlistentry>
697
698            <varlistentry>
699              <term>buffer</term>
700
701              <listitem>
702                <para>If specified, must be either a string or a byte vector
703                which will be used to read in the data. If not specified, a
704                new buffer will be created (of type determined by
705                socket-format).</para>
706              </listitem>
707            </varlistentry>
708
709            <varlistentry>
710              <term>extract</term>
711
712              <listitem>
713                <para>If true, the subsequence of the buffer corresponding
714                only to the data read in is extracted and returned as the
715                first value. If false (the default) the original buffer is
716                returned even if it is only partially filled.</para>
717              </listitem>
718            </varlistentry>
719
720            <varlistentry>
721              <term>offset</term>
722
723              <listitem>
724                <para>Specifies the start offset into the buffer at which
725                data is to be stored. The default is 0.</para>
726              </listitem>
727            </varlistentry>
728          </variablelist>
729        </refsect1>
730
731        <refsect1>
732          <title>Description</title>
733
734          <para>Reads a UDP packet from a socket. If no packets are
735          available, waits for a packet to arrive. Returns four values:</para>
736
737          <orderedlist continuation="restarts" inheritnum="ignore">
738            <listitem>
739              <para>The buffer with the data</para>
740            </listitem>
741
742            <listitem>
743              <para>The number of bytes read</para>
744            </listitem>
745
746            <listitem>
747              <para>The 32-bit unsigned IP address of the sender of the data</para>
748            </listitem>
749
750            <listitem>
751              <para>The port number of the sender of the data</para>
752            </listitem>
753          </orderedlist>
754        </refsect1>
755      </refentry>
756
757      <refentry id="f_send-to">
758        <indexterm zone="f_send-to">
759          <primary>send-to</primary>
760        </indexterm>
761        <refnamediv>
762          <refname>SEND-TO</refname>
763          <refpurpose></refpurpose>
764          <refclass>Function</refclass>
765        </refnamediv>
766
767        <refsynopsisdiv>
768          <synopsis><function>send-to</function>
769          (socket udp-socket) buffer size &key; remote-host
770          remote-port offset</synopsis>
771        </refsynopsisdiv>
772
773        <refsect1>
774          <title>Arguments and Values</title>
775
776          <variablelist>
777            <varlistentry>
778              <term>socket</term>
779
780              <listitem>
781                <para>The socket to write to</para>
782              </listitem>
783            </varlistentry>
784
785            <varlistentry>
786              <term>buffer</term>
787
788              <listitem>
789                <para>A vector containing the data to send. It must be
790                either a string or a byte vector (either one is acceptable
791                regardless of the stream format).</para>
792              </listitem>
793            </varlistentry>
794
795            <varlistentry>
796              <term>size</term>
797
798              <listitem>
799                <para>Number of bytes to send</para>
800              </listitem>
801            </varlistentry>
802
803            <varlistentry>
804              <term>remote-host</term>
805
806              <listitem>
807                <para>The host to send the packet to, in any format
808                acceptable to lookup-hostname. The default is the remote
809                host specified in the call to make-socket.</para>
810              </listitem>
811            </varlistentry>
812
813            <varlistentry>
814              <term>remote-port</term>
815
816              <listitem>
817                <para>The port to send the packet to, in any format
818                acceptable to lookup-port. The default is the remote port
819                specified in the call to make-socket.</para>
820              </listitem>
821            </varlistentry>
822
823            <varlistentry>
824              <term>offset</term>
825
826              <listitem>
827                <para>The offset in the buffer where the packet data starts</para>
828              </listitem>
829            </varlistentry>
830          </variablelist>
831        </refsect1>
832
833        <refsect1>
834          <title>Description</title>
835
836          <para>Send a UDP packet over a socket.</para>
837        </refsect1>
838      </refentry>
839
840      <refentry id="f_shutdown">
841        <indexterm zone="f_shutdown">
842          <primary>shutdown</primary>
843        </indexterm>
844        <refnamediv>
845          <refname>SHUTDOWN</refname>
846          <refpurpose></refpurpose>
847          <refclass>Function</refclass>
848        </refnamediv>
849
850        <refsynopsisdiv>
851          <synopsis><function>shutdown</function>
852          socket &key; direction</synopsis>
853        </refsynopsisdiv>
854
855        <refsect1>
856          <title>Arguments and Values</title>
857
858          <variablelist>
859            <varlistentry>
860              <term>socket</term>
861
862              <listitem>
863                <para>The socket to shut down (typically a tcp-stream)</para>
864              </listitem>
865            </varlistentry>
866
867            <varlistentry>
868              <term>direction</term>
869
870              <listitem>
871                <para>One of :input to disallow further input, or :output to
872                disallow further output.</para>
873              </listitem>
874            </varlistentry>
875          </variablelist>
876        </refsect1>
877
878        <refsect1>
879          <title>Description</title>
880
881          <para>Shuts down part of a bidirectional connection. This is
882          useful if e.g. you need to read responses after sending an
883          end-of-file signal.</para>
884        </refsect1>
885      </refentry>
886
887      <refentry id="f_socket-os-fd">
888        <indexterm zone="f_socket-os-fd">
889          <primary>socket-os-fd</primary>
890        </indexterm>
891        <refnamediv>
892          <refname>SOCKET-OS-FD</refname>
893          <refpurpose></refpurpose>
894          <refclass>Function</refclass>
895        </refnamediv>
896
897        <refsynopsisdiv>
898          <synopsis><function>socket-os-fd</function>
899          socket</synopsis>
900        </refsynopsisdiv>
901
902        <refsect1>
903          <title>Arguments and Values</title>
904
905          <variablelist>
906            <varlistentry>
907              <term>socket</term>
908
909              <listitem>
910                <para>The socket</para>
911              </listitem>
912            </varlistentry>
913          </variablelist>
914        </refsect1>
915
916        <refsect1>
917          <title>Description</title>
918
919          <para>Returns the native OS&#39;s representation of the socket, or
920          NIL if the socket is closed. On Unix, this is the Unix &#39;file
921          descriptor&#39;, a small non-negative integer. Note that it is
922          rather dangerous to mess around with tcp-stream fd&#39;s, as there
923          is all sorts of buffering and asynchronous I/O going on above the
924          OS level. listener-socket and udp-socket fd&#39;s are safer to
925          mess with directly as there is less magic going on.</para>
926        </refsect1>
927      </refentry>
928
929      <refentry id="f_remote-host">
930        <indexterm zone="f_remote-host">
931          <primary>remote-host</primary>
932        </indexterm>
933        <refnamediv>
934          <refname>REMOTE-HOST</refname>
935          <refpurpose></refpurpose>
936          <refclass>Function</refclass>
937        </refnamediv>
938
939        <refsynopsisdiv>
940          <synopsis><function>remote-host</function>
941          socket</synopsis>
942        </refsynopsisdiv>
943
944        <refsect1>
945          <title>Arguments and Values</title>
946
947          <variablelist>
948            <varlistentry>
949              <term>socket</term>
950
951              <listitem>
952                <para>The socket</para>
953              </listitem>
954            </varlistentry>
955          </variablelist>
956        </refsect1>
957
958        <refsect1>
959          <title>Description</title>
960
961          <para>Returns the 32-bit unsigned IP address of the remote host,
962          or NIL if the socket is not connected.</para>
963        </refsect1>
964      </refentry>
965
966      <refentry id="f_remote-port">
967        <indexterm zone="f_remote-port">
968          <primary>remote-port</primary>
969        </indexterm>
970        <refnamediv>
971          <refname>REMOTE-PORT</refname>
972          <refpurpose></refpurpose>
973          <refclass>Function</refclass>
974        </refnamediv>
975
976        <refsynopsisdiv>
977          <synopsis><function>remote-port</function>
978          socket</synopsis>
979        </refsynopsisdiv>
980
981        <refsect1>
982          <title>Arguments and Values</title>
983
984          <variablelist>
985            <varlistentry>
986              <term>socket</term>
987
988              <listitem>
989                <para>The socket</para>
990              </listitem>
991            </varlistentry>
992          </variablelist>
993        </refsect1>
994
995        <refsect1>
996          <title>Description</title>
997
998          <para>Returns the remote port number, or NIL if the socket is not
999          connected.</para>
1000        </refsect1>
1001      </refentry>
1002
1003      <refentry id="f_local-host">
1004        <indexterm zone="f_local-host">
1005          <primary>local-host</primary>
1006        </indexterm>
1007        <refnamediv>
1008          <refname>LOCAL-HOST</refname>
1009          <refpurpose></refpurpose>
1010          <refclass>Function</refclass>
1011        </refnamediv>
1012
1013        <refsynopsisdiv>
1014          <synopsis><function>local-host</function>
1015          socket</synopsis>
1016        </refsynopsisdiv>
1017
1018        <refsect1>
1019          <title>Arguments and Values</title>
1020
1021          <variablelist>
1022            <varlistentry>
1023              <term>socket</term>
1024
1025              <listitem>
1026                <para>The socket</para>
1027              </listitem>
1028            </varlistentry>
1029          </variablelist>
1030        </refsect1>
1031
1032        <refsect1>
1033          <title>Description</title>
1034
1035          <para>Returns 32-bit unsigned IP address of the local host.</para>
1036        </refsect1>
1037      </refentry>
1038
1039      <refentry id="f_local-port">
1040        <indexterm zone="f_local-port">
1041          <primary>local-port</primary>
1042        </indexterm>
1043        <refnamediv>
1044          <refname>LOCAL-PORT</refname>
1045          <refpurpose></refpurpose>
1046          <refclass>Function</refclass>
1047        </refnamediv>
1048
1049        <refsynopsisdiv>
1050          <synopsis><function>local-port</function>
1051          socket</synopsis>
1052        </refsynopsisdiv>
1053
1054        <refsect1>
1055          <title>Arguments and Values</title>
1056
1057          <variablelist>
1058            <varlistentry>
1059              <term>socket</term>
1060
1061              <listitem>
1062                <para>The socket</para>
1063              </listitem>
1064            </varlistentry>
1065          </variablelist>
1066        </refsect1>
1067
1068        <refsect1>
1069          <title>Description</title>
1070
1071          <para>Returns the local port number</para>
1072        </refsect1>
1073      </refentry>
1074
1075      <refentry id="f_socket-address-family">
1076        <indexterm zone="f_socket-address-family">
1077          <primary>socket-address-family</primary>
1078        </indexterm>
1079        <refnamediv>
1080          <refname>SOCKET-ADDRESS-FAMILY</refname>
1081          <refpurpose></refpurpose>
1082          <refclass>Function</refclass>
1083        </refnamediv>
1084
1085        <refsynopsisdiv>
1086          <synopsis><function>socket-address-family</function>
1087          socket</synopsis>
1088        </refsynopsisdiv>
1089
1090        <refsect1>
1091          <title>Arguments and Values</title>
1092
1093          <variablelist>
1094            <varlistentry>
1095              <term>socket</term>
1096
1097              <listitem>
1098                <para>The socket</para>
1099              </listitem>
1100            </varlistentry>
1101          </variablelist>
1102        </refsect1>
1103
1104        <refsect1>
1105          <title>Description</title>
1106
1107          <para>Returns :internet or :file, as appropriate.</para>
1108        </refsect1>
1109      </refentry>
1110
1111      <refentry id="f_socket-connect">
1112        <indexterm zone="f_socket-connect">
1113          <primary>socket-connect</primary>
1114        </indexterm>
1115        <refnamediv>
1116          <refname>SOCKET-CONNECT</refname>
1117          <refpurpose></refpurpose>
1118          <refclass>Function</refclass>
1119        </refnamediv>
1120
1121        <refsynopsisdiv>
1122          <synopsis><function>socket-connect</function>
1123          socket</synopsis>
1124        </refsynopsisdiv>
1125
1126        <refsect1>
1127          <title>Arguments and Values</title>
1128
1129          <variablelist>
1130            <varlistentry>
1131              <term>socket</term>
1132
1133              <listitem>
1134                <para>The socket</para>
1135              </listitem>
1136            </varlistentry>
1137          </variablelist>
1138        </refsect1>
1139
1140        <refsect1>
1141          <title>Description</title>
1142
1143          <para>Returns :active for tcp-stream, :passive for
1144          listener-socket, and NIL for udp-socket</para>
1145        </refsect1>
1146      </refentry>
1147
1148      <refentry id="f_socket-format">
1149        <indexterm zone="f_socket-format">
1150          <primary>socket-format</primary>
1151        </indexterm>
1152        <refnamediv>
1153          <refname>SOCKET-FORMAT</refname>
1154          <refpurpose></refpurpose>
1155          <refclass>Function</refclass>
1156        </refnamediv>
1157
1158        <refsynopsisdiv>
1159          <synopsis><function>socket-format</function>
1160          socket</synopsis>
1161        </refsynopsisdiv>
1162
1163        <refsect1>
1164          <title>Arguments and Values</title>
1165
1166          <variablelist>
1167            <varlistentry>
1168              <term>socket</term>
1169
1170              <listitem>
1171                <para>The socket</para>
1172              </listitem>
1173            </varlistentry>
1174          </variablelist>
1175        </refsect1>
1176
1177        <refsect1>
1178          <title>Description</title>
1179
1180          <para>Returns the socket format as specified by the :format
1181          argument to make-socket.</para>
1182        </refsect1>
1183      </refentry>
1184
1185      <refentry id="f_socket-type">
1186        <indexterm zone="f_socket-type">
1187          <primary>socket-type</primary>
1188        </indexterm>
1189        <refnamediv>
1190          <refname>SOCKET-TYPE</refname>
1191          <refpurpose></refpurpose>
1192          <refclass>Function</refclass>
1193        </refnamediv>
1194
1195        <refsynopsisdiv>
1196          <synopsis><function>socket-type</function>
1197          socket</synopsis>
1198        </refsynopsisdiv>
1199
1200        <refsect1>
1201          <title>Arguments and Values</title>
1202
1203          <variablelist>
1204            <varlistentry>
1205              <term>socket</term>
1206
1207              <listitem>
1208                <para>The socket</para>
1209              </listitem>
1210            </varlistentry>
1211          </variablelist>
1212        </refsect1>
1213
1214        <refsect1>
1215          <title>Description</title>
1216
1217          <para>returns :stream for tcp-stream and listener-socket, and
1218          :datagram for udp-socket.</para>
1219        </refsect1>
1220      </refentry>
1221
1222      <refentry id="c_socket-error">
1223        <indexterm zone="c_socket-error">
1224          <primary>socket-error</primary>
1225        </indexterm>
1226        <refnamediv>
1227          <refname>SOCKET-ERROR</refname>
1228          <refpurpose></refpurpose>
1229          <refclass>Class</refclass>
1230        </refnamediv>
1231
1232        <refsect1>
1233          <title>Description</title>
1234
1235          <para>The class of OS errors signaled by socket functions</para>
1236        </refsect1>
1237
1238        <refsect1>
1239          <title>Superclasses</title>
1240
1241          <para>simple-error</para>
1242        </refsect1>
1243      </refentry>
1244
1245      <refentry id="f_socket-error-code">
1246        <indexterm zone="f_socket-error-code">
1247          <primary>socket-error-code</primary>
1248        </indexterm>
1249        <refnamediv>
1250          <refname>SOCKET-ERROR-CODE</refname>
1251          <refpurpose></refpurpose>
1252          <refclass>Function</refclass>
1253        </refnamediv>
1254
1255        <refsynopsisdiv>
1256          <synopsis><function>socket-error-code</function>
1257          socket-error</synopsis>
1258        </refsynopsisdiv>
1259
1260        <refsect1>
1261          <title>Arguments and Values</title>
1262
1263          <variablelist>
1264            <varlistentry>
1265              <term>socket-error</term>
1266
1267              <listitem>
1268                <para>the condition</para>
1269              </listitem>
1270            </varlistentry>
1271          </variablelist>
1272        </refsect1>
1273
1274        <refsect1>
1275          <title>Description</title>
1276
1277          <para>The OS error code of the error</para>
1278        </refsect1>
1279      </refentry>
1280
1281      <refentry id="f_socket-error-identifier">
1282        <indexterm zone="f_socket-error-identifier">
1283          <primary>socket-error-identifier</primary>
1284        </indexterm>
1285        <refnamediv>
1286          <refname>SOCKET-ERROR-IDENTIFIER</refname>
1287          <refpurpose></refpurpose>
1288          <refclass>Function</refclass>
1289        </refnamediv>
1290
1291        <refsynopsisdiv>
1292          <synopsis><function>socket-error-identifier</function>
1293          socket-error</synopsis>
1294        </refsynopsisdiv>
1295
1296        <refsect1>
1297          <title>Arguments and Values</title>
1298
1299          <variablelist>
1300            <varlistentry>
1301              <term>socket-error</term>
1302
1303              <listitem>
1304                <para>the condition</para>
1305              </listitem>
1306            </varlistentry>
1307          </variablelist>
1308        </refsect1>
1309
1310        <refsect1>
1311          <title>Description</title>
1312
1313          <para>A symbol representing the error code in a more
1314          OS-independent way.</para>
1315
1316          <para>One of: :address-in-use :connection-aborted :no-buffer-space
1317          :connection-timed-out :connection-refused :host-unreachable
1318          :host-down :network-down :address-not-available :network-reset
1319          :connection-reset :shutdown :access-denied or :unknown.</para>
1320        </refsect1>
1321      </refentry>
1322
1323      <refentry id="f_socket-error-situation">
1324        <indexterm zone="f_socket-error-situation">
1325          <primary>socket-error-situation</primary>
1326        </indexterm>
1327        <refnamediv>
1328          <refname>SOCKET-ERROR-SITUATION</refname>
1329          <refpurpose></refpurpose>
1330          <refclass>Function</refclass>
1331        </refnamediv>
1332
1333        <refsynopsisdiv>
1334          <synopsis><function>socket-error-situation</function>
1335          socket-error</synopsis>
1336        </refsynopsisdiv>
1337
1338        <refsect1>
1339          <title>Arguments and Values</title>
1340
1341          <variablelist>
1342            <varlistentry>
1343              <term>socket-error</term>
1344
1345              <listitem>
1346                <para>the condition</para>
1347              </listitem>
1348            </varlistentry>
1349          </variablelist>
1350        </refsect1>
1351
1352        <refsect1>
1353          <title>Description</title>
1354
1355          <para>A string describing the context where the error happened. On
1356          Linux, this is the name of the system call which returned the
1357          error.</para>
1358        </refsect1>
1359      </refentry>
1360
1361      <refentry id="o_close">
1362        <indexterm zone="o_close">
1363          <primary>close</primary>
1364        </indexterm>
1365        <refnamediv>
1366          <refname>CLOSE</refname>
1367          <refpurpose></refpurpose>
1368          <refclass>Method</refclass>
1369        </refnamediv>
1370
1371        <refsynopsisdiv>
1372          <synopsis><function>close</function>
1373          (socket socket) &key; abort</synopsis>
1374        </refsynopsisdiv>
1375
1376        <refsect1>
1377          <title>Arguments and Values</title>
1378
1379          <variablelist>
1380            <varlistentry>
1381              <term>socket</term>
1382
1383              <listitem>
1384                <para>The socket to close</para>
1385              </listitem>
1386            </varlistentry>
1387
1388            <varlistentry>
1389              <term>abort</term>
1390
1391              <listitem>
1392                <para>If false (the default), closes the socket in an
1393                orderly fashion, finishing up any buffered pending I/O,
1394                before closing the connection. If true, aborts/ignores
1395                pending I/O. (For listener and udp sockets, this argument is
1396                effectively ignored since there is never any buffered I/O to
1397                clean up).</para>
1398              </listitem>
1399            </varlistentry>
1400          </variablelist>
1401        </refsect1>
1402
1403        <refsect1>
1404          <title>Description</title>
1405
1406          <para>The close generic function can be applied to sockets. It
1407          releases the operating system resources associated with the
1408          socket.</para>
1409        </refsect1>
1410      </refentry>
1411
1412      <refentry id="m_with-open-socket">
1413        <indexterm zone="m_with-open-socket">
1414          <primary>with-open-socket</primary>
1415        </indexterm>
1416        <refnamediv>
1417          <refname>WITH-OPEN-SOCKET</refname>
1418          <refpurpose></refpurpose>
1419          <refclass>Macro</refclass>
1420        </refnamediv>
1421
1422        <refsynopsisdiv>
1423          <synopsis><function>with-open-socket</function>
1424          (var . make-socket-args) &body; body</synopsis>
1425        </refsynopsisdiv>
1426
1427        <refsect1>
1428          <title>Arguments and Values</title>
1429
1430          <variablelist>
1431            <varlistentry>
1432              <term>var</term>
1433
1434              <listitem>
1435                <para>variable to bind</para>
1436              </listitem>
1437            </varlistentry>
1438
1439            <varlistentry>
1440              <term>make-socket-args</term>
1441
1442              <listitem>
1443                <para>arguments suitable for passing to make-socket</para>
1444              </listitem>
1445            </varlistentry>
1446
1447            <varlistentry>
1448              <term>body</term>
1449
1450              <listitem>
1451                <para>body to execute</para>
1452              </listitem>
1453            </varlistentry>
1454          </variablelist>
1455        </refsect1>
1456
1457        <refsect1>
1458          <title>Description</title>
1459
1460          <para>executes body with var bound to the result of applying
1461          make-socket to make-socket-args. The socket gets closed on exit.</para>
1462        </refsect1>
1463      </refentry>
1464    </sect1>
1465  </chapter>
Note: See TracBrowser for help on using the repository browser.