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

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