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