* 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
+ * documentation: documentation for SB-BSD-SOCKETS, SB-GRAY,
+ SB-SIMPLE-STREAMS, and SB-PROFILE have been integrated into the user
+ manual.
has been integrated into the user manual.
* bug fix: SBCL can now load its contributed modules with REQUIRE
even if the system-provided entries have been removed from
-@node sb-bsd-sockets
-@section sb-bsd-sockets
+@c This currently appears in the manual as a chapter: if a
+@c higher-level interface appear, it will make sense to lower this
+@c into a section.
@cindex Sockets, Networking
-The @code{sb-bsd-sockets} module provides 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.
+The @code{sb-bsd-sockets} module provides a thinly disguised BSD
+socket API for SBCL. Ideas have been stolen from the BSD socket API
+for C and Graham Barr's IO::Socket classes for Perl.
Sockets are represented as CLOS objects, and the API naming
conventions attempt to balance between the BSD names and good lisp style.
@end menu
@node Sockets Overview
-@subsection Sockets Overview
+@section Sockets Overview
Most of the functions are modelled on the BSD socket API. BSD sockets
are widely supported, portably @emph{(``portable'' by Unix standards, at least)}
@end itemize
@node General Sockets
-@subsection General Sockets
+@section General Sockets
@include class-sb-bsd-sockets-socket.texinfo
@include fun-sb-bsd-sockets-non-blocking-mode.texinfo
@node Socket Options
-@subsection Socket Options
+@section 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
@include fun-sb-bsd-sockets-sockopt-tcp-nodelay.texinfo
@node INET Domain Sockets
-@subsection INET Domain Sockets
+@section INET Domain Sockets
The TCP and UDP sockets that you know and love. Some representation
issues:
@include fun-sb-bsd-sockets-get-protocol-by-name.texinfo
@node Local (Unix) Domain Sockets
-@subsection Local (Unix) Domain Sockets
+@section Local (Unix) Domain Sockets
Local domain (@code{AF_LOCAL}) sockets are also known as Unix-domain
sockets, but were renamed by POSIX presumably on the basis that they
@include class-sb-bsd-sockets-local-socket.texinfo
@node Name Service
-@subsection Name Service
+@section Name Service
Presently name service is implemented by calling whatever
@code{gethostbyname(2)} uses. This may be any or all of
--- /dev/null
+Simple streams are an extensible streams protocol that avoids some
+problems with Gray streams.
+
+Documentation about simple streams is available at:
+
+@uref{http://www.franz.com/support/documentation/6.2/doc/streams.htm}
+
+The implementation should be considered Alpha-quality; the basic
+framework is there, but many classes are just stubs at the moment.
+
+See @file{SYS:CONTRIB;SB-SIMPLE-STREAMS;SIMPLE-STREAM-TEST.LISP} for
+things that should work.
+
+Known differences to the ACL behaviour:
+
+@itemize
+
+@item
+@code{open} not return a simple-stream by default. This can be
+adjusted; see default-open-class in the file cl.lisp
+
+@item
+@code{write-vector} is unimplemented.
+
+@end itemize
-@node sb-sprof
-@section sb-sprof
-@cindex Profiler
-
-The @code{sb-sprof} module provides an alternate profiler which works by
-taking samples of the program execution at regular intervals, instead of
-instrumenting functions like @code{profile} does. You might find
-@code{sb-sprof} more useful than @code{profile} when profiling functions
-in the @code{common-lisp}-package, SBCL internals, or code where the
-instrumenting overhead is excessive.
+@cindex Profiling, statistical
+
+The @code{sb-sprof} module, loadable by
+@lisp
+(require :sb-sprof)
+@end lisp
+provides an alternate profiler which works by taking samples of the
+program execution at regular intervals, instead of instrumenting
+functions like @code{sb-profile:profile} does. You might find
+@code{sb-sprof} more useful than accurate profiler when profiling
+functions in the @code{common-lisp}-package, SBCL internals, or code
+where the instrumenting overhead is excessive.
This module is known not to work consistently on the Alpha platform,
for technical reasons related to the implementation of a machine
-
DOCFILES:=$(shell echo *.texinfo)
ROOTFILE:=sbcl.texinfo
TMPFILES:=sbcl.aux sbcl.cp sbcl.fn sbcl.ky sbcl.log sbcl.pg sbcl.toc sbcl.tp sbcl.vr
# DOCSTRINGDIR has to end with a slash or you lose (it's passed to
# Lisp's `pathname' function).
DOCSTRINGDIR="docstrings/"
+I_FLAGS=-I $(DOCSTRINGDIR) -I ../../contrib/
# 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 :sb-bsd-sockets'
html-stamp: variables $(DOCFILES) docstrings
@rm -rf $(HTMLDIR)
- $(MAKEINFO) -I $(DOCSTRINGDIR) --html $(ROOTFILE)
+ $(MAKEINFO) $(I_FLAGS) --html $(ROOTFILE)
touch html-stamp
# Postscript documentation
dvips -o $@ $<
$(DVIFILE): variables $(DOCFILES) docstrings
- texi2dvi -I $(DOCSTRINGDIR) $(ROOTFILE)
+ texi2dvi $(I_FLAGS) $(ROOTFILE)
# PDF documentation
.PHONY: pdf
pdf: $(PDFFILE)
$(PDFFILE): variables $(DOCFILES) docstrings
- texi2pdf -I $(DOCSTRINGDIR) $(ROOTFILE)
+ texi2pdf $(I_FLAGS) $(ROOTFILE)
# info docfiles
.PHONY: info
info: $(INFOFILE)
$(INFOFILE): variables $(DOCFILES) docstrings
- $(MAKEINFO) -I $(DOCSTRINGDIR) $(ROOTFILE)
+ $(MAKEINFO) $(I_FLAGS) $(ROOTFILE)
# contrib-modules.texinfo includes contrib-doc-list.texi-temp
contrib-modules.texinfo: tempfiles-stamp
-@node Beyond The ANSI Standard
-@comment node-name, next, previous, up
-@chapter Beyond The ANSI Standard
-
SBCL is mostly an implementation of the ANSI standard for
Common Lisp. However, there's some important behavior which extends
or clarifies the standard, and various behavior which outright
Declarations are generally treated as assertions. This general
principle, and its implications, and the bugs which still keep the
compiler from quite satisfying this principle, are discussed in
-@ref{The Compiler}.
+@ref{Compiler}.
SBCL is essentially a compiler-only implementation of Common
Lisp. That is, for all but a few special cases, @code{eval} creates a
@comment node-name, next, previous, up
@subsection Things Which Might Be In The Next ANSI Standard
-SBCL provides extensive support for calling external C code, @ref{The
-Foreign Function Interface}.
+SBCL provides extensive support for calling external C code,
+@ref{Foreign Function Interface}.
SBCL provides additional garbage collection functionality not
specified by ANSI. Weak pointers allow references to objects to be
facility. For more information, see @ref{macro-common-lisp-trace}.
The debugger supports a number of options. Its documentation is
-accessed by typing @kbd{help} at the debugger prompt. @xref{The
-Debugger}.
+accessed by typing @kbd{help} at the debugger prompt. @xref{Debugger}.
Documentation for @code{inspect} is accessed by typing @kbd{help} at
the @code{inspect} prompt.
-@node The Compiler
-@comment node-name, next, previous, up
-@chapter The Compiler
-
This chapter will discuss most compiler issues other than
efficiency, including compiler error messages, the SBCL compiler's
unusual approach to type safety in the presence of type declarations,
-@node Contributed Modules
-@comment node-name, next, previous, up
-@chapter Contributed Modules
-
SBCL comes with a number of modules that are not part of the core
system. These are loaded via @code{(require :@var{modulename})}
(@pxref{Customization Hooks for Users}). This section contains
documentation (or pointers to documentation) for the contributed
modules.
-@include contrib-doc-list.texi-temp
+@menu
+* sb-aclrepl::
+* sb-grovel::
+* sb-md5::
+* sb-rotate-byte::
+@end menu
+
+@page
+@include sb-aclrepl/sb-aclrepl.texinfo
+
+@page
+@include sb-grovel/sb-grovel.texinfo
+
+@page
+@include sb-md5/sb-md5.texinfo
+
+@page
+@include sb-rotate-byte/sb-rotate-byte.texinfo
+
-@node The Debugger
-@comment node-name, next, previous, up
-@chapter The Debugger
@cindex Debugger
The SBCL debugger (as the CMUCL debugger it was derived from) has very
-@node Efficiency
-@comment node-name, next, previous, up
-@chapter Efficiency
+@cindex Efficiency
FIXME: The material in the CMUCL manual about getting good
performance from the compiler should be reviewed, reformatted in
-@node The Foreign Function Interface
-@comment node-name, next, previous, up
-@chapter The Foreign Function Interface
-
This chapter describes SBCL's interface to C programs and
libraries (and, since C interfaces are a sort of @emph{ingua
franca} of the Unix world, to other programs and libraries in
-@node Introduction
-@comment node-name, next, previous, up
-@chapter Introduction
-
SBCL is a mostly-conforming implementation of the ANSI Common Lisp
standard. This manual focuses on behavior which is specific to SBCL,
not on behavior which is common to all implementations of ANSI Common
#!/bin/sh
# Create Texinfo snippets from the documentation of exported symbols.
-# Also create contrib-docs.texi-temp to include documentation in contrib/.
# This software is part of the SBCL system. See the README file for
# more information.
echo /creating docstring snippets from SBCL=\'$SBCLRUNTIME\' for packages \'$PACKAGES\'
echo "(progn (load \"docstrings.lisp\") (dolist (module (quote ($MODULES))) (require module)) (docstrings-to-texinfo \"$DOCSTRINGDIR\" $PACKAGES) (sb-ext:quit))" | $SBCL
-echo /creating contrib-docs.texi-temp
-echo "(load \"create-contrib-doc-list.lisp\")" | $SBCL
-
echo /creating package-locks.texi-temp
if $SBCL --eval "(let ((plp (find-symbol \"PACKAGE-LOCKED-P\" :sb-ext))) (quit :unix-status (if (and plp (fboundp plp)) 0 1)))";
then
-@node Package Locks
-@comment node-name, next, previous, up
-@chapter Package Locks
-
SBCL can be built with support for package locks to protect against
unintentional modifications of packages. The full documentation for
package locks is only built if package locks are enabled in the image
-@node Package Locks
-@comment node-name, next, previous, up
-@chapter Package Locks
+@cindex Packages, locked
None of the following sections apply to SBCL built without package
locksing support.
--- /dev/null
+@cindex Profiling
+
+SBCL includes both an accurate profiler, that can collect statistics
+on individual functions, and a more ``modern'' statistical profiler.
+
+Inlined functions do not appear in the results reported by either.
+
+@menu
+* Accurate Profiler::
+* Statistical Profiler::
+@end menu
+
+@node Accurate Profiler
+@comment node-name, next, previous, up
+@section Accurate Profiler
+@cindex Profiling, accurate
+
+The package @code{sb-profile} provides a classic, per-function-call
+profiler.
+
+@include macro-sb-profile-profile.texinfo
+@include macro-sb-profile-unprofile.texinfo
+@include fun-sb-profile-report.texinfo
+@include fun-sb-profile-reset.texinfo
+
+@node Statistical Profiler
+@comment node-name, next, previous, up
+@section Statistical Profiler
+@include sb-sprof/sb-sprof.texinfo
@insertcopying
@menu
-* Introduction::
-* The Compiler::
-* The Debugger::
-* Efficiency::
-* Beyond The ANSI Standard::
-* The Foreign Function Interface::
-* Package Locks::
-* Contributed Modules::
-* Concept Index::
-* Function Index::
-* Variable Index::
-* Type Index::
-* Colophon::
+* Introduction::
+* Compiler::
+* Debugger::
+* Efficiency::
+* Beyond the ANSI Standard::
+* Foreign Function Interface::
+* Extensible Streams::
+* Package Locks::
+* Networking::
+* Profiling::
+* Contributed Modules::
+* Concept Index::
+* Function Index::
+* Variable Index::
+* Type Index::
+* Colophon::
@end menu
@end ifnottex
+@node Introduction
+@comment node-name, next, previous, up
+@chapter Introduction
@include intro.texinfo
+
+@node Compiler
+@comment node-name, next, previous, up
+@chapter Compiler
@include compiler.texinfo
+
+@node Debugger
+@comment node-name, next, previous, up
+@chapter Debugger
@include debugger.texinfo
+
+@node Efficiency
+@comment node-name, next, previous, up
+@chapter Efficiency
@include efficiency.texinfo
+
+@node Beyond the ANSI Standard
+@comment node-name, next, previous, up
+@chapter Beyond the ANSI Standard
@include beyond-ansi.texinfo
+
+@node Foreign Function Interface
+@comment node-name, next, previous, up
+@chapter Foreign Function Interface
@include ffi.texinfo
+
+@node Extensible Streams
+@comment node-name, next, previous, up
+@chapter Extensible Streams
+@include streams.texinfo
+
+@node Package Locks
+@comment node-name, next, previous, up
+@chapter Package Locks
@include package-locks.texi-temp
+
+@node Networking
+@comment node-name, next, previous, up
+@chapter Networking
+@include sb-bsd-sockets/sb-bsd-sockets.texinfo
+
+@node Profiling
+@comment node-name, next, previous, up
+@chapter Profiling
+@include profiling.texinfo
+
+@node Contributed Modules
+@comment node-name, next, previous, up
+@chapter Contributed Modules
@include contrib-modules.texinfo
-@include backmatter.texinfo
+
+@node Concept Index
+@comment node-name, next, previous, up
+@appendix Concept Index
+@printindex cp
+
+@node Function Index
+@comment node-name, next, previous, up
+@appendix Function Index
+@printindex fn
+
+@node Variable Index
+@comment node-name, next, previous, up
+@appendix Variable Index
+@printindex vr
+
+@node Type Index
+@comment node-name, next, previous, up
+@appendix Type Index
+@printindex tp
+
+@node Colophon
+@comment node-name, next, previous, up
+@unnumbered Colophon
+
+This manual is maintained in Texinfo, and automatically translated
+into other forms (e.g. HTML or pdf). If you're @emph{reading} this
+manual in one of these non-Texinfo translated forms, that's fine, but
+if you want to @emph{modify} this manual, you are strongly advised to
+seek out a Texinfo version and modify that instead of modifying a
+translated version. Even better might be to seek out @emph{the}
+Texinfo version (maintained at the time of this writing as part of the
+SBCL project at @uref{http://sbcl.sourceforge.net/}) and submit a
+patch.
+
@bye
--- /dev/null
+SBCL supports @dfn{Gray streams}, user-overloadable CLOS classes whose
+instances can be used as Lisp streams (e.g. passed as the first
+argument to @code{format}). Additionally, the bundled contrib module
+@dfn{sb-simple-streams} implements a subset of the Franz Allegro
+simple-streams proposal.
+
+@menu
+* Gray Streams::
+* Simple Streams::
+@end menu
+
+@node Gray Streams
+@section Gray Streams
+
+@include class-sb-gray-fundamental-stream.texinfo
+@include fun-sb-gray-stream-advance-to-column.texinfo
+@include fun-sb-gray-stream-clear-input.texinfo
+@include fun-sb-gray-stream-clear-output.texinfo
+@include fun-sb-gray-stream-finish-output.texinfo
+@include fun-sb-gray-stream-force-output.texinfo
+@include fun-sb-gray-stream-fresh-line.texinfo
+@include fun-sb-gray-stream-line-column.texinfo
+@include fun-sb-gray-stream-line-length.texinfo
+@include fun-sb-gray-stream-listen.texinfo
+@include fun-sb-gray-stream-peek-char.texinfo
+@include fun-sb-gray-stream-read-byte.texinfo
+@include fun-sb-gray-stream-read-char-no-hang.texinfo
+@include fun-sb-gray-stream-read-char.texinfo
+@include fun-sb-gray-stream-read-line.texinfo
+@include fun-sb-gray-stream-read-sequence.texinfo
+@include fun-sb-gray-stream-start-line-p.texinfo
+@include fun-sb-gray-stream-terpri.texinfo
+@include fun-sb-gray-stream-unread-char.texinfo
+@include fun-sb-gray-stream-write-byte.texinfo
+@include fun-sb-gray-stream-write-char.texinfo
+@include fun-sb-gray-stream-write-sequence.texinfo
+@include fun-sb-gray-stream-write-string.texinfo
+
+@node Simple Streams
+@comment node-name, next, previous, up
+@section Simple Streams
+@include sb-simple-streams/sb-simple-streams.texinfo
;;; 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.69"
+"0.8.13.70"
projects / sbcl.git / commitdiff