From 8a3c76ab9725a199aa06a0abc018e096271a0f75 Mon Sep 17 00:00:00 2001 From: Nikodemus Siivola Date: Sun, 1 Aug 2004 23:33:05 +0000 Subject: [PATCH] 0.8.13.14: Texinfoization continues * Move documentation for SB-BSD-SOCKETS into user manual, deleting docs (FAQ, TODO, NEWS, and doc.lisp remain yet). * Automatically generate class-precedence-list information for classes and conditions in the manual, ditto for documented slots. * Start documentation for each contrib on a new page for clarity. (twiddle, twiddle) --- NEWS | 2 + contrib/sb-bsd-sockets/README | 30 ----- contrib/sb-bsd-sockets/TODO | 1 - contrib/sb-bsd-sockets/api-reference.html | 199 ----------------------------- contrib/sb-bsd-sockets/doc.lisp | 5 + contrib/sb-bsd-sockets/index.html | 188 --------------------------- contrib/sb-bsd-sockets/inet.lisp | 21 ++- contrib/sb-bsd-sockets/local.lisp | 19 +-- contrib/sb-bsd-sockets/name-service.lisp | 25 ++-- contrib/sb-bsd-sockets/sockets.lisp | 32 +++-- contrib/sb-bsd-sockets/sockopt.lisp | 31 ++--- contrib/sb-bsd-sockets/tests.lisp | 12 -- doc/manual/Makefile | 5 +- doc/manual/create-contrib-doc-list.lisp | 4 +- doc/manual/docstrings.lisp | 90 +++++++++---- version.lisp-expr | 2 +- 16 files changed, 136 insertions(+), 530 deletions(-) delete mode 100644 contrib/sb-bsd-sockets/README delete mode 100644 contrib/sb-bsd-sockets/api-reference.html delete mode 100644 contrib/sb-bsd-sockets/index.html diff --git a/NEWS b/NEWS index 0e37ace..6b7811e 100644 --- a/NEWS +++ b/NEWS @@ -2,6 +2,8 @@ changes in sbcl-0.8.14 relative to sbcl-0.8.13: * new feature: on platforms where "dladdr" is available foreign function names now appear in backtraces. (based on Helmut Eller's work for CMUCL) + * documentation: networking interface SB-BSD-SOCKETS' documentation + has been integrated into the user manual. * bug fix: backtraces involving undefined functions or assembly routines are more informative. (thanks to Brian Downing) * bug fix: mutually referent alien structures now work correctly. diff --git a/contrib/sb-bsd-sockets/README b/contrib/sb-bsd-sockets/README deleted file mode 100644 index 311b06a..0000000 --- a/contrib/sb-bsd-sockets/README +++ /dev/null @@ -1,30 +0,0 @@ -o/~ Hey Mr Tambourine Man, play some -*- Text -*- for me o/~ - -A semi-sane sockets interface for SBCL. Usually also works in CMUCL, -but is rarely actually tested there so may require some massaging. - -It is invoked through the SBCL contrib/ modules system: - (require :asdf) - (require :sb-bsd-sockets) - -It uses the regression tester from the CMU AI repository, in its -incarnation as the SBCL contrib SB-RT. The tests themselves are in -tests.lisp, and can be run using the Makefile target intended for the -purpose, or by evaluating (sb-rt:do-tests). Note that one of the tests -is an HTTP client that connects back to ww.telent.net; if this bothers -your expectations of privacy, don't run it. - -There is an automatically generated API reference in -api-reference.html which you can regenerate if you can figure out how -doc.lisp works. You might find the examples in tests.lisp useful, -too. - -Feedback, patches, development versions - -Instructions on how to access the CVS repository for db-sockets are -at http://cvs.telent.net/ - -If you find bugs or want to send patches for enhancements, by email to -Daniel Barlow , but please check the CVS version first. - -$Id$ diff --git a/contrib/sb-bsd-sockets/TODO b/contrib/sb-bsd-sockets/TODO index 90c82a3..7d9bb5d 100644 --- a/contrib/sb-bsd-sockets/TODO +++ b/contrib/sb-bsd-sockets/TODO @@ -17,4 +17,3 @@ options are in but need odd ones, plus tcp, udp, ip - write tests for socket-name and socket-peername -- documentation: see doc.lisp, but beware: it's grotty. diff --git a/contrib/sb-bsd-sockets/api-reference.html b/contrib/sb-bsd-sockets/api-reference.html deleted file mode 100644 index 94bb89d..0000000 --- a/contrib/sb-bsd-sockets/api-reference.html +++ /dev/null @@ -1,199 +0,0 @@ -db-sockets API Reference - - - -

Package SOCKETS

- -

-A thinly-disguised BSD socket API for SBCL. Ideas stolen from the BSD -socket API for C and Graham Barr's IO::Socket classes for Perl. -

-We represent sockets as CLOS objects, and rename a lot of methods and -arguments to fit Lisp style more closely. -

- -

-

Contents

-

-

    -
  1. General concepts -
  2. Methods applicable to all sockets -
  3. Socket Options -
  4. Methods applicable to a particular subclass -
      -
    1. INET-SOCKET - Internet Protocol (TCP, UDP, raw) sockets -
    2. Methods on UNIX-SOCKET - Unix-domain sockets -
    -
  5. Name resolution (DNS, /etc/hosts, &c) -
-

-

General concepts

-

-

Most of the functions are modelled on the BSD socket API. BSD sockets -are widely supported, portably (well, fairly portably) -available on a variety of systems, and documented. There are some -differences in approach where we have taken advantage of some of the more useful features of Common Lisp - briefly -

-

-

-

-

SOCKETs

-

-

Class: SOCKET -

Slots:

(socket-bind (s socket) &rest address)Generic Function
-

(socket-accept (socket socket))Method
-

Perform the accept(2) call, returning a newly-created connected socket -and the peer address as multiple values
-

(socket-connect (s socket) &rest address)Generic Function
-

(socket-peername (socket socket))Method
-

Return the socket's peer; depending on the address family this may return multiple values
-

(socket-name (socket socket))Method
-

Return the address (as vector of bytes) and port that the socket is bound to, as multiple values
-

(socket-receive (socket socket) buffer length &key oob peek waitall (element-type - 'character))Method
-

Read LENGTH octets from SOCKET into BUFFER (or a freshly-consed buffer if -NIL), using recvfrom(2). If LENGTH is NIL, the length of BUFFER is -used, so at least one of these two arguments must be non-NIL. If -BUFFER is supplied, it had better be of an element type one octet wide. -Returns the buffer, its length, and the address of the peer -that sent it, as multiple values. On datagram sockets, sets MSG_TRUNC -so that the actual packet length is returned even if the buffer was too -small
-

(socket-listen (socket socket) backlog)Method
-

Mark SOCKET as willing to accept incoming connections. BACKLOG -defines the maximum length that the queue of pending connections may -grow to before new connection attempts are refused. See also listen(2)
-

(socket-close (socket socket))Method
-

Close SOCKET. May throw any kind of error that write(2) would have -thrown. If SOCKET-MAKE-STREAM has been called, calls CLOSE on that -stream instead
-

(socket-make-stream (socket socket) &rest args)Method
-

Find or create a STREAM that can be used for IO on SOCKET (which -must be connected). ARGS are passed onto SB-SYS:MAKE-FD-STREAM.
-
-

Socket Options

- -

A subset of socket options are supported, using a fairly -general framework which should make it simple to add more as required -- see sockopt.lisp for details. The name mapping from C is fairly -straightforward: SO_RCVLOWAT becomes -sockopt-receive-low-water and (setf -sockopt-receive-low-water). -|

(sockopt-reuse-address (socket socket) argument)Accessor
-

Return the value of the SO-REUSEADDR socket option for SOCKET. This can also be updated with SETF.
-

(sockopt-keep-alive (socket socket) argument)Accessor
-

Return the value of the SO-KEEPALIVE socket option for SOCKET. This can also be updated with SETF.
-

(sockopt-oob-inline (socket socket) argument)Accessor
-

Return the value of the SO-OOBINLINE socket option for SOCKET. This can also be updated with SETF.
-

(sockopt-bsd-compatible (socket socket) argument)Accessor
-

Return the value of the SO-BSDCOMPAT socket option for SOCKET. This can also be updated with SETF.
-

(sockopt-pass-credentials (socket socket) argument)Accessor
-

Return the value of the SO-PASSCRED socket option for SOCKET. This can also be updated with SETF.
-

(sockopt-debug (socket socket) argument)Accessor
-

Return the value of the SO-DEBUG socket option for SOCKET. This can also be updated with SETF.
-

(sockopt-dont-route (socket socket) argument)Accessor
-

Return the value of the SO-DONTROUTE socket option for SOCKET. This can also be updated with SETF.
-

(sockopt-broadcast (socket socket) argument)Accessor
-

Return the value of the SO-BROADCAST socket option for SOCKET. This can also be updated with SETF.
-

(sockopt-tcp-nodelay (socket socket) argument)Accessor
-

Return the value of the TCP-NODELAY socket option for SOCKET. This can also be updated with SETF.
-

INET-domain sockets

-

-

The TCP and UDP sockets that you know and love. Some representation issues: -

-

-

Class: INET-SOCKET -

Slots:

(make-inet-address dotted-quads)Function
-

Return a vector of octets given a string DOTTED-QUADS in the format -"127.0.0.1"
-

(get-protocol-by-name name)Function
-

Returns the network protocol number associated with the string NAME, -using getprotobyname(2) which typically looks in NIS or /etc/protocols
-

(make-inet-socket type protocol)Function
-

Make an INET socket. Deprecated in favour of make-instance
-

File-domain sockets

-

-File-domain (AF_FILE) sockets are also known as Unix-domain sockets, but were -renamed by POSIX presumably on the basis that they may be -available on other systems too. -

-A file-domain socket address is a string, which is used to create a node -in the local filesystem. This means of course that they cannot be used across -a network. -

-|

Class: UNIX-SOCKET -

Slots:

Name Service

 -

-

Presently name service is implemented by calling whatever -gethostbyname(2) uses. This may be any or all of /etc/hosts, NIS, DNS, -or something completely different. Typically it's controlled by -/etc/nsswitch.conf -

-

Direct links to the asynchronous resolver(3) routines would be nice to have -eventually, so that we can do DNS lookups in parallel with other things -

Class: HOST-ENT -

Slots:

(host-ent-address (host-ent host-ent))Method
-

(get-host-by-name host-name)Function
-

Returns a HOST-ENT instance for HOST-NAME or throws some kind of condition. -HOST-NAME may also be an IP address in dotted quad notation or some other -weird stuff - see gethostbyname(3) for grisly details.
-

(get-host-by-address address)Function
-

Returns a HOST-ENT instance for ADDRESS, which should be a vector of -(integer 0 255), or throws some kind of error. See gethostbyaddr(3) for -grisly details.
-

(name-service-error where)Function
-

(non-blocking-mode (socket socket))Method
-

Is SOCKET in non-blocking mode?
-
-

-

Tests

-

-There should be at least one test for pretty much everything you can do -with the package. In some places I've been more diligent than others; more -tests gratefully accepted. -

-Tests are in the file tests.lisp and also make good examples. -

-| -

Unix-domain sockets

-

-A fairly rudimentary test that connects to the syslog socket and sends a -message. Priority 7 is kern.debug; you'll probably want to look at -/etc/syslog.conf or local equivalent to find out where the message ended up -| \ No newline at end of file diff --git a/contrib/sb-bsd-sockets/doc.lisp b/contrib/sb-bsd-sockets/doc.lisp index b4ecd69..51f417f 100644 --- a/contrib/sb-bsd-sockets/doc.lisp +++ b/contrib/sb-bsd-sockets/doc.lisp @@ -1,3 +1,8 @@ +;;;; the old documentation extracted / generator for db-sockets / sb-bsd-sockets +;;;; +;;;; Not used anymore as the documentation is now integrated into the user manual, +;;;; but I didn't have heart yet to delete this. -- NS 20040801 + (eval-when (:load-toplevel :compile-toplevel :execute) (defpackage :db-doc (:use :cl :asdf #+sbcl :sb-ext #+cmu :ext ))) (in-package :db-doc) diff --git a/contrib/sb-bsd-sockets/index.html b/contrib/sb-bsd-sockets/index.html deleted file mode 100644 index 37a852c..0000000 --- a/contrib/sb-bsd-sockets/index.html +++ /dev/null @@ -1,188 +0,0 @@ -SBCL BSD-Sockets API Reference -

Package SB-BSD-SOCKETS

- -

-A thinly-disguised BSD socket API for SBCL. Ideas stolen from the BSD -socket API for C and Graham Barr's IO::Socket classes for Perl. -

-We represent sockets as CLOS objects, and rename a lot of methods and -arguments to fit Lisp style more closely. -

- -

-

Contents

-

-

    -
  1. General concepts -
  2. Methods applicable to all sockets -
  3. Socket Options -
  4. Methods applicable to a particular subclass -
      -
    1. INET-SOCKET - Internet Protocol (TCP, UDP, raw) sockets -
    2. Methods on UNIX-SOCKET - Unix-domain sockets -
    -
  5. Name resolution (DNS, /etc/hosts, &c) -
-

-

General concepts

-

-

Most of the functions are modelled on the BSD socket API. BSD sockets -are widely supported, portably ("portable" by Unix standards, at least) -available on a variety of systems, and documented. There are some -differences in approach where we have taken advantage of some of the more useful features of Common Lisp - briefly -

-

-

-

-

SOCKETs

-

-

Class: SOCKET -

Slots:

(socket-bind socket &rest address)Generic Function
-

(socket-accept (socket socket))Method
-

Perform the accept(2) call, returning a newly-created connected socket -and the peer address as multiple values
-

(socket-connect socket &rest address)Generic Function
-

(socket-peername (socket socket))Method
-

Return the socket's peer; depending on the address family this may return multiple values
-

(socket-name (socket socket))Method
-

Return the address (as vector of bytes) and port that the socket is bound to, as multiple values
-

(socket-receive (socket socket) buffer length &key oob peek waitall (element-type - 'character))Method
-

Read LENGTH octets from SOCKET into BUFFER (or a freshly-consed buffer if -NIL), using recvfrom(2). If LENGTH is NIL, the length of BUFFER is -used, so at least one of these two arguments must be non-NIL. If -BUFFER is supplied, it had better be of an element type one octet wide. -Returns the buffer, its length, and the address of the peer -that sent it, as multiple values. On datagram sockets, sets MSG_TRUNC -so that the actual packet length is returned even if the buffer was too -small
-

(socket-listen (socket socket) backlog)Method
-

Mark SOCKET as willing to accept incoming connections. BACKLOG -defines the maximum length that the queue of pending connections may -grow to before new connection attempts are refused. See also listen(2)
-

(socket-close (socket socket))Method
-

Close SOCKET. May throw any kind of error that write(2) would have -thrown. If SOCKET-MAKE-STREAM has been called, calls CLOSE on that -stream instead
-

(socket-make-stream (socket socket) &rest args)Method
-

Find or create a STREAM that can be used for IO on SOCKET (which -must be connected). ARGS are passed onto SB-SYS:MAKE-FD-STREAM.
-
-

Socket Options

- -

A subset of socket options are supported, using a fairly -general framework which should make it simple to add more as required -- see sockopt.lisp for details. The name mapping from C is fairly -straightforward: SO_RCVLOWAT becomes -sockopt-receive-low-water and (setf -sockopt-receive-low-water). -|

(sockopt-reuse-address (socket socket) argument)Accessor
-

Return the value of the SO-REUSEADDR socket option for SOCKET. This can also be updated with SETF.
-

(sockopt-keep-alive (socket socket) argument)Accessor
-

Return the value of the SO-KEEPALIVE socket option for SOCKET. This can also be updated with SETF.
-

(sockopt-oob-inline (socket socket) argument)Accessor
-

Return the value of the SO-OOBINLINE socket option for SOCKET. This can also be updated with SETF.
-

(sockopt-bsd-compatible (socket socket) argument)Accessor
-

Return the value of the SO-BSDCOMPAT socket option for SOCKET. This can also be updated with SETF.
-

(sockopt-pass-credentials (socket socket) argument)Accessor
-

Return the value of the SO-PASSCRED socket option for SOCKET. This can also be updated with SETF.
-

(sockopt-debug (socket socket) argument)Accessor
-

Return the value of the SO-DEBUG socket option for SOCKET. This can also be updated with SETF.
-

(sockopt-dont-route (socket socket) argument)Accessor
-

Return the value of the SO-DONTROUTE socket option for SOCKET. This can also be updated with SETF.
-

(sockopt-broadcast (socket socket) argument)Accessor
-

Return the value of the SO-BROADCAST socket option for SOCKET. This can also be updated with SETF.
-

(sockopt-tcp-nodelay (socket socket) argument)Accessor
-

Return the value of the TCP-NODELAY socket option for SOCKET. This can also be updated with SETF.
-

INET-domain sockets

-

-

The TCP and UDP sockets that you know and love. Some representation issues: -

-

-

Class: INET-SOCKET -

Slots:

(make-inet-address dotted-quads)Function
-

Return a vector of octets given a string DOTTED-QUADS in the format -"127.0.0.1"
-

(get-protocol-by-name name)Function
-

Returns the network protocol number associated with the string NAME, -using getprotobyname(2) which typically looks in NIS or /etc/protocols
-

(make-inet-socket type protocol)Function
-

Make an INET socket. Deprecated in favour of make-instance
-

File-domain sockets

-

-File-domain (AF_FILE) sockets are also known as Unix-domain sockets, but were -renamed by POSIX presumably on the basis that they may be -available on other systems too. -

-A file-domain socket address is a string, which is used to create a node -in the local filesystem. This means of course that they cannot be used across -a network. -

-|

Class: UNIX-SOCKET -

Slots:

Name Service

 -

-

Presently name service is implemented by calling whatever -gethostbyname(2) uses. This may be any or all of /etc/hosts, NIS, DNS, -or something completely different. Typically it's controlled by -/etc/nsswitch.conf -

-

Direct links to the asynchronous resolver(3) routines would be nice to have -eventually, so that we can do DNS lookups in parallel with other things -

Class: HOST-ENT -

Slots:

(host-ent-address (host-ent host-ent))Method
-

(get-host-by-name host-name)Function
-

Returns a HOST-ENT instance for HOST-NAME or throws some kind of condition. -HOST-NAME may also be an IP address in dotted quad notation or some other -weird stuff - see gethostbyname(3) for grisly details.
-

(get-host-by-address address)Function
-

Returns a HOST-ENT instance for ADDRESS, which should be a vector of -(integer 0 255), or throws some kind of error. See gethostbyaddr(3) for -grisly details.
-

(name-service-error where)Function
-

(non-blocking-mode (socket socket))Method
-

Is SOCKET in non-blocking mode?
-
-

-

Tests

-

-There should be at least one test for pretty much everything you can do -with the package. In some places I've been more diligent than others; more -tests gratefully accepted. -

-Tests are in the file tests.lisp and also make good examples. -

-| -

Unix-domain sockets

-

-A fairly rudimentary test that connects to the syslog socket and sends a -message. Priority 7 is kern.debug; you'll probably want to look at -/etc/syslog.conf or local equivalent to find out where the message ended up -| \ No newline at end of file diff --git a/contrib/sb-bsd-sockets/inet.lisp b/contrib/sb-bsd-sockets/inet.lisp index f6a7c17..51e79d3 100644 --- a/contrib/sb-bsd-sockets/inet.lisp +++ b/contrib/sb-bsd-sockets/inet.lisp @@ -1,21 +1,18 @@ (in-package :sb-bsd-sockets) -#||

INET-domain sockets

- -

The TCP and UDP sockets that you know and love. Some representation issues: -

- -|# - ;;; Our class and constructor (eval-when (:compile-toplevel :load-toplevel :execute) (defclass inet-socket (socket) - ((family :initform sockint::AF-INET)))) + ((family :initform sockint::AF-INET)) + (:documentation "Class representing TCP and UDP sockets. + +Examples: + + (make-instance 'inet-socket :type :stream :protocol :tcp) + + (make-instance 'inet-socket :type :datagram :protocol :udp) +"))) ;;; XXX should we *...* this? (defparameter inet-address-any (vector 0 0 0 0)) diff --git a/contrib/sb-bsd-sockets/local.lisp b/contrib/sb-bsd-sockets/local.lisp index ccc220b..d77fee7 100644 --- a/contrib/sb-bsd-sockets/local.lisp +++ b/contrib/sb-bsd-sockets/local.lisp @@ -1,21 +1,12 @@ (in-package :sb-bsd-sockets) -#||

Local (unix) domain sockets

- -Local domain (AF_LOCAL) sockets are also known as Unix-domain sockets, but were -renamed by POSIX presumably on the basis that they may be -available on other systems too. - -A local socket address is a string, which is used to create a node -in the local filesystem. This means of course that they cannot be used across -a network. - -||# - (defclass local-socket (socket) - ((family :initform sockint::af-local))) + ((family :initform sockint::af-local)) + (:documentation "Class representing local domain (AF_LOCAL) sockets, +also known as unix-domain sockets.")) -(defmethod make-sockaddr-for ((socket local-socket) &optional sockaddr &rest address &aux (filename (first address))) +(defmethod make-sockaddr-for ((socket local-socket) + &optional sockaddr &rest address &aux (filename (first address))) (let ((sockaddr (or sockaddr (sockint::allocate-sockaddr-un)))) (setf (sockint::sockaddr-un-family sockaddr) sockint::af-local) (when filename diff --git a/contrib/sb-bsd-sockets/name-service.lisp b/contrib/sb-bsd-sockets/name-service.lisp index 2c02fca..03dd6c5 100644 --- a/contrib/sb-bsd-sockets/name-service.lisp +++ b/contrib/sb-bsd-sockets/name-service.lisp @@ -1,25 +1,21 @@ (in-package :sb-bsd-sockets) -#||

Name Service

 - -

Presently name service is implemented by calling whatever -gethostbyname(2) uses. This may be any or all of /etc/hosts, NIS, DNS, -or something completely different. Typically it's controlled by -/etc/nsswitch.conf - -

Direct links to the asynchronous resolver(3) routines would be nice to have -eventually, so that we can do DNS lookups in parallel with other things -|# (defclass host-ent () ((name :initarg :name :accessor host-ent-name) (aliases :initarg :aliases :accessor host-ent-aliases) (address-type :initarg :type :accessor host-ent-address-type) ; presently always AF_INET - (addresses :initarg :addresses :accessor host-ent-addresses))) + (addresses :initarg :addresses :accessor host-ent-addresses)) + ;; FIXME: Our Texinfo documentation extracter need at least his to spit + ;; out the signature. Real documentation would be better... + (:documentation "")) -(defgeneric host-ent-address (host-ent)) +(defgeneric host-ent-address (host-ent) + ;; FIXME: Our Texinfo documentation extracter need at least his to spit + ;; out the signature. Real documentation would be better... + (:documentation "")) -(defmethod host-ent-address ((host-ent host-ent)) +(defmethod host-ent-address ((host-ent host-ent)) (car (host-ent-addresses host-ent))) ;(define-condition host-not-found-error (socket-error)) ; host unknown @@ -79,6 +75,9 @@ grisly details." GET-NAME-SERVICE-ERRNO") (defun name-service-error (where) + ;; FIXME: Our Texinfo documentation extracter need at least his to spit + ;; out the signature. Real documentation would be better... + "" (get-name-service-errno) ;; Comment next to NETDB_INTERNAL in netdb.h says "See errno.". ;; This special case treatment hasn't actually been tested yet. diff --git a/contrib/sb-bsd-sockets/sockets.lisp b/contrib/sb-bsd-sockets/sockets.lisp index 03b6344..4a5249f 100644 --- a/contrib/sb-bsd-sockets/sockets.lisp +++ b/contrib/sb-bsd-sockets/sockets.lisp @@ -3,19 +3,25 @@ ;;;; Methods, classes, functions for sockets. Protocol-specific stuff ;;;; is deferred to inet.lisp, unix.lisp, etc -#||

SOCKETs

- -|# - (eval-when (:load-toplevel :compile-toplevel :execute) (defclass socket () ((file-descriptor :initarg :descriptor :reader socket-file-descriptor) - (family :initform (error "No socket family") :reader socket-family) - (protocol :initarg :protocol :reader socket-protocol) - (type :initarg :type :reader socket-type) - (stream)))) - + (family :initform (error "No socket family") + :reader socket-family) + (protocol :initarg :protocol + :reader socket-protocol + :documentation "Protocol used by the socket. If a +keyword, the symbol-name of the keyword will be passed to +GET-PROTOCOL-BY-NAME downcased, and the returned value used as +protocol. Other values are used as-is.") + (type :initarg :type + :reader socket-type + :documentation "Type of the socket: :STREAM or :DATAGRAM.") + (stream)) + (:documentation "Common base class of all sockets, not ment to be +directly instantiated."))) + (defmethod print-object ((object socket) stream) (print-unreadable-object (object stream :type t :identity t) (princ "descriptor " stream) @@ -205,8 +211,6 @@ small")) (bits-of-sockaddr socket sockaddr))))))) (sb-alien:free-alien copy-buffer)))))) - - (defgeneric socket-listen (socket backlog) (:documentation "Mark SOCKET as willing to accept incoming connections. BACKLOG defines the maximum length that the queue of pending connections may @@ -285,7 +289,8 @@ SB-SYS:MAKE-FD-STREAM.")) (socket-error-syscall c) (or (socket-error-symbol c) (socket-error-errno c)) #+cmu (sb-unix:get-unix-error-msg num) - #+sbcl (sb-int:strerror num)))))) + #+sbcl (sb-int:strerror num))))) + (:documentation "Common base class of socket related conditions.")) ;;; watch out for slightly hacky symbol punning: we use both the value ;;; and the symbol-name of sockint::efoo @@ -333,6 +338,9 @@ SB-SYS:MAKE-FD-STREAM.")) #+sbcl (defun socket-error (where) + ;; FIXME: Our Texinfo documentation extracter need at least his to spit + ;; out the signature. Real documentation would be better... + "" (let* ((errno (sb-unix::get-errno)) (condition (condition-for-errno errno))) (error condition :errno errno :syscall where))) diff --git a/contrib/sb-bsd-sockets/sockopt.lisp b/contrib/sb-bsd-sockets/sockopt.lisp index 04bf3bb..33ecabd 100644 --- a/contrib/sb-bsd-sockets/sockopt.lisp +++ b/contrib/sb-bsd-sockets/sockopt.lisp @@ -1,16 +1,5 @@ (in-package :sb-bsd-sockets) -#|| -

Socket Options

- -

A subset of socket options are supported, using a fairly -general framework which should make it simple to add more as required -- see sockopt.lisp for details. The name mapping from C is fairly -straightforward: SO_RCVLOWAT becomes -sockopt-receive-low-water and (setf -sockopt-receive-low-water). -||# - #| getsockopt(socket, level, int optname, void *optval, socklen_t *optlen) setsockopt(socket, level, int optname, void *optval, socklen_t optlen) @@ -20,7 +9,7 @@ In terms of providing a useful interface, we have to face up to the fact that most of these take different data types - some are integers, some are booleans, some are foreign struct instances, etc etc - (define-socket-option lisp-name level number mangle-arg size mangle-return) + (define-socket-option lisp-name doc level number mangle-arg size mangle-return) macro-expands to two functions that define lisp-name and (setf ,lisp-name) and calls the functions mangle-arg and mangle-return on outgoing and incoming @@ -42,14 +31,13 @@ something that the caller will want. Code for options that not every system has should be conditionalised: (if (boundp 'sockint::IP_RECVIF) - (define-socket-option so-receive-interface (getprotobyname "ip") + (define-socket-option so-receive-interface nil (getprotobyname "ip") sockint::IP_RECVIF ... )) - - |# (defmacro define-socket-option - (lisp-name level number buffer-type mangle-arg mangle-return mangle-setf-buffer) + (lisp-name documentation + level number buffer-type mangle-arg mangle-return mangle-setf-buffer) (let ((find-level (if (numberp (eval level)) level @@ -57,6 +45,7 @@ Code for options that not every system has should be conditionalised: `(progn (export ',lisp-name) (defun ,lisp-name (socket &aux (fd (socket-file-descriptor socket))) + ,@(when documentation (list documentation)) (sb-alien:with-alien ((size sb-alien:integer) (buffer ,buffer-type)) (setf size (sb-alien:alien-size ,buffer-type :bytes)) @@ -85,7 +74,7 @@ Code for options that not every system has should be conditionalised: buffer) (defmacro define-socket-option-int (name level number) - `(define-socket-option ,name ,level ,number + `(define-socket-option ,name nil ,level ,number sb-alien:integer nil foreign-int-to-integer sb-alien:addr)) (define-socket-option-int @@ -111,8 +100,10 @@ Code for options that not every system has should be conditionalised: (defun bool-to-foreign-int (val) (if val 1 0)) -(defmacro define-socket-option-bool (name level number) - `(define-socket-option ,name ,level ,number +(defmacro define-socket-option-bool (name level c-name) + `(define-socket-option ,name + ,(format nil "Return the value of the ~A socket option for SOCKET. This can also be updated with SETF." (symbol-name c-name)) + ,level ,c-name sb-alien:integer bool-to-foreign-int foreign-int-to-bool sb-alien:addr)) (define-socket-option-bool @@ -138,7 +129,7 @@ Code for options that not every system has should be conditionalised: (declare (ignore args)) x) -#+linux(define-socket-option sockopt-bind-to-device sockint::sol-socket +#+linux(define-socket-option sockopt-bind-to-device nil sockint::sol-socket sockint::so-bindtodevice sb-alien:c-string identity identity-1 identity) ;;; other kinds of socket option diff --git a/contrib/sb-bsd-sockets/tests.lisp b/contrib/sb-bsd-sockets/tests.lisp index 3fec556..ba41bc5 100644 --- a/contrib/sb-bsd-sockets/tests.lisp +++ b/contrib/sb-bsd-sockets/tests.lisp @@ -1,18 +1,6 @@ (defpackage "SB-BSD-SOCKETS-TEST" (:use "CL" "SB-BSD-SOCKETS" "SB-RT")) -#|| - -

Tests

- -There should be at least one test for pretty much everything you can do -with the package. In some places I've been more diligent than others; more -tests gratefully accepted. - -Tests are in the file tests.lisp and also make good examples. - -||# - (in-package :sb-bsd-sockets-test) ;;; a real address diff --git a/doc/manual/Makefile b/doc/manual/Makefile index c9b03dd..5251918 100644 --- a/doc/manual/Makefile +++ b/doc/manual/Makefile @@ -15,10 +15,9 @@ HTMLDIR=$(basename $(ROOTFILE)) DOCSTRINGDIR="docstrings/" # List of contrib modules that docstring docs will be created for. # FIXME: should check test-passed and not load them. -MODULES=':sb-md5 :sb-rotate-byte :sb-grovel :sb-sprof' +MODULES=':sb-md5 :sb-rotate-byte :sb-grovel :sb-sprof :sb-bsd-sockets' # List of package names that docstring docs will be created for. -PACKAGES=":COMMON-LISP :SB-ALIEN :SB-DEBUG :SB-EXT :SB-GRAY :SB-MOP :SB-PROFILE :SB-THREAD :SB-MD5 :SB-ROTATE-BYTE :SB-SPROF" - +PACKAGES=":COMMON-LISP :SB-ALIEN :SB-DEBUG :SB-EXT :SB-GRAY :SB-MOP :SB-PROFILE :SB-THREAD :SB-MD5 :SB-ROTATE-BYTE :SB-SPROF :SB-BSD-SOCKETS" ifeq ($(MAKEINFO),) MAKEINFO:=makeinfo diff --git a/doc/manual/create-contrib-doc-list.lisp b/doc/manual/create-contrib-doc-list.lisp index e83f147..2d4db6b 100644 --- a/doc/manual/create-contrib-doc-list.lisp +++ b/doc/manual/create-contrib-doc-list.lisp @@ -31,7 +31,7 @@ (write-line "@end menu" out) (terpri out) (dolist (texi-file texi-files) - (format out "@include ~A~%" + (format out "@page~%@include ~A~%" (namestring (make-pathname :directory (list* :relative :up :up (last @@ -39,4 +39,4 @@ :name (pathname-name texi-file) :type (pathname-type texi-file))))))) -(sb-ext:quit) \ No newline at end of file +(sb-ext:quit) diff --git a/doc/manual/docstrings.lisp b/doc/manual/docstrings.lisp index 814735b..7780fce 100644 --- a/doc/manual/docstrings.lisp +++ b/doc/manual/docstrings.lisp @@ -217,7 +217,6 @@ line)) offset))) - (defun collect-maybe-table-section (lines starting-line arglist-symbols) ;; Return index of next line to be processed outside (let ((this-offset (maybe-table-offset (svref lines starting-line))) @@ -258,9 +257,6 @@ `("" "@table @code" ,@(reverse result) "@end table" "")) nil))) - - - (defun string-as-lines (string) (coerce (with-input-from-string (s string) (loop for line = (read-line s nil nil) @@ -313,7 +309,6 @@ (defvar *characters-to-drop* '(#\\ #\` #\') "Characters that should be removed by `alphanumize'.") - (defun alphanumize (symbol) "Construct a string without characters like *`' that will f-star-ck up filename handling. See `*character-replacements*' @@ -412,6 +407,60 @@ (format nil "~{~A~^ ~}" (mapcar #'texinfoify-arglist-part (argument-list symbol)))))) +(defun hidden-superclass-name-p (class-name superclass-name) + (let ((super-package (symbol-package superclass-name))) + (or + ;; KLUDGE: We assume that we don't want to advertise internal + ;; classes in CP-lists, unless the symbol we're documenting is + ;; internal as well. + (and (member super-package #.'(mapcar #'find-package '(sb-pcl sb-int sb-kernel))) + (not (eq super-package (symbol-package class-name)))) + ;; KLUDGE: We don't generally want to advertise SIMPLE-ERROR or + ;; SIMPLE-CONDITION in the CPLs of conditions that inherit them + ;; simply as a matter of convenience. The assumption here is + ;; that the inheritance is incidental unless the name of the + ;; condition begins with SIMPLE-. + (and (member superclass-name '(simple-error simple-condition)) + (let ((prefix "SIMPLE-")) + (mismatch prefix (string class-name) :end2 (length prefix))) + t ; don't return number from MISMATCH + )))) + +(defun hidden-slot-p (symbol slot) + ;; FIXME: There is no pricipal reason to avoid the slot docs fo + ;; structures and conditions, but their DOCUMENTATION T doesn't + ;; currently work with them the way we'd like. + (not (and (typep (find-class symbol nil) 'standard-class) + (documentation slot t)))) + +(defun classlike-p (symbol kind) + (and (eq 'type kind) + (let ((class (find-class symbol nil))) + (some (lambda (type) + (typep class type)) + '(structure-class standard-class sb-pcl::condition-class))))) + +(defun def-body (symbol kind docstring) + (with-output-to-string (s) + (when (classlike-p symbol kind) + (format s "Class precedence list: @code{~(~{@w{~A}~^, ~}~)}~%~%" + (remove-if (lambda (super) + (hidden-superclass-name-p symbol super)) + (mapcar #'class-name + (sb-mop:class-precedence-list (find-class symbol))))) + (let ((documented-slots (remove-if (lambda (slot) + (hidden-slot-p symbol slot)) + (sb-mop:class-direct-slots (find-class symbol))))) + (when documented-slots + (format s "Slots:~%@itemize~%") + (dolist (slot documented-slots) + (format s "@item ~(@code{~A} ~@[--- initargs: @code{~{@w{~S}~^, ~}}~]~)~%~%~A~%" + (sb-mop:slot-definition-name slot) + (sb-mop:slot-definition-initargs slot) + (frob-docstring (documentation slot t) nil))) + (format s "@end itemize~%~%")))) + (write-string (frob-docstring docstring (ignore-errors (argument-list symbol))) s))) + (defun def-end (symbol kind) (declare (ignore symbol)) (ecase kind @@ -436,15 +485,7 @@ (with-open-file (out filename :direction :output :if-does-not-exist :create :if-exists :supersede) (loop for (symbol kind docstring) in docs - do (format out "~&@anchor{~A}~%~A ~A:~A~@[ ~A~]~%~A~&~A~%~A~%~%" - (unique-name symbol package kind) - (def-begin symbol kind) - (texinfoify (package-name package)) - (texinfoify symbol) - (def-arglist symbol kind) - (def-index symbol kind) - (frob-docstring docstring (argument-list symbol)) - (def-end symbol kind)))) + do (write-texinfo out package symbol kind docstring))) filename)) (defun docstrings-to-texinfo (directory &rest packages) @@ -469,13 +510,16 @@ directory) :direction :output :if-does-not-exist :create :if-exists :supersede) - (format out "~&@anchor{~A}~%~A ~A:~A~@[ ~A~]~%~A~&~A~%~A~%~%" - (unique-name symbol package kind) - (def-begin symbol kind) - (texinfoify (package-name package)) - (texinfoify symbol) - (def-arglist symbol kind) - (def-index symbol kind) - (frob-docstring docstring (ignore-errors (argument-list symbol))) - (def-end symbol kind))))) + (write-texinfo out package symbol kind docstring)))) directory)) + +(defun write-texinfo (stream package symbol kind docstring) + (format stream "~&@anchor{~A}~%~A ~A:~A~@[ ~A~]~%~A~&~A~%~A~%~%" + (unique-name symbol package kind) + (def-begin symbol kind) + (texinfoify (package-name package)) + (texinfoify symbol) + (def-arglist symbol kind) + (def-index symbol kind) + (def-body symbol kind docstring) + (def-end symbol kind))) diff --git a/version.lisp-expr b/version.lisp-expr index 688d019..da2f19e 100644 --- a/version.lisp-expr +++ b/version.lisp-expr @@ -17,4 +17,4 @@ ;;; checkins which aren't released. (And occasionally for internal ;;; versions, especially for internal versions off the main CVS ;;; branch, it gets hairier, e.g. "0.pre7.14.flaky4.13".) -"0.8.13.13" +"0.8.13.14" -- 1.7.10.4