contrib/sb-bsd-sockets/sb-bsd-sockets.texinfo

   1 @node Networking
   2 @comment  node-name,  next,  previous,  up
   3 @chapter Networking
   4 @cindex Sockets, Networking
   5
   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.
   9
  10 Sockets are represented as CLOS objects, and the API naming
  11 conventions attempt to balance between the BSD names and good lisp style.
  12
  13 @menu
  14 * Sockets Overview::
  15 * General Sockets::      Methods applicable to all sockets
  16 * Socket Options::
  17 * INET Domain Sockets::
  18 * Local (Unix) Domain Sockets::
  19 * Name Service::
  20 @end menu
  21
  22 @node Sockets Overview
  23 @section Sockets Overview
  24
  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:
  30
  31 @itemize
  32
  33 @item
  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.
  38
  39 @item
  40 We use multiple return values in many places where the C API would use
  41 pass-by-reference values.
  42
  43 @item
  44 We can often avoid supplying an explicit @emph{length} argument to
  45 functions because we already know how long the argument is.
  46
  47 @item
  48 IP addresses and ports are represented in slightly friendlier fashion
  49 than "network-endian integers".
  50
  51 @end itemize
  52
  53 @node General Sockets
  54 @section General Sockets
  55
  56 @include class-sb-bsd-sockets-socket.texinfo
  57
  58 @include fun-sb-bsd-sockets-socket-bind.texinfo
  59
  60 @include fun-sb-bsd-sockets-socket-accept.texinfo
  61
  62 @include fun-sb-bsd-sockets-socket-connect.texinfo
  63
  64 @include fun-sb-bsd-sockets-socket-peername.texinfo
  65
  66 @include fun-sb-bsd-sockets-socket-name.texinfo
  67
  68 @include fun-sb-bsd-sockets-socket-receive.texinfo
  69
  70 @include fun-sb-bsd-sockets-socket-listen.texinfo
  71
  72 @include fun-sb-bsd-sockets-socket-close.texinfo
  73
  74 @include fun-sb-bsd-sockets-socket-make-stream.texinfo
  75
  76 @include fun-sb-bsd-sockets-socket-error.texinfo
  77
  78 @include fun-sb-bsd-sockets-non-blocking-mode.texinfo
  79
  80 @node Socket Options
  81 @section Socket Options
  82
  83 A subset of socket options are supported, using a fairly general
  84 framework which should make it simple to add more as required - see
  85 @file{SYS:CONTRIB;SB-BSD-SOCKETS:SOCKOPT.LISP} for details. The name
  86 mapping from C is fairly straightforward: @code{SO_RCVLOWAT} becomes
  87 @code{sockopt-receive-low-water} and @code{(setf
  88 sockopt-receive-low-water)}.
  89
  90 @include fun-sb-bsd-sockets-sockopt-reuse-address.texinfo
  91
  92 @include fun-sb-bsd-sockets-sockopt-keep-alive.texinfo
  93
  94 @include fun-sb-bsd-sockets-sockopt-oob-inline.texinfo
  95
  96 @include fun-sb-bsd-sockets-sockopt-bsd-compatible.texinfo
  97
  98 @include fun-sb-bsd-sockets-sockopt-pass-credentials.texinfo
  99
 100 @include fun-sb-bsd-sockets-sockopt-debug.texinfo
 101
 102 @include fun-sb-bsd-sockets-sockopt-dont-route.texinfo
 103
 104 @include fun-sb-bsd-sockets-sockopt-broadcast.texinfo
 105
 106 @include fun-sb-bsd-sockets-sockopt-tcp-nodelay.texinfo
 107
 108 @node INET Domain Sockets
 109 @section INET Domain Sockets
 110
 111 The TCP and UDP sockets that you know and love. Some representation
 112 issues:
 113
 114 @itemize
 115
 116 @item
 117 Internet addresses are represented by vectors of (unsigned-byte 8) -
 118 viz. #(127 0 0 1). Ports are just integers: 6010. No conversion
 119 between network- and host-order data is needed from the user of this
 120 package.
 121
 122 @item
 123 Socket addresses are represented by the two values for address and
 124 port, so for example, (socket-connect s #(192 168 1 1) 80).
 125
 126 @end itemize
 127
 128 @include class-sb-bsd-sockets-inet-socket.texinfo
 129
 130 @include fun-sb-bsd-sockets-make-inet-address.texinfo
 131
 132 @include fun-sb-bsd-sockets-get-protocol-by-name.texinfo
 133
 134 @node Local (Unix) Domain Sockets
 135 @section Local (Unix) Domain Sockets
 136
 137 Local domain (@code{AF_LOCAL}) sockets are also known as Unix-domain
 138 sockets, but were renamed by POSIX presumably on the basis that they
 139 may be available on other systems too.
 140
 141 A local socket address is a string, which is used to create a node in
 142 the local filesystem. This means of course that they cannot be used
 143 across a network.
 144
 145 @include class-sb-bsd-sockets-local-socket.texinfo
 146
 147 @node Name Service
 148 @section Name Service
 149
 150 Presently name service is implemented by calling whatever
 151 @code{gethostbyname(2)} uses. This may be any or all of
 152 @file{/etc/hosts}, NIS, DNS, or something completely different.
 153 Typically it's controlled by @file{/etc/nsswitch.conf}.
 154
 155 Direct links to the asynchronous @code{resolver(3)} routines would be
 156 nice to have eventually, so that we can do DNS lookups in parallel
 157 with other things
 158
 159 @include class-sb-bsd-sockets-host-ent.texinfo
 160
 161 @include fun-sb-bsd-sockets-get-host-by-name.texinfo
 162
 163 @include fun-sb-bsd-sockets-get-host-by-address.texinfo
 164
 165 @include fun-sb-bsd-sockets-host-ent-address.texinfo
 166
 167 @include fun-sb-bsd-sockets-name-service-error.texinfo