Networking
**********

The sb-bsd-sockets module provides a thinly disguised BSD socket API for SBCL. Ideas have been 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-send.texinfo not included]

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

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

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

     [file fun-sb-bsd-sockets-socket-shutdown.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 out to the getaddrinfo(3) and gethostinfo(3), or to gethostbyname(3) gethostbyaddr(3) on platforms where the preferred functions are not available. The exact details of the name resolving process (for example the choice of whether DNS or a hosts file is used for lookup) are platform dependent.

     [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]