contrib/sb-bsd-sockets/api-reference.html

   1 <html><head><title>db-sockets API Reference</title></head><body>
   2
   3 <!--
   4  This is intended to be[**] a machine-generated file (from SB-BSD-SOCKETS
   5  source code, massaged by doc.lisp), so do not edit it directly.
   6
   7  [**] As of sbcl-0.8.0.12, there's clearly been some divergence between
   8  the text here and the original doc.lisp output, e.g. the way doc.lisp
   9  says "<title>SBCL BSD-Sockets API Reference</title>" where this file
  10  says "<title>db-sockets API Reference</title>". FIXME?
  11  -->
  12
  13 <h1>Package SOCKETS</h1>
  14
  15 <P>
  16 A thinly-disguised BSD socket API for SBCL.  Ideas stolen from the BSD
  17 socket API for C and Graham Barr's IO::Socket classes for Perl.
  18 <P>
  19 We represent sockets as CLOS objects, and rename a lot of methods and
  20 arguments to fit Lisp style more closely.
  21 <P>
  22
  23 <P>
  24 <h2>Contents</h2>
  25 <P>
  26 <ol>
  27 <li> General concepts
  28 <li> Methods applicable to all <a href="#socket">sockets</a>
  29 <li> <a href="#sockopt">Socket Options</a>
  30 <li> Methods applicable to a particular subclass
  31 <ol>
  32 <li> <a href="#internet">INET-SOCKET</a> - Internet Protocol (TCP, UDP, raw) sockets
  33 <li> Methods on <a href="#UNIX-SOCKET">UNIX-SOCKET</a> - Unix-domain sockets
  34 </ol>
  35 <li> <a href="#name-service">Name resolution</a> (DNS, /etc/hosts, &amp;c)
  36 </ol>
  37 <P>
  38 <h2>General concepts</h2>
  39 <P>
  40 <p>Most of the functions are modelled on the BSD socket API.  BSD sockets
  41 are widely supported, portably <i>(well, fairly portably)</i>
  42 available on a variety of systems, and documented.  There are some
  43 differences in approach where we have taken advantage of some of the more useful features of Common Lisp - briefly
  44 <P>
  45 <ul>
  46 <li> Where the C API would typically return -1 and set errno, db-sockets
  47 signals an error.  All the errors are subclasses of SOCKET-CONDITION
  48 and generally correspond one for one with possible <tt>errno</tt> values
  49 <P>
  50 <li> We use multiple return values in many places where the C API would use p[ass-by-reference values
  51 <P>
  52 <li> We can often avoid supplying an explicit <i>length</i> argument to
  53 functions because we already know how long the argument is.
  54 <P>
  55 <li> IP addresses and ports are represented in slightly friendlier fashion
  56 than "network-endian integers".  See the section on <a href="#internet"
  57 >Internet domain</a> sockets for details.
  58 </ul>
  59 <P>
  60 <P>
  61 <hr> <h2>SOCKETs</h2>
  62 <P>
  63 <p><a name="SOCKET"><i>Class: </i><b>SOCKET</b></a>
  64 <p><b>Slots:</b><ul><li>FILE-DESCRIPTOR : </li>
  65 <li>FAMILY : </li>
  66 <li>PROTOCOL : </li>
  67 <li>TYPE : </li>
  68 <li>STREAM : </li>
  69 </ul><p><a name="SOCKET-BIND"><table width="100%"><tr><td width="80%">(socket-bind <i> (s <a href="#socket">socket</a>) &rest address</i>)</td><td align=right>Generic Function</td></tr></table>
  70 <p><a name="SOCKET-ACCEPT"><table width="100%"><tr><td width="80%">(socket-accept <i> (socket <a href="#socket">socket</a>)</i>)</td><td align=right>Method</td></tr></table>
  71 <blockquote>Perform the accept(2) call, returning a newly-created connected socket
  72 and the peer address as multiple values</blockquote>
  73 <p><a name="SOCKET-CONNECT"><table width="100%"><tr><td width="80%">(socket-connect <i> (s <a href="#socket">socket</a>) &rest address</i>)</td><td align=right>Generic Function</td></tr></table>
  74 <p><a name="SOCKET-PEERNAME"><table width="100%"><tr><td width="80%">(socket-peername <i> (socket <a href="#socket">socket</a>)</i>)</td><td align=right>Method</td></tr></table>
  75 <blockquote>Return the socket's peer; depending on the address family this may return multiple values</blockquote>
  76 <p><a name="SOCKET-NAME"><table width="100%"><tr><td width="80%">(socket-name <i> (socket <a href="#socket">socket</a>)</i>)</td><td align=right>Method</td></tr></table>
  77 <blockquote>Return the address (as vector of bytes) and port that the socket is bound to, as multiple values</blockquote>
  78 <p><a name="SOCKET-RECEIVE"><table width="100%"><tr><td width="80%">(socket-receive <i> (socket <a href="#socket">socket</a>) buffer length &key oob peek waitall (element-type
  79                                                                             'character)</i>)</td><td align=right>Method</td></tr></table>
  80 <blockquote>Read LENGTH octets from <a href="#SOCKET">SOCKET</a> into BUFFER (or a freshly-consed buffer if
  81 NIL), using recvfrom(2).  If LENGTH is NIL, the length of BUFFER is
  82 used, so at least one of these two arguments must be non-NIL.  If
  83 BUFFER is supplied, it had better be of an element type one octet wide.
  84 Returns the buffer, its length, and the address of the peer
  85 that sent it, as multiple values.  On datagram sockets, sets MSG_TRUNC
  86 so that the actual packet length is returned even if the buffer was too
  87 small</blockquote>
  88 <p><a name="SOCKET-LISTEN"><table width="100%"><tr><td width="80%">(socket-listen <i> (socket <a href="#socket">socket</a>) backlog</i>)</td><td align=right>Method</td></tr></table>
  89 <blockquote>Mark <a href="#SOCKET">SOCKET</a> as willing to accept incoming connections.  BACKLOG
  90 defines the maximum length that the queue of pending connections may
  91 grow to before new connection attempts are refused.  See also listen(2)</blockquote>
  92 <p><a name="SOCKET-CLOSE"><table width="100%"><tr><td width="80%">(socket-close <i> (socket <a href="#socket">socket</a>)</i>)</td><td align=right>Method</td></tr></table>
  93 <blockquote>Close <a href="#SOCKET">SOCKET</a>.  May throw any kind of error that write(2) would have
  94 thrown.  If <a href="#SOCKET-MAKE-STREAM">SOCKET-MAKE-STREAM</a> has been called, calls CLOSE on that
  95 stream instead</blockquote>
  96 <p><a name="SOCKET-MAKE-STREAM"><table width="100%"><tr><td width="80%">(socket-make-stream <i> (socket <a href="#socket">socket</a>) &rest args</i>)</td><td align=right>Method</td></tr></table>
  97 <blockquote>Find or create a STREAM that can be used for IO on <a href="#SOCKET">SOCKET</a> (which
  98 must be connected).  ARGS are passed onto SB-SYS:MAKE-FD-STREAM.</blockquote>
  99 <hr>
 100 <H2> Socket Options </h2>
 101 <a name="sockopt"> </a>
 102 <p> A subset of socket options are supported, using a fairly
 103 general framework which should make it simple to add more as required
 104 - see sockopt.lisp for details.  The name mapping from C is fairly
 105 straightforward: <tt>SO_RCVLOWAT</tt> becomes
 106 <tt>sockopt-receive-low-water</tt> and <tt>(setf
 107 sockopt-receive-low-water)</tt>.
 108 |<p><a name="SOCKOPT-REUSE-ADDRESS"><table width="100%"><tr><td width="80%">(sockopt-reuse-address <i> (socket <a href="#socket">socket</a>) argument</i>)</td><td align=right>Accessor</td></tr></table>
 109 <blockquote>Return the value of the SO-REUSEADDR socket option for <a href="#SOCKET">SOCKET</a>.  This can also be updated with SETF.</blockquote>
 110 <p><a name="SOCKOPT-KEEP-ALIVE"><table width="100%"><tr><td width="80%">(sockopt-keep-alive <i> (socket <a href="#socket">socket</a>) argument</i>)</td><td align=right>Accessor</td></tr></table>
 111 <blockquote>Return the value of the SO-KEEPALIVE socket option for <a href="#SOCKET">SOCKET</a>.  This can also be updated with SETF.</blockquote>
 112 <p><a name="SOCKOPT-OOB-INLINE"><table width="100%"><tr><td width="80%">(sockopt-oob-inline <i> (socket <a href="#socket">socket</a>) argument</i>)</td><td align=right>Accessor</td></tr></table>
 113 <blockquote>Return the value of the SO-OOBINLINE socket option for <a href="#SOCKET">SOCKET</a>.  This can also be updated with SETF.</blockquote>
 114 <p><a name="SOCKOPT-BSD-COMPATIBLE"><table width="100%"><tr><td width="80%">(sockopt-bsd-compatible <i> (socket <a href="#socket">socket</a>) argument</i>)</td><td align=right>Accessor</td></tr></table>
 115 <blockquote>Return the value of the SO-BSDCOMPAT socket option for <a href="#SOCKET">SOCKET</a>.  This can also be updated with SETF.</blockquote>
 116 <p><a name="SOCKOPT-PASS-CREDENTIALS"><table width="100%"><tr><td width="80%">(sockopt-pass-credentials <i> (socket <a href="#socket">socket</a>) argument</i>)</td><td align=right>Accessor</td></tr></table>
 117 <blockquote>Return the value of the SO-PASSCRED socket option for <a href="#SOCKET">SOCKET</a>.  This can also be updated with SETF.</blockquote>
 118 <p><a name="SOCKOPT-DEBUG"><table width="100%"><tr><td width="80%">(sockopt-debug <i> (socket <a href="#socket">socket</a>) argument</i>)</td><td align=right>Accessor</td></tr></table>
 119 <blockquote>Return the value of the SO-DEBUG socket option for <a href="#SOCKET">SOCKET</a>.  This can also be updated with SETF.</blockquote>
 120 <p><a name="SOCKOPT-DONT-ROUTE"><table width="100%"><tr><td width="80%">(sockopt-dont-route <i> (socket <a href="#socket">socket</a>) argument</i>)</td><td align=right>Accessor</td></tr></table>
 121 <blockquote>Return the value of the SO-DONTROUTE socket option for <a href="#SOCKET">SOCKET</a>.  This can also be updated with SETF.</blockquote>
 122 <p><a name="SOCKOPT-BROADCAST"><table width="100%"><tr><td width="80%">(sockopt-broadcast <i> (socket <a href="#socket">socket</a>) argument</i>)</td><td align=right>Accessor</td></tr></table>
 123 <blockquote>Return the value of the SO-BROADCAST socket option for <a href="#SOCKET">SOCKET</a>.  This can also be updated with SETF.</blockquote>
 124 <p><a name="SOCKOPT-TCP-NODELAY"><table width="100%"><tr><td width="80%">(sockopt-tcp-nodelay <i> (socket <a href="#socket">socket</a>) argument</i>)</td><td align=right>Accessor</td></tr></table>
 125 <blockquote>Return the value of the TCP-NODELAY socket option for <a href="#SOCKET">SOCKET</a>.  This can also be updated with SETF.</blockquote>
 126 <hr> <h2>INET-domain sockets</h2>
 127 <P>
 128 <p>The TCP and UDP sockets that you know and love.  Some representation issues:
 129 <ul>
 130 <li>These functions do not accept hostnames directly: see <a href="#name-service">name resolution</a>
 131 <li>Internet <b>addresses</b> are represented by vectors of <tt>(unsigned-byte 8)</tt> - viz. <tt>#(127 0 0 1)</tt>.  <b>Ports</b> are just integers: <tt>6010</tt>.  No conversion between network- and host-order data is needed from the user of this package.
 132 <li><b><i>socket addresses</i></b> are represented by the two values for <b>address</b> and <b>port</b>, so for example, <tt>(<a href="#SOCKET-CONNECT">socket-connect</a> s #(192 168 1 1) 80)</tt>
 133 </ul>
 134 <P>
 135 <p><a name="INET-SOCKET"><i>Class: </i><b>INET-SOCKET</b></a>
 136 <p><b>Slots:</b><ul><li>FAMILY : </li>
 137 </ul><p><a name="MAKE-INET-ADDRESS"><table width="100%"><tr><td width="80%">(make-inet-address <i> dotted-quads</i>)</td><td align=right>Function</td></tr></table>
 138 <blockquote>Return a vector of octets given a string DOTTED-QUADS in the format
 139 "127.0.0.1"</blockquote>
 140 <p><a name="GET-PROTOCOL-BY-NAME"><table width="100%"><tr><td width="80%">(get-protocol-by-name <i> name</i>)</td><td align=right>Function</td></tr></table>
 141 <blockquote>Returns the network protocol number associated with the string NAME,
 142 using getprotobyname(2) which typically looks in NIS or /etc/protocols</blockquote>
 143 <p><a name="MAKE-INET-SOCKET"><table width="100%"><tr><td width="80%">(make-inet-socket <i> type protocol</i>)</td><td align=right>Function</td></tr></table>
 144 <blockquote>Make an INET socket.  Deprecated in favour of make-instance</blockquote>
 145 <hr> <h2>File-domain sockets</h2>
 146 <P>
 147 File-domain (AF_FILE) sockets are also known as Unix-domain sockets, but were
 148 renamed by POSIX presumably on the basis that they may be
 149 available on other systems too.
 150 <P>
 151 A file-domain socket address is a string, which is used to create a node
 152 in the local filesystem.  This means of course that they cannot be used across
 153 a network.
 154 <P>
 155 |<p><a name="UNIX-SOCKET"><i>Class: </i><b>UNIX-SOCKET</b></a>
 156 <p><b>Slots:</b><ul><li>FAMILY : </li>
 157 </ul><hr> <a name="name-service"><h2>Name Service</h2></a>
 158 <P>
 159 <p>Presently name service is implemented by calling whatever
 160 gethostbyname(2) uses.  This may be any or all of /etc/hosts, NIS, DNS,
 161 or something completely different.  Typically it's controlled by
 162 /etc/nsswitch.conf
 163 <P>
 164 <p> Direct links to the asynchronous resolver(3) routines would be nice to have
 165 eventually, so that we can do DNS lookups in parallel with other things
 166 <p><a name="HOST-ENT"><i>Class: </i><b>HOST-ENT</b></a>
 167 <p><b>Slots:</b><ul><li>NAME : </li>
 168 <li>ALIASES : </li>
 169 <li>ADDRESS-TYPE : </li>
 170 <li>ADDRESSES : </li>
 171 </ul><p><a name="HOST-ENT-ADDRESS"><table width="100%"><tr><td width="80%">(host-ent-address <i> (host-ent <a href="#host-ent">host-ent</a>)</i>)</td><td align=right>Method</td></tr></table>
 172 <p><a name="GET-HOST-BY-NAME"><table width="100%"><tr><td width="80%">(get-host-by-name <i> host-name</i>)</td><td align=right>Function</td></tr></table>
 173 <blockquote>Returns a <a href="#HOST-ENT">HOST-ENT</a> instance for HOST-NAME or throws some kind of condition.
 174 HOST-NAME may also be an IP address in dotted quad notation or some other
 175 weird stuff - see gethostbyname(3) for grisly details.</blockquote>
 176 <p><a name="GET-HOST-BY-ADDRESS"><table width="100%"><tr><td width="80%">(get-host-by-address <i> address</i>)</td><td align=right>Function</td></tr></table>
 177 <blockquote>Returns a <a href="#HOST-ENT">HOST-ENT</a> instance for ADDRESS, which should be a vector of
 178 (integer 0 255), or throws some kind of error.  See gethostbyaddr(3) for
 179 grisly details.</blockquote>
 180 <p><a name="NAME-SERVICE-ERROR"><table width="100%"><tr><td width="80%">(name-service-error <i> where</i>)</td><td align=right>Function</td></tr></table>
 181 <hr><p><a name="NON-BLOCKING-MODE"><table width="100%"><tr><td width="80%">(non-blocking-mode <i> (socket <a href="#socket">socket</a>)</i>)</td><td align=right>Method</td></tr></table>
 182 <blockquote>Is <a href="#SOCKET">SOCKET</a> in non-blocking mode?</blockquote>
 183 <hr>
 184 <P>
 185 <H1>Tests</h1>
 186 <P>
 187 There should be at least one test for pretty much everything you can do
 188 with the package.  In some places I've been more diligent than others; more
 189 tests gratefully accepted.
 190 <P>
 191 Tests are in the file <tt>tests.lisp</tt> and also make good examples.
 192 <P>
 193 |
 194 <h2>Unix-domain sockets</h2>
 195 <P>
 196 A fairly rudimentary test that connects to the syslog socket and sends a
 197 message.  Priority 7 is kern.debug; you'll probably want to look at
 198 /etc/syslog.conf or local equivalent to find out where the message ended up
 199 |