sb-bsd-sockets
==============

The sb-bsd-sockets module provides a thinly disguised BSD socket API for SBCL. Ideas stolen from the BSD socket API for C and Graham Barr's IO::Socket classes for Perl.

Sockets are represented as CLOS objects, and the API naming conventions attempt to balance between the BSD names and good lisp style.

Sockets Overview
----------------

Most of the functions are modelled on the BSD socket API.  BSD sockets are widely supported, portably (``portable'' by Unix standards, at least) available on a variety of systems, and documented.  There are some differences in approach where we have taken advantage of some of the more useful features of Common Lisp - briefly:

  * Where the C API would typically return -1 and set errno, sb-bsd-sockets signals an error. All the errors are subclasses of sb-bsd-sockets:socket-condition and generally correspond one for one with possible errno values.

  * We use multiple return values in many places where the C API would use pass-by-reference values.

  * We can often avoid supplying an explicit length argument to functions because we already know how long the argument is.

  * IP addresses and ports are represented in slightly friendlier fashion than "network-endian integers".

General Sockets
---------------

     [file class-sb-bsd-sockets-socket.texinfo not included]

     [file fun-sb-bsd-sockets-socket-bind.texinfo not included]

     [file fun-sb-bsd-sockets-socket-accept.texinfo not included]

     [file fun-sb-bsd-sockets-socket-connect.texinfo not included]

     [file fun-sb-bsd-sockets-socket-peername.texinfo not included]

     [file fun-sb-bsd-sockets-socket-name.texinfo not included]

     [file fun-sb-bsd-sockets-socket-receive.texinfo not included]

     [file fun-sb-bsd-sockets-socket-listen.texinfo not included]

     [file fun-sb-bsd-sockets-socket-close.texinfo not included]

     [file fun-sb-bsd-sockets-socket-make-stream.texinfo not included]

     [file fun-sb-bsd-sockets-socket-error.texinfo not included]

     [file fun-sb-bsd-sockets-non-blocking-mode.texinfo not included]

Socket Options
--------------

A subset of socket options are supported, using a fairly general framework which should make it simple to add more as required - see SYS:CONTRIB;SB-BSD-SOCKETS:SOCKOPT.LISP for details. The name mapping from C is fairly straightforward: SO_RCVLOWAT becomes sockopt-receive-low-water and (setf sockopt-receive-low-water).

     [file fun-sb-bsd-sockets-sockopt-reuse-address.texinfo not included]

     [file fun-sb-bsd-sockets-sockopt-keep-alive.texinfo not included]

     [file fun-sb-bsd-sockets-sockopt-oob-inline.texinfo not included]

     [file fun-sb-bsd-sockets-sockopt-bsd-compatible.texinfo not included]

     [file fun-sb-bsd-sockets-sockopt-pass-credentials.texinfo not included]

     [file fun-sb-bsd-sockets-sockopt-debug.texinfo not included]

     [file fun-sb-bsd-sockets-sockopt-dont-route.texinfo not included]

     [file fun-sb-bsd-sockets-sockopt-broadcast.texinfo not included]

     [file fun-sb-bsd-sockets-sockopt-tcp-nodelay.texinfo not included]

INET Domain Sockets
-------------------

The TCP and UDP sockets that you know and love. Some representation issues:

  * Internet addresses are represented by vectors of (unsigned-byte 8) - viz. #(127 0 0 1). Ports are just integers: 6010. No conversion between network- and host-order data is needed from the user of this package.

  * Socket addresses are represented by the two values for address and port, so for example, (socket-connect s #(192 168 1 1) 80).

     [file class-sb-bsd-sockets-inet-socket.texinfo not included]

     [file fun-sb-bsd-sockets-make-inet-address.texinfo not included]

     [file fun-sb-bsd-sockets-get-protocol-by-name.texinfo not included]

Local (Unix) Domain Sockets
---------------------------

Local domain (AF_LOCAL) sockets are also known as Unix-domain sockets, but were renamed by POSIX presumably on the basis that they may be available on other systems too.

A local socket address is a string, which is used to create a node in the local filesystem. This means of course that they cannot be used across a network.

     [file class-sb-bsd-sockets-local-socket.texinfo not included]

Name Service
------------

Presently name service is implemented by calling whatever gethostbyname(2) uses. This may be any or all of /etc/hosts, NIS, DNS, or something completely different. Typically it's controlled by /etc/nsswitch.conf.

Direct links to the asynchronous resolver(3) routines would be nice to have eventually, so that we can do DNS lookups in parallel with other things

     [file class-sb-bsd-sockets-host-ent.texinfo not included]

     [file fun-sb-bsd-sockets-get-host-by-name.texinfo not included]

     [file fun-sb-bsd-sockets-get-host-by-address.texinfo not included]

     [file fun-sb-bsd-sockets-host-ent-address.texinfo not included]

     [file fun-sb-bsd-sockets-name-service-error.texinfo not included]