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-send.texinfo
  71
  72 @include fun-sb-bsd-sockets-socket-listen.texinfo
  73
  74 @include fun-sb-bsd-sockets-socket-open-p.texinfo
  75
  76 @include fun-sb-bsd-sockets-socket-close.texinfo
  77
  78 @include fun-sb-bsd-sockets-socket-shutdown.texinfo
  79
  80 @include fun-sb-bsd-sockets-socket-make-stream.texinfo
  81
  82 @include fun-sb-bsd-sockets-socket-error.texinfo
  83
  84 @include fun-sb-bsd-sockets-non-blocking-mode.texinfo
  85
  86 @node Socket Options
  87 @section Socket Options
  88
  89 A subset of socket options are supported, using a fairly general
  90 framework which should make it simple to add more as required - see
  91 @file{SYS:CONTRIB;SB-BSD-SOCKETS:SOCKOPT.LISP} for details. The name
  92 mapping from C is fairly straightforward: @code{SO_RCVLOWAT} becomes
  93 @code{sockopt-receive-low-water} and @code{(setf
  94 sockopt-receive-low-water)}.
  95
  96 @include fun-sb-bsd-sockets-sockopt-reuse-address.texinfo
  97
  98 @include fun-sb-bsd-sockets-sockopt-keep-alive.texinfo
  99
 100 @include fun-sb-bsd-sockets-sockopt-oob-inline.texinfo
 101
 102 @include fun-sb-bsd-sockets-sockopt-bsd-compatible.texinfo
 103
 104 @include fun-sb-bsd-sockets-sockopt-pass-credentials.texinfo
 105
 106 @include fun-sb-bsd-sockets-sockopt-debug.texinfo
 107
 108 @include fun-sb-bsd-sockets-sockopt-dont-route.texinfo
 109
 110 @include fun-sb-bsd-sockets-sockopt-broadcast.texinfo
 111
 112 @include fun-sb-bsd-sockets-sockopt-tcp-nodelay.texinfo
 113
 114 @node INET Domain Sockets
 115 @section INET Domain Sockets
 116
 117 The TCP and UDP sockets that you know and love. Some representation
 118 issues:
 119
 120 @itemize
 121
 122 @item
 123 IPv4 Internet addresses are represented by vectors of
 124 @code{(unsigned-byte 8)} - viz. @code{#(127 0 0 1)}. Ports are just
 125 integers: 6010. No conversion between network- and host-order data is
 126 needed from the user of this package.
 127
 128 @item
 129 IPv6 Internet addresses are represented by vectors of 16
 130 @code{(unsigned-byte 8)} - viz. @code{#(0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
 131 1)}. Ports are just integers. As for IPv4 addresses, no conversion
 132 between network- and host-order data is needed from the user of this
 133 package.
 134
 135 @item
 136 Socket addresses are represented by the two values for address and port,
 137 so for example, @code{(socket-connect socket #(192 168 1 1) 80)} for
 138 IPv4 and @code{(socket-connect socket #(0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1)
 139 80)} for IPv6.
 140
 141 @end itemize
 142
 143 @include class-sb-bsd-sockets-inet-socket.texinfo
 144
 145 @include class-sb-bsd-sockets-inet6-socket.texinfo
 146
 147 @include fun-sb-bsd-sockets-make-inet-address.texinfo
 148
 149 @include fun-sb-bsd-sockets-make-inet6-address.texinfo
 150
 151 @include fun-sb-bsd-sockets-get-protocol-by-name.texinfo
 152
 153 @node Local (Unix) Domain Sockets
 154 @section Local (Unix) Domain Sockets
 155
 156 Local domain (@code{AF_LOCAL}) sockets are also known as Unix-domain
 157 sockets, but were renamed by POSIX presumably on the basis that they
 158 may be available on other systems too.
 159
 160 A local socket address is a string, which is used to create a node in
 161 the local filesystem. This means of course that they cannot be used
 162 across a network.
 163
 164 @include class-sb-bsd-sockets-local-socket.texinfo
 165
 166 @node Name Service
 167 @section Name Service
 168
 169 Presently name service is implemented by calling out to the
 170 @code{getaddrinfo(3)} and @code{gethostinfo(3)}, or to
 171 @code{gethostbyname(3)} @code{gethostbyaddr(3)} on platforms where
 172 the preferred functions are not available. The exact details of
 173 the name resolving process (for example the choice of whether
 174 DNS or a hosts file is used for lookup) are platform dependent.
 175
 176 @c Direct links to the asynchronous @code{resolver(3)} routines would be
 177 @c nice to have eventually, so that we can do DNS lookups in parallel
 178 @c with other things.
 179
 180 @include class-sb-bsd-sockets-host-ent.texinfo
 181
 182 @include fun-sb-bsd-sockets-get-host-by-name.texinfo
 183
 184 @include fun-sb-bsd-sockets-get-host-by-address.texinfo
 185
 186 @include fun-sb-bsd-sockets-host-ent-address.texinfo