2 @comment node-name, next, previous, up
4 @cindex Sockets, Networking
6 The @code{sb-bsd-sockets} module provides a thinly disguised BSD
7 socket API for SBCL. Ideas have been stolen from the BSD socket API
8 for C and Graham Barr's IO::Socket classes for Perl.
10 Sockets are represented as CLOS objects, and the API naming
11 conventions attempt to balance between the BSD names and good lisp style.
15 * General Sockets:: Methods applicable to all sockets
17 * INET Domain Sockets::
18 * Local (Unix) Domain Sockets::
22 @node Sockets Overview
23 @section Sockets Overview
25 Most of the functions are modelled on the BSD socket API. BSD sockets
26 are widely supported, portably @emph{(``portable'' by Unix standards, at least)}
27 available on a variety of systems, and documented. There are some
28 differences in approach where we have taken advantage of some of the
29 more useful features of Common Lisp - briefly:
34 Where the C API would typically return -1 and set @code{errno},
35 @code{sb-bsd-sockets} signals an error. All the errors are subclasses
36 of @code{sb-bsd-sockets:socket-condition} and generally correspond one
37 for one with possible @code{errno} values.
40 We use multiple return values in many places where the C API would use
41 pass-by-reference values.
44 We can often avoid supplying an explicit @emph{length} argument to
45 functions because we already know how long the argument is.
48 IP addresses and ports are represented in slightly friendlier fashion
49 than "network-endian integers".
54 @section General Sockets
56 @include class-sb-bsd-sockets-socket.texinfo
58 @include fun-sb-bsd-sockets-socket-bind.texinfo
60 @include fun-sb-bsd-sockets-socket-accept.texinfo
62 @include fun-sb-bsd-sockets-socket-connect.texinfo
64 @include fun-sb-bsd-sockets-socket-peername.texinfo
66 @include fun-sb-bsd-sockets-socket-name.texinfo
68 @include fun-sb-bsd-sockets-socket-receive.texinfo
70 @include fun-sb-bsd-sockets-socket-listen.texinfo
72 @include fun-sb-bsd-sockets-socket-open-p.texinfo
74 @include fun-sb-bsd-sockets-socket-close.texinfo
76 @include fun-sb-bsd-sockets-socket-make-stream.texinfo
78 @include fun-sb-bsd-sockets-socket-error.texinfo
80 @include fun-sb-bsd-sockets-non-blocking-mode.texinfo
83 @section Socket Options
85 A subset of socket options are supported, using a fairly general
86 framework which should make it simple to add more as required - see
87 @file{SYS:CONTRIB;SB-BSD-SOCKETS:SOCKOPT.LISP} for details. The name
88 mapping from C is fairly straightforward: @code{SO_RCVLOWAT} becomes
89 @code{sockopt-receive-low-water} and @code{(setf
90 sockopt-receive-low-water)}.
92 @include fun-sb-bsd-sockets-sockopt-reuse-address.texinfo
94 @include fun-sb-bsd-sockets-sockopt-keep-alive.texinfo
96 @include fun-sb-bsd-sockets-sockopt-oob-inline.texinfo
98 @include fun-sb-bsd-sockets-sockopt-bsd-compatible.texinfo
100 @include fun-sb-bsd-sockets-sockopt-pass-credentials.texinfo
102 @include fun-sb-bsd-sockets-sockopt-debug.texinfo
104 @include fun-sb-bsd-sockets-sockopt-dont-route.texinfo
106 @include fun-sb-bsd-sockets-sockopt-broadcast.texinfo
108 @include fun-sb-bsd-sockets-sockopt-tcp-nodelay.texinfo
110 @node INET Domain Sockets
111 @section INET Domain Sockets
113 The TCP and UDP sockets that you know and love. Some representation
119 Internet addresses are represented by vectors of (unsigned-byte 8) -
120 viz. #(127 0 0 1). Ports are just integers: 6010. No conversion
121 between network- and host-order data is needed from the user of this
125 Socket addresses are represented by the two values for address and
126 port, so for example, (socket-connect s #(192 168 1 1) 80).
130 @include class-sb-bsd-sockets-inet-socket.texinfo
132 @include fun-sb-bsd-sockets-make-inet-address.texinfo
134 @include fun-sb-bsd-sockets-get-protocol-by-name.texinfo
136 @node Local (Unix) Domain Sockets
137 @section Local (Unix) Domain Sockets
139 Local domain (@code{AF_LOCAL}) sockets are also known as Unix-domain
140 sockets, but were renamed by POSIX presumably on the basis that they
141 may be available on other systems too.
143 A local socket address is a string, which is used to create a node in
144 the local filesystem. This means of course that they cannot be used
147 @include class-sb-bsd-sockets-local-socket.texinfo
150 @section Name Service
152 Presently name service is implemented by calling whatever
153 @code{gethostbyname(2)} uses. This may be any or all of
154 @file{/etc/hosts}, NIS, DNS, or something completely different.
155 Typically it's controlled by @file{/etc/nsswitch.conf}.
157 Direct links to the asynchronous @code{resolver(3)} routines would be
158 nice to have eventually, so that we can do DNS lookups in parallel
161 @include class-sb-bsd-sockets-host-ent.texinfo
163 @include fun-sb-bsd-sockets-get-host-by-name.texinfo
165 @include fun-sb-bsd-sockets-get-host-by-address.texinfo
167 @include fun-sb-bsd-sockets-host-ent-address.texinfo
169 @include fun-sb-bsd-sockets-name-service-error.texinfo