contrib/sb-bsd-sockets/defpackage.lisp

   1 #+(and sbcl win32)
   2 (defpackage "SB-WIN32-SOCKETS-INTERNAL"
   3   (:nicknames "WIN32SOCKINT")
   4   (:shadow close listen)
   5   (:use "COMMON-LISP" "SB-ALIEN" "SB-EXT" "SB-C-CALL"))
   6
   7 (defpackage "SB-BSD-SOCKETS-INTERNAL"
   8   (:nicknames "SOCKINT")
   9   (:shadow close listen)
  10   #+cmu (:shadowing-import-from "CL" with-array-data)
  11   #+sbcl (:shadowing-import-from "SB-KERNEL" with-array-data)
  12   #+cmu (:use "COMMON-LISP" "ALIEN" "SYSTEM" "EXT" "C-CALL")
  13   #+sbcl (:use "COMMON-LISP" "SB-ALIEN" #+nil "SB-SYSTEM" "SB-EXT" "SB-C-CALL"))
  14
  15 ;;; SBCL changes a lot of package prefixes.  To avoid littering the
  16 ;;; code with conditionals, we use the SBCL package prefixes
  17 ;;; throughout.  This means that we need to create said packages
  18 ;;; first, if we're using CMUCL
  19
  20 ;;; One thing that this exercise really has made clear is just how much
  21 ;;; of the alien stuff is scattered around the cmucl package space
  22 ;;; seemingly at random.  Hmm.
  23
  24 #+cmu
  25 (eval-when (:compile-toplevel :load-toplevel)
  26   (defun add-package-nickname (name nickname)
  27     (let ((p (find-package name)))
  28       (rename-package p (package-name p)
  29                       (cons nickname (package-nicknames name)))))
  30   (add-package-nickname "EXT" "SB-EXT")
  31   (add-package-nickname "ALIEN" "SB-ALIEN")
  32   (add-package-nickname "UNIX" "SB-UNIX")
  33   (add-package-nickname "C-CALL" "SB-C-CALL")
  34   (add-package-nickname "KERNEL" "SB-KERNEL")
  35   (add-package-nickname "SYSTEM" "SB-SYS"))
  36
  37 (defpackage "SB-BSD-SOCKETS"
  38   (:export socket local-socket inet-socket
  39            make-local-socket make-inet-socket
  40            socket-bind socket-accept socket-connect
  41            socket-send socket-receive socket-recv
  42            socket-name socket-peername socket-listen
  43            socket-close socket-file-descriptor
  44            socket-family socket-protocol socket-open-p
  45            socket-type socket-make-stream get-protocol-by-name
  46
  47            get-host-by-name get-host-by-address
  48            host-ent
  49            host-ent-addresses host-ent-address
  50            host-ent-aliases host-ent-name
  51            name-service-error
  52            ;; not sure if these are really good names or not
  53            netdb-internal-error
  54            netdb-success-error
  55            host-not-found-error
  56            try-again-error
  57            no-recovery-error
  58
  59            unknown-protocol
  60
  61            ;; all socket options are also exported, by code in
  62            ;; sockopt.lisp
  63
  64            socket-error
  65
  66            ;; other errno-based socket errors are exported by code in
  67            ;; sockets.lisp
  68
  69            make-inet-address
  70
  71            non-blocking-mode
  72            )
  73   (:use "COMMON-LISP" "SB-BSD-SOCKETS-INTERNAL")
  74   (:import-from "SB-INT" "UNSUPPORTED-OPERATOR" "FEATUREP")
  75   (:documentation
  76    "
  77
  78 A thinly-disguised BSD socket API for SBCL.  Ideas stolen from the BSD
  79 socket API for C and Graham Barr's IO::Socket classes for Perl.
  80
  81 We represent sockets as CLOS objects, and rename a lot of methods and
  82 arguments to fit Lisp style more closely.
  83
  84 "
  85    ))
  86
  87 #||
  88
  89 <h2>Contents</h2>
  90
  91 <ol>
  92 <li> General concepts
  93 <li> Methods applicable to all <a href="#socket">sockets</a>
  94 <li> <a href="#sockopt">Socket Options</a>
  95 <li> Methods applicable to a particular subclass
  96 <ol>
  97 <li> <a href="#internet">INET-SOCKET</a> - Internet Protocol (TCP, UDP, raw) sockets
  98 <li> Methods on <a href="#LOCAL-SOCKET">LOCAL-SOCKET</a> - Local-domain sockets
  99 </ol>
 100 <li> <a href="#name-service">Name resolution</a> (DNS, /etc/hosts, &amp;c)
 101 </ol>
 102
 103 <h2>General concepts</h2>
 104
 105 <p>Most of the functions are modelled on the BSD socket API.  BSD sockets
 106 are widely supported, portably <i>("portable" by Unix standards, at least)</i>
 107 available on a variety of systems, and documented.  There are some
 108 differences in approach where we have taken advantage of some of the more useful features of Common Lisp - briefly
 109
 110 <ul>
 111 <li> Where the C API would typically return -1 and set errno, we
 112 signal an error.  All the errors are subclasses of SOCKET-CONDITION
 113 and generally correspond one for one with possible <tt>errno</tt> values
 114
 115 <li> We use multiple return values in many places where the C API would use
 116 pass-by-reference values
 117
 118 <li> We can often avoid supplying an explicit <i>length</i> argument to
 119 functions because we already know how long the argument is.
 120
 121 <li> IP addresses and ports are represented in slightly friendlier fashion
 122 than "network-endian integers".  See the section on <a href="#internet"
 123 >Internet domain</a> sockets for details.
 124 </ul>
 125
 126
 127 |#
 128
 129 (in-package :sb-bsd-sockets)
 130
 131 (defmethod asdf:hyperdocumentation
 132     ((package (eql #.*package*)) symbol kind)
 133   (declare (ignore kind))
 134   (format nil "file://~A#~A"
 135           #.(namestring
 136              (merge-pathnames "index.html"
 137                               (or *load-pathname* *compile-file-pathname*)))
 138           symbol))