DVIFILE=sbcl.dvi
INFOFILE=sbcl.info
HTMLDIR=$(basename $(ROOTFILE))
-# The value of DOCSTRINGDIR has to end with a slash or you lose (it's
-# passed to Lisp's `pathname' function).
+# Place where generated documentation ends up. The value of
+# DOCSTRINGDIR has to end with a slash or you lose (it's passed to
+# Lisp's `pathname' function).
DOCSTRINGDIR="docstrings/"
+# List of package names that documentation will be created for.
+PACKAGES=":COMMON-LISP :SB-ALIEN :SB-DEBUG :SB-EXT :SB-GRAY :SB-MOP :SB-PROFILE :SB-THREAD"
ifeq ($(MAKEINFO),)
.PHONY: clean
clean:
- rm -f *~ *.bak *.orig \#*\# .\#* texput.log
+ rm -f *~ *.bak *.orig \#*\# .\#* texput.log *.fasl
rm -rf $(HTMLDIR) $(DOCSTRINGDIR)
rm -f $(PSFILE) $(PDFFILE) $(DVIFILE) html-stamp docstrings-stamp
rm -f $(TMPFILES)
--- /dev/null
+-*- text -*-
+
+Some hints for editing the manual files. Feel free to add anything
+that will save the next person some time. Thanks!
+
+
+- There's no need for Next, Prev, etc. pointers in @node lines:
+ makeinfo will deduce these automatically when the line after @node
+ contains a sectioning command like @section, @subsection. Hence,
+ texinfo-multiple-files-update should not be used either.
+
+- Don't create or update Menus by hand; use C-c C-u C-a
+ (texinfo-all-menus-update) instead. (Doesn't work in sbcl.texinfo,
+ but this file is only changed when an entire chapter is added.)
-@node Function Index, Concept Index, The Foreign Function Interface, Top
+@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 Concept Index, Colophon, Function Index, Top
+@node Variable Index
@comment node-name, next, previous, up
-@appendix Concept Index
-
-@printindex cp
+@appendix Variable Index
+
+@printindex vr
-@node Colophon, , Concept Index, Top
+@node Colophon
@comment node-name, next, previous, up
@unnumbered Colophon
-@node Beyond The ANSI Standard, The Foreign Function Interface, Efficiency, Top
+@node Beyond The ANSI Standard
@comment node-name, next, previous, up
@chapter Beyond The ANSI Standard
* Extensions::
@end menu
-@node Non-Conformance With The ANSI Standard, Idiosyncrasies, Beyond The ANSI Standard, Beyond The ANSI Standard
+@node Non-Conformance With The ANSI Standard
@comment node-name, next, previous, up
@section Non-Conformance With The ANSI Standard
addresses, @ref{More SBCL Information}.
-@node Idiosyncrasies, Extensions, Non-Conformance With The ANSI Standard, Beyond The ANSI Standard
+@node Idiosyncrasies
@comment node-name, next, previous, up
@section Idiosyncrasies
case, but still isn't as of SBCL 0.7.6.)
-@node Extensions, , Idiosyncrasies, Beyond The ANSI Standard
+@node Extensions
@comment node-name, next, previous, up
@section Extensions
* Efficiency Hacks::
@end menu
-@node Things Which Might Be In The Next ANSI Standard, Threading, Extensions, Extensions
+@node Things Which Might Be In The Next ANSI Standard
@comment node-name, next, previous, up
@subsection Things Which Might Be In The Next ANSI Standard
@end itemize
-@node Threading, Support For Unix, Things Which Might Be In The Next ANSI Standard, Extensions
+@node Threading
@comment node-name, next, previous, up
@subsection Threading (a.k.a Multiprocessing)
this has been found to be embarrassing.
-@node Support For Unix, Customization Hooks for Users, Threading, Extensions
+@node Support For Unix
@comment node-name, next, previous, up
@subsection Support For Unix
@include fun-sb-ext-quit.texinfo
-@node Customization Hooks for Users, Tools To Help Developers, Support For Unix, Extensions
+@node Customization Hooks for Users
@comment node-name, next, previous, up
@subsection Customization Hooks for Users
-The behaviour of @code{require} when called with only one argument is
-implementation-defined. In SBCL it calls functions on the
-user-settable list @code{sb-ext:*module-provider-functions*} - see the
-@code{require} documentation string for details.
-
The toplevel repl prompt may be customized, and the function
that reads user input may be replaced completely.
@c <!-- FIXME but I don't currently remember how -->
+The behaviour of @code{require} when called with only one argument is
+implementation-defined. In SBCL, @code{require} behaves in the
+following way:
+
+@include fun-common-lisp-require.texinfo
+
+@include var-sb-ext-star-module-provider-functions-star.texinfo
+
-@node Tools To Help Developers, Interface To Low-Level SBCL Implementation, Customization Hooks for Users, Extensions
+@node Tools To Help Developers
@comment node-name, next, previous, up
@subsection Tools To Help Developers
-SBCL provides a profiler and other extensions to the ANSI
-@code{trace} facility. See the online function documentation for
-@code{trace} for more information.
+SBCL provides a profiler and other extensions to the ANSI @code{trace}
+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.
-@c <!-- FIXME:
-@c A true debugger section in the manual would be good. Start
-@c with CMU CL's debugger section, but remember:
-@c * no QUIT command (TOPLEVEL restart instead)
-@c * no GO command (CONTINUE restart instead)
-@c * Limitations of the x86 port of the debugger should be
-@c documented or fixed where possible.
-@c * Discuss TRACE and its unification with PROFILE. -->
+accessed by typing @kbd{help} at the debugger prompt. @xref{The
+Debugger}.
Documentation for @code{inspect} is accessed by typing @kbd{help} at
the @code{inspect} prompt.
-@node Interface To Low-Level SBCL Implementation, Efficiency Hacks, Tools To Help Developers, Extensions
+@node Interface To Low-Level SBCL Implementation
@comment node-name, next, previous, up
@subsection Interface To Low-Level SBCL Implementation
@end quotation
-@node Efficiency Hacks, , Interface To Low-Level SBCL Implementation, Extensions
+@node Efficiency Hacks
@comment node-name, next, previous, up
@subsection Efficiency Hacks
-@node The Compiler, The Debugger, Introduction, Top
+@node The Compiler
@comment node-name, next, previous, up
@chapter The Compiler
* Open Coding and Inline Expansion::
@end menu
-@node Error Messages, Handling of Types, The Compiler, The Compiler
+@node Error Messages
@comment node-name, next, previous, up
@section Error Messages
@cindex Error messages, Compiler
* Read Errors::
@end menu
-@node The Parts of the Error Message, The Original and Actual Source, Error Messages, Error Messages
+@node The Parts of the Error Message
@comment node-name, next, previous, up
@subsection The Parts of the Error Message
processing path will also be omitted.
-@node The Original and Actual Source, Error Severity, The Parts of the Error Message, Error Messages
+@node The Original and Actual Source
@comment node-name, next, previous, up
@subsection The Original and Actual Source
explanation, so the compiler backed out one level.
-@node Error Severity, Errors During Macroexpansion, The Original and Actual Source, Error Messages
+@node Error Severity
@comment node-name, next, previous, up
@subsection Error Severity
@cindex Severity of compiler errors
improved.
-@node Errors During Macroexpansion, Read Errors, Error Severity, Error Messages
+@node Errors During Macroexpansion
@comment node-name, next, previous, up
@subsection Errors During Macroexpansion
@cindex Macroexpansion, errors during
@end example
-@node Read Errors, , Errors During Macroexpansion, Error Messages
+@node Read Errors
@comment node-name, next, previous, up
@subsection Read Errors
@cindex Read errors, compiler
@c _ -->
-@node Handling of Types, Compiler Policy, Error Messages, The Compiler
+@node Handling of Types
@comment node-name, next, previous, up
@section The Compiler's Handling of Types
@end menu
-@node Type Errors at Compile Time, Precise Type Checking, Handling of Types, Handling of Types
+@node Type Errors at Compile Time
@comment node-name, next, previous, up
@subsection Type Errors at Compile Time
@cindex Compile time type errors
fragment that has spurious warnings.
-@node Precise Type Checking, Weakened Type Checking, Type Errors at Compile Time, Handling of Types
+@node Precise Type Checking
@comment node-name, next, previous, up
@subsection Precise Type Checking
@cindex Precise type checking
@code{member}, and other list-style type specifiers.
-@node Weakened Type Checking, Getting Existing Programs to Run, Precise Type Checking, Handling of Types
+@node Weakened Type Checking
@comment node-name, next, previous, up
@subsection Weakened Type Checking
@cindex Weakened type checking
nonexistent runtime checking.
-@node Getting Existing Programs to Run, Implementation Limitations, Weakened Type Checking, Handling of Types
+@node Getting Existing Programs to Run
@comment node-name, next, previous, up
@subsection Getting Existing Programs to Run
@cindex Existing programs, to run
@c <!-- FIXME: <xref>ND-variables, once we crib the text from the
@c CMU CL manual. -->
-@node Implementation Limitations, , Getting Existing Programs to Run, Handling of Types
+@node Implementation Limitations
@comment node-name, next, previous, up
@subsection Implementation Limitations
may, alas, remain in the system for a while.
-@node Compiler Policy, Open Coding and Inline Expansion, Handling of Types, The Compiler
+@node Compiler Policy
@comment node-name, next, previous, up
@section Compiler Policy
@c _-->
-@node Open Coding and Inline Expansion, , Compiler Policy, The Compiler
+@node Open Coding and Inline Expansion
@comment node-name, next, previous, up
@section Open Coding and Inline Expansion
@cindex Open-coding
-@node The Debugger, Efficiency, The Compiler, Top
+@node The Debugger
@comment node-name, next, previous, up
@chapter The Debugger
@cindex Debugger
* Function Tracing::
@end menu
-@node Starting the Debugger, The Debugger Command Loop, The Debugger, The Debugger
+@node Starting the Debugger
@comment node-name, next, previous, up
@section Starting the Debugger
frame and the debugger prompt.
-@node The Debugger Command Loop, Controlling Printing in the Debugger, Starting the Debugger, The Debugger
+@node The Debugger Command Loop
@comment node-name, next, previous, up
@section The Debugger Command Loop
@cindex Evaluation, in the debugger
@ref{Variable Access}.
-@node Controlling Printing in the Debugger, Stack Frames, The Debugger Command Loop, The Debugger
+@node Controlling Printing in the Debugger
@comment node-name, next, previous, up
@section Controlling Printing in the Debugger
@end defvr
-@node Stack Frames, Variable Access, Controlling Printing in the Debugger, The Debugger
+@node Stack Frames
@comment node-name, next, previous, up
@section Stack Frames
@cindex Stack frames
* Unknown Locations and Interrupts::
@end menu
-@node Stack Motion, How Arguments are Printed, Stack Frames, Stack Frames
+@node Stack Motion
@comment node-name, next, previous, up
@subsection Stack Motion
@end deffn
-@node How Arguments are Printed, Function Names, Stack Motion, Stack Frames
+@node How Arguments are Printed
@comment node-name, next, previous, up
@subsection How Arguments are Printed
the Debugger}.
-@node Function Names, Funny Frames, How Arguments are Printed, Stack Frames
+@node Function Names
@comment node-name, next, previous, up
@subsection Function Names
form if there is no @code{def@var{mumble}}.
-@node Funny Frames, Debug Tail Recursion, Function Names, Stack Frames
+@node Funny Frames
@comment node-name, next, previous, up
@subsection Funny Frames
@cindex External entry points
@c @ref{open-coding}
-@node Debug Tail Recursion, Unknown Locations and Interrupts, Funny Frames, Stack Frames
+@node Debug Tail Recursion
@comment node-name, next, previous, up
@subsection Debug Tail Recursion
@cindex Tail recursion
@c For a more thorough discussion of tail recursion, @ref{tail-recursion}.
-@node Unknown Locations and Interrupts, , Debug Tail Recursion, Stack Frames
+@node Unknown Locations and Interrupts
@comment node-name, next, previous, up
@subsection Unknown Locations and Interrupts
@cindex Unknown code locations
located. If this happens, return from the interrupt and try again.
-@node Variable Access, Source Location Printing, Stack Frames, The Debugger
+@node Variable Access
@comment node-name, next, previous, up
@section Variable Access
@cindex Debug variables
* Note On Lexical Variable Access::
@end menu
-@node Variable Value Availability, Note On Lexical Variable Access, Variable Access, Variable Access
+@node Variable Value Availability
@comment node-name, next, previous, up
@subsection Variable Value Availability
@cindex Availability of debug variables
known locations.
-@node Note On Lexical Variable Access, , Variable Value Availability, Variable Access
+@node Note On Lexical Variable Access
@comment node-name, next, previous, up
@subsection Note On Lexical Variable Access
things happening.
-@node Source Location Printing, Debugger Policy Control, Variable Access, The Debugger
+@node Source Location Printing
@comment node-name, next, previous, up
@section Source Location Printing
@cindex Source location printing, debugger
* Source Location Availability::
@end menu
-@node How the Source is Found, Source Location Availability, Source Location Printing, Source Location Printing
+@node How the Source is Found
@comment node-name, next, previous, up
@subsection How the Source is Found
@code{##} in perverted ways, you don't need to worry about this.
-@node Source Location Availability, , How the Source is Found, Source Location Printing
+@node Source Location Availability
@comment node-name, next, previous, up
@subsection Source Location Availability
@cindex Debug optimization quality
program on you.)
-@node Debugger Policy Control, Exiting Commands, Source Location Printing, The Debugger
+@node Debugger Policy Control
@comment node-name, next, previous, up
@section Debugger Policy Control
@cindex Policy, debugger
the original function.
-@node Exiting Commands, Information Commands, Debugger Policy Control, The Debugger
+@node Exiting Commands
@comment node-name, next, previous, up
@section Exiting Commands
@end deffn
-@node Information Commands, Function Tracing, Exiting Commands, The Debugger
+@node Information Commands
@comment node-name, next, previous, up
@section Information Commands
@c @end example
-@node Function Tracing, , Information Commands, The Debugger
+@node Function Tracing
@comment node-name, next, previous, up
@section Function Tracing
@cindex Tracing
printing of the trace information and conditional breakpoints on
function entry or exit.
-@comment rudi 2004-03-26: The docstring for `trace' is quite comprehensive,
-@comment so refer to it (see also ``OAOO'')
-The docstrings for @code{trace} and @code{untrace} explain SBCL's
-tracing facility.
+@include macro-common-lisp-trace.texinfo
-@comment FIXME rudi 2004-03-26: revive the documentation of variables
-@comment describing trace behaviour: *trace-encapsulate-default*,
-@comment *max-trace-indentation* and friends. Some of these are
-@comment mentioned (perhaps under different names) in the cmucl
-@comment manual.
+@include macro-common-lisp-untrace.texinfo
+
+@include var-sb-debug-star-trace-indentation-step-star.texinfo
+
+@include var-sb-debug-star-max-trace-indentation-star.texinfo
+
+@include var-sb-debug-star-trace-encapsulate-default-star.texinfo
+
+@include var-sb-debug-star-trace-values-star.texinfo
@comment FIXME rudi 2004-03-26: encapsulate is (per TODO file as of
@comment 0.8.9) in a state of flux. When it's sorted out, revive the
;;;; -*- lisp -*-
-;;;; (c) 2004 Rudi Schlatte <rudi@constantly.at>
-;;;; Use it as you wish, send changes back to me if you like.
+;;;; A docstring extractor for the sbcl manual. Creates
+;;;; @include-ready documentation from the docstrings of exported
+;;;; symbols of specified packages.
+
+;;;; This software is part of the SBCL software system. SBCL is in the
+;;;; public domain and is provided with absolutely no warranty. See
+;;;; the COPYING file for more information.
+
+;;;; Written by Rudi Schlatte <rudi@constantly.at>
+
-#+sbcl
(eval-when (:compile-toplevel :load-toplevel :execute)
(require 'sb-introspect))
(package "package")
(setf "setf-expander")
(structure "struct")
- (type (let ((class (find-class symbol)))
+ (type (let ((class (ignore-errors (find-class symbol))))
(etypecase class
(structure-class "struct")
(standard-class "class")
(ecase kind
(compiler-macro "@deffn {Compiler Macro}")
(function (cond
- ((macro-function symbol) "@defmac")
- ((special-operator-p symbol) "@defspec")
- (t "@defun")))
+ ((macro-function symbol) "@deffn Macro")
+ ((special-operator-p symbol) "@deffn {Special Operator}")
+ (t "@deffn Function")))
(method-combination "@deffn {Method Combination}")
- (package "@deffn Package")
+ (package "@defvr Package")
(setf "@deffn {Setf Expander}")
(structure "@deftp Structure")
- (type (let ((class (find-class symbol)))
+ (type (let ((class (ignore-errors (find-class symbol))))
(etypecase class
(structure-class "@deftp Structure")
(standard-class "@deftp Class")
((or built-in-class null) "@deftp Type"))))
(variable (if (constantp symbol)
"@defvr Constant"
- "@defvar"))))
+ "@defvr Variable"))))
+
+(defun def-index (symbol kind)
+ (case kind
+ ((compiler-macro function method-combination)
+ (format nil "@findex ~A" (texinfoify symbol)))
+ ((structure type)
+ (format nil "@tindex ~A" (texinfoify symbol)))
+ (variable
+ (format nil "@vindex ~A" (texinfoify symbol)))))
(defparameter *arglist-keywords*
'(&allow-other-keys &aux &body &environment &key &optional &rest &whole))
(list
(format s "(~{~A~^ ~})" (mapcar #'texinfoify-arglist-part part))))))
-(defun def-rest (symbol kind)
+(defun def-arglist (symbol kind)
(case kind
(function
(format nil "~{~A~^ ~}" (mapcar #'texinfoify-arglist-part
(argument-list symbol))))))
(defun def-end (symbol kind)
+ (declare (ignore symbol))
(ecase kind
- (compiler-macro "@end deffn")
- (function (cond
- ((macro-function symbol) "@end defmac")
- ((special-operator-p symbol) "@end defspec")
- (t "@end defun")))
- (method-combination "@end deffn")
- (package "@end deffn")
- (setf "@end deffn")
- (type "@end deftp")
- (variable (if (constantp symbol)
- "@end defvr"
- "@defvar"))))
+ ((compiler-macro function method-combination setf) "@end deffn")
+ ((package variable) "@end defvr")
+ ((structure type) "@end deftp"))
+ )
(defun make-info-file (package &optional filename)
"Create a file containing all available documentation for the
(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~%~%"
+ 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-rest symbol kind)
- docstring
+ (def-arglist symbol kind)
+ (def-index symbol kind)
+ (texinfoify docstring)
(def-end symbol kind))))
filename))
directory)
:direction :output
:if-does-not-exist :create :if-exists :supersede)
- (format out "~&@anchor{~A}~%~A ~A~@[ ~A~]~%~A~%~A~%~%"
+ (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-rest symbol kind)
- docstring
+ (def-arglist symbol kind)
+ (def-index symbol kind)
+ (texinfoify docstring)
(def-end symbol kind)))))
directory))
SBCL="${1:-`which sbcl`}"
fi
-# List of package names that documentation will be created for.
-PACKAGES=":SB-ALIEN :SB-EXT :SB-GRAY :SB-MOP :SB-PROFILE :SB-THREAD"
-
# Output directory. This has to end with a slash (it's interpreted by
-# Lisp's `pathname' function) or you lose.
+# Lisp's `pathname' function) or you lose. This is normally set from
+# Makefile.
DOCSTRINGDIR="${DOCSTRINGDIR:-docstrings/}"
+# List of package names that documentation will be created for. This
+# is normally set from Makefile.
+PACKAGES="${PACKAGES:-:COMMON-LISP :SB-ALIEN :SB-DEBUG :SB-EXT :SB-GRAY :SB-MOP :SB-PROFILE :SB-THREAD}"
echo /creating docstring snippets from SBCL=\'$SBCL\' for packages \'$PACKAGES\'
echo "(progn (load \"docstrings.lisp\") (docstrings-to-texinfo \"$DOCSTRINGDIR\" $PACKAGES) (sb-ext:quit))" | $SBCL --noinform --sysinit /dev/null --userinit /dev/null --noprint --disable-debugger
-@node Efficiency, Beyond The ANSI Standard, The Debugger, Top
+@node Efficiency
@comment node-name, next, previous, up
@chapter Efficiency
* Modular arithmetic::
@end menu
-@node Dynamic-extent allocation, Modular arithmetic, Efficiency, Efficiency
+@node Dynamic-extent allocation
@comment node-name, next, previous, up
@section Dynamic-extent allocation
@cindex Dynamic-extent declaration
@end itemize
-@node Modular arithmetic, , Dynamic-extent allocation, Efficiency
+@node Modular arithmetic
@comment node-name, next, previous, up
@section Modular arithmetic
@cindex Modular arithmetic
-@node The Foreign Function Interface, Function Index, Beyond The ANSI Standard, Top
+@node The Foreign Function Interface
@comment node-name, next, previous, up
@chapter The Foreign Function Interface
* Step-By-Step Example of the Foreign Function Interface::
@end menu
-@node Introduction to the Foreign Function Interface, Foreign Types, The Foreign Function Interface, The Foreign Function Interface
+@node Introduction to the Foreign Function Interface
@comment node-name, next, previous, up
@section Introduction to the Foreign Function Interface
@c AKA "Introduction to Aliens" in the CMU CL manual
The type language and operations on foreign types are
intentionally similar to those of the C language.
-@node Foreign Types, Operations On Foreign Values, Introduction to the Foreign Function Interface, The Foreign Function Interface
+@node Foreign Types
@comment node-name, next, previous, up
@section Foreign Types
@c AKA "Alien Types" in the CMU CL manual
* Foreign Type Specifiers::
@end menu
-@node Defining Foreign Types, Foreign Types and Lisp Types, Foreign Types, Foreign Types
+@node Defining Foreign Types
@comment node-name, next, previous, up
@subsection Defining Foreign Types
inherently named, but can be given named abbreviations using the
@code{define-alien-type} macro.
-@node Foreign Types and Lisp Types, Foreign Type Specifiers, Defining Foreign Types, Foreign Types
+@node Foreign Types and Lisp Types
@comment node-name, next, previous, up
@subsection Foreign Types and Lisp Types
is not automatically converted to a Lisp value, then it will return an
@code{alien} type specifier.
-@node Foreign Type Specifiers, , Foreign Types and Lisp Types, Foreign Types
+@node Foreign Type Specifiers
@comment node-name, next, previous, up
@subsection Foreign Type Specifiers
@end itemize
-@node Operations On Foreign Values, Foreign Variables, Foreign Types, The Foreign Function Interface
+@node Operations On Foreign Values
@comment node-name, next, previous, up
@section Operations On Foreign Values
@c AKA "Alien Operations" in the CMU CL manual
* Foreign Dynamic Allocation::
@end menu
-@node Accessing Foreign Values, Coercing Foreign Values, Operations On Foreign Values, Operations On Foreign Values
+@node Accessing Foreign Values
@comment node-name, next, previous, up
@subsection Accessing Foreign Values
@defun sb-alien:deref @var{pointer-or-array} &rest @var{indices}
+@findex deref
The @code{sb-alien:deref} function returns the value pointed to by a
foreign pointer, or the value of a foreign array element. When
number of indices must be the same as the number of dimensions in the
array type. @code{deref} can be set with @code{setf} to assign a new
value.
-
@end defun
@defun sb-alien:slot @var{struct-or-union} &rest @var{slot-names}
-
+@findex slot
+
The @code{sb-alien:slot} function extracts the value of the slot named
@var{slot-name} from a foreign @code{struct} or @code{union}. If
@var{struct-or-union} is a pointer to a structure or union, then it is
@acronym{SAP}s is trivial.
@defun sb-sys:int-sap @var{machine-address}
+@findex int-sap
Creates a @acronym{SAP} pointing at the virtual address
@var{machine-address}.
@end defun
@defun sb-sys:sap-ref-32 @var{sap} @var{offset}
+@findex sap-ref-32
Access the value of the memory location at @var{offset} bytes from
@var{sap}. This form may also be used with @code{setf} to alter the
@end defun
@defun sb-sys:sap= @var{sap1} @var{sap2}
+@findex sap=
Compare @var{sap1} and @var{sap2} for equality.
@end defun
@end lisp
-@node Coercing Foreign Values, Foreign Dynamic Allocation, Accessing Foreign Values, Operations On Foreign Values
+@node Coercing Foreign Values
@comment node-name, next, previous, up
@subsection Coercing Foreign Values
@defun sb-alien:addr @var{alien-expr}
-
+@findex addr
+
The @code{sb-alien:addr} macro returns a pointer to the location
specified by @var{alien-expr}, which must be either a foreign
variable, a use of @code{sb-alien:deref}, a use of
@end defun
@defun sb-alien:cast @var{foreign-value} @var{new-type}
-
+@findex cast
+
The @code{sb-alien:cast} macro converts @var{foreign-value} to a new
foreign value with the specified @var{new-type}. Both types, old and
new, must be foreign pointer, array or function types. Note that the
@end defun
@defun sb-alien:sap-alien @var{sap} @var{type}
-
+@findex sap-alien
+
The @code{sb-alien:sap-alien} function converts @var{sap} (a system
area pointer) to a foreign value with the specified
@var{type}. @var{type} is not evaluated. </para>
@end defun
@defun sb-alien:alien-sap @var{foreign-value} @var{type}
+@findex alien-sap
The @code{sb-alien:alien-sap} function returns the @acronym{SAP} which
points to @var{alien-value}'s data.
@end defun
-@node Foreign Dynamic Allocation, , Coercing Foreign Values, Operations On Foreign Values
+@node Foreign Dynamic Allocation
@comment node-name, next, previous, up
@subsection Foreign Dynamic Allocation
code.
@defmac sb-alien:make-alien @var{type} @var{size}
-
+@findex make-alien
+
The @code{sb-alien:make-alien} macro
returns a dynamically allocated foreign value of the specified
@var{type} (which is not evaluated.) The allocated memory is not
@end defmac
@defun sb-alien:free-alien @var{foreign-value}
+@findex free-alien
The @code{sb-alien:free-alien} function
frees the storage for @var{foreign-value},
values on the stack.
@end defun
-@node Foreign Variables, Foreign Data Structure Examples, Operations On Foreign Values, The Foreign Function Interface
+@node Foreign Variables
@comment node-name, next, previous, up
@section Foreign Variables
@c AKA "Alien Variables" in the CMU CL manual
* External Foreign Variables::
@end menu
-@node Local Foreign Variables, External Foreign Variables, Foreign Variables, Foreign Variables
+@node Local Foreign Variables
@comment node-name, next, previous, up
@subsection Local Foreign Variables
@defmac sb-alien:with-alien @var{var-definitions} &body @var{body}
+@findex with-alien
The @code{with-alien} macro establishes local foreign variables with
the specified alien types and names. This form is analogous to
using @code{(struct @var{foo})}.
@end defmac
-@node External Foreign Variables, , Local Foreign Variables, Foreign Variables
+@node External Foreign Variables
@comment node-name, next, previous, up
@subsection External Foreign Variables
@end itemize
@defmac sb-alien:define-alien-variable @var{name} @var{type}
+@findex define-alien-variable
The @code{define-alien-variable} macro defines @var{name} as an
external foreign variable of the specified foreign @code{type}.
@end defmac
@defun sb-alien:get-errno
+@findex get-errno
Since in modern C libraries, the @code{errno} ``variable'' is typically
no longer a variable, but some bizarre artificial construct
@end defun
@defmac sb-alien:extern-alien @var{name} @var{type}
+@findex extern-alien
The @code{extern-alien} macro returns an alien with the specified
@var{type} which points to an externally defined value. @var{name} is
an unevaluated alien type specifier.
@end defmac
-@node Foreign Data Structure Examples, Loading Unix Object Files, Foreign Variables, The Foreign Function Interface
+@node Foreign Data Structure Examples
@comment node-name, next, previous, up
@section Foreign Data Structure Examples
@c AKA "Alien Data Structure Example" in the CMU CL manual
(setq my-struct (slot my-struct 'n))
@end lisp
-@node Loading Unix Object Files, Foreign Function Calls, Foreign Data Structure Examples, The Foreign Function Interface
+@node Loading Unix Object Files
@comment node-name, next, previous, up
@section Loading Unix Object Files
@end quotation
-@node Foreign Function Calls, Step-By-Step Example of the Foreign Function Interface, Loading Unix Object Files, The Foreign Function Interface
+@node Foreign Function Calls
@comment node-name, next, previous, up
@section Foreign Function Calls
* Calling Lisp From C::
@end menu
-@node The alien-funcall Primitive, The define-alien-routine Macro, Foreign Function Calls, Foreign Function Calls
+@node The alien-funcall Primitive
@comment node-name, next, previous, up
@subsection The @code{alien-funcall} Primitive
@defun sb-alien:alien-funcall @var{alien-function} &rest @var{arguments}
+@findex alien-funcall
The @code{alien-funcall} function is the foreign function call
primitive: @var{alien-function} is called with the supplied
result)))
@end lisp
-@node The define-alien-routine Macro, define-alien-routine Example, The alien-funcall Primitive, Foreign Function Calls
+@node The define-alien-routine Macro
@comment node-name, next, previous, up
@subsection The @code{define-alien-routine} Macro
@defmac sb-alien:define-alien-routine @var{name} @var{result-type} &rest @var{arg-specifiers}
+@findex define-alien-routine
The @code{define-alien-routine} macro is a convenience for
automatically generating Lisp interfaces to simple foreign functions.
@end defmac
-@node define-alien-routine Example, Calling Lisp From C, The define-alien-routine Macro, Foreign Function Calls
+@node define-alien-routine Example
@comment node-name, next, previous, up
@subsection @code{define-alien-routine} Example
The Lisp function @code{cfoo} will have two arguments (@var{str} and
@var{a}) and two return values (@var{a} and @var{i}).
-@node Calling Lisp From C, , define-alien-routine Example, Foreign Function Calls
+@node Calling Lisp From C
@comment node-name, next, previous, up
@subsection Calling Lisp From C
@c -->
-@node Step-By-Step Example of the Foreign Function Interface, , Foreign Function Calls, The Foreign Function Interface
+@node Step-By-Step Example of the Foreign Function Interface
@comment node-name, next, previous, up
@section Step-By-Step Example of the Foreign Function Interface
-@node Introduction, The Compiler, Top, Top
+@node Introduction
@comment node-name, next, previous, up
@chapter Introduction
* Overview::
@end menu
-@node More Common Lisp Information, More SBCL Information, Introduction, Introduction
+@node More Common Lisp Information
@comment node-name, next, previous, up
@section Where To Go For More Information about Common Lisp in General
@end itemize
-@node More SBCL Information, Overview, More Common Lisp Information, Introduction
+@node More SBCL Information
@comment node-name, next, previous, up
@section Where To Go For More Information About SBCL
@end itemize
-@node Overview, , More SBCL Information, Introduction
+@node Overview
@comment node-name, next, previous, up
@section Overview Of SBCL, How It Works And Where It Came From
@set VERSION 0.8.9
@set UPDATED 2 April 2004
@set UPDATE-MONTH April 2004
-
+
+@c for install-info
+@dircategory Software development
+@direntry
+* sbcl: (sbcl). The Steel Bank Common Lisp compiler
+@end direntry
+
+
@copying
@ifnottex
-@node Top, Introduction, (dir), (dir)
+@node Top
@comment node-name, next, previous, up
-@top SBCL
+@top sbcl
@insertcopying
* Efficiency::
* Beyond The ANSI Standard::
* The Foreign Function Interface::
-* Function Index::
* Concept Index::
+* Function Index::
+* Variable Index::
* Colophon::
-
-@detailmenu
- --- The Detailed Node Listing ---
-
-Introduction
-
-* More Common Lisp Information::
-* More SBCL Information::
-* Overview::
-
-The Compiler
-
-* Error Messages::
-* Handling of Types::
-* Compiler Policy::
-* Open Coding and Inline Expansion::
-
-Error Messages
-
-* The Parts of the Error Message::
-* The Original and Actual Source::
-* Error Severity::
-* Errors During Macroexpansion::
-* Read Errors::
-
-The Compiler's Handling of Types
-
-* Implementation Limitations::
-* Type Errors at Compile Time::
-* Precise Type Checking::
-* Weakened Type Checking::
-* Getting Existing Programs to Run::
-
-The Debugger
-
-* Starting the Debugger::
-* The Debugger Command Loop::
-* Controlling Printing in the Debugger::
-* Stack Frames::
-* Variable Access::
-* Source Location Printing::
-* Debugger Policy Control::
-* Exiting Commands::
-* Information Commands::
-* Function Tracing::
-
-Stack Frames
-
-* Stack Motion::
-* How Arguments are Printed::
-* Function Names::
-* Funny Frames::
-* Debug Tail Recursion::
-* Unknown Locations and Interrupts::
-
-Variable Access
-
-* Variable Value Availability::
-* Note On Lexical Variable Access::
-
-Source Location Printing
-
-* How the Source is Found::
-* Source Location Availability::
-
-Efficiency
-
-* Dynamic-extent allocation::
-* Modular arithmetic::
-
-Beyond The ANSI Standard
-
-* Non-Conformance With The ANSI Standard::
-* Idiosyncrasies::
-* Extensions::
-
-Extensions
-
-* Things Which Might Be In The Next ANSI Standard::
-* Threading::
-* Support For Unix::
-* Customization Hooks for Users::
-* Tools To Help Developers::
-* Interface To Low-Level SBCL Implementation::
-* Efficiency Hacks::
-
-The Foreign Function Interface
-
-* Introduction to the Foreign Function Interface::
-* Foreign Types::
-* Operations On Foreign Values::
-* Foreign Variables::
-* Foreign Data Structure Examples::
-* Loading Unix Object Files::
-* Foreign Function Calls::
-* Step-By-Step Example of the Foreign Function Interface::
-
-Foreign Types
-
-* Defining Foreign Types::
-* Foreign Types and Lisp Types::
-* Foreign Type Specifiers::
-
-Operations On Foreign Values
-
-* Accessing Foreign Values::
-* Coercing Foreign Values::
-* Foreign Dynamic Allocation::
-
-Foreign Variables
-
-* Local Foreign Variables::
-* External Foreign Variables::
-
-Foreign Function Calls
-
-* The alien-funcall Primitive::
-* The define-alien-routine Macro::
-* define-alien-routine Example::
-* Calling Lisp From C::
-
-@end detailmenu
@end menu
@end ifnottex
;;; 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.9.31"
+"0.8.9.32"
projects / sbcl.git / commitdiff