compilation of modular arithmetic (@pxref{Modular arithmetic}), which
enabled the implementation to be expressed in portable arithmetical
terms, apart from the use of @code{rotate-byte} for bitwise rotation.
-@findex rotate-byte
+@findex @sbrotatebyte{rotate-byte}
:sb-sprof :sb-bsd-sockets :sb-cover :sb-posix'
# 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-PCL :SB-SYS \
:SB-PROFILE :SB-THREAD :SB-MD5 :SB-QUEUE :SB-ROTATE-BYTE \
:SB-SPROF :SB-BSD-SOCKETS :SB-COVER :SB-POSIX :SB-CONCURRENCY"
@itemize
@item
-@findex compute-effective-method
-@findex sb-mop:compute-effective-method
+@findex @sbmop{compute-effective-method}
@code{compute-effective-method} only returns one value, not two.
There is no record of what the second return value was meant to
indicate, and apparently no clients for it.
@item
-@tindex generic-function
-@tindex standard-generic-function
-@tindex funcallable-standard-object
-@tindex sb-mop:funcallable-standard-object
-@tindex standard-object
-@tindex function
+@tindex @cl{generic-function}
+@tindex @cl{standard-generic-function}
+@tindex @sbmop{funcallable-standard-object}
+@tindex @cl{standard-object}
+@tindex @cl{function}
The direct superclasses of @code{sb-mop:funcallable-standard-object} are
@code{(function standard-object)}, not @code{(standard-object function)}.
ANSI specification.
@item
-@findex ensure-generic-function
-@findex generic-function-declarations
-@findex sb-mop:generic-function-declarations
+@findex @cl{ensure-generic-function}
+@findex @sbmop{generic-function-declarations}
the arguments @code{:declare} and @code{:declarations} to
@code{ensure-generic-function} are both accepted, with the leftmost
argument defining the declarations to be stored and returned by
@code{:declare}. Portable code should use @code{:declare}.
@item
-@findex validate-superclass
-@findex finalize-inheritance
-@findex sb-mop:validate-superclass
-@findex sb-mop:finalize-inheritance
-@tindex standard-class
-@tindex funcallable-standard-class
-@tindex sb-mop:funcallable-standard-class
-@tindex function
-@findex sb-mop:class-prototype
-@findex class-prototype
+@findex @sbmop{validate-superclass}
+@findex @sbmop{finalize-inheritance}
+@tindex @cl{standard-class}
+@tindex @sbmop{funcallable-standard-class}
+@tindex @cl{function}
+@findex @sbmop{class-prototype}
although SBCL obeys the requirement in AMOP that
@code{validate-superclass} should treat @code{standard-class} and
@code{funcallable-standard-class} as compatible metaclasses, we
@code{function} in its superclasses, and a class of metaclass
@code{standard-class} must not.
-@findex typep
-@findex class-of
-@findex subtypep
+@findex @cl{typep}
+@findex @cl{class-of}
+@findex @cl{subtypep}
After a class has been finalized, it is associated with a class
prototype which is accessible by a standard mop function
@code{sb-mop:class-prototype}. The user can then ask whether this
@end lisp
and leads to a class whose instances are funcallable and have one slot.
-@tindex funcallable-standard-object
-@tindex sb-mop:funcallable-standard-object
+@tindex @sbmop{funcallable-standard-object}
Note that this requirement also applies to the class
@code{sb-mop:funcallable-standard-object}, which has metaclass
@code{sb-mop:funcallable-standard-class} rather than
of software from colliding with each other.
@item
-@findex slot-value-using-class
-@findex sb-mop:slot-value-using-class
-@findex (setf slot-value-using-class)
-@findex (setf sb-mop:slot-value-using-class)
-@findex slot-boundp-using-class
-@findex sb-mop:slot-boundp-using-class
+@findex @sbmop{slot-value-using-class}
+@findex @setf{@sbmop{slot-value-using-class}}
+@findex @sbmop{slot-boundp-using-class}
specializations of the @code{new-value} argument to @code{(setf
sb-mop:slot-value-using-class)} are not allowed: all user-defined
methods must have a specializer of the class @code{t}.
argument of slot accessors.
@item
-@findex defclass
-@findex ensure-class
-@findex ensure-class-using-class
-@findex sb-mop:ensure-class
-@findex sb-mop:ensure-class-using-class
-@findex find-class
-@findex class-name
+@findex @cl{defclass}
+@findex @sbmop{ensure-class}
+@findex @sbmop{ensure-class-using-class}
+@findex @cl{find-class}
+@findex @cl{class-name}
the class named by the @code{name} argument to @code{ensure-class}, if
any, is only redefined if it is the proper name of that class;
otherwise, a new class is created.
@itemize
@item
-@findex defmethod
-@findex find-class
-@findex intern-eql-specializer
-@findex sb-mop:intern-eql-specializer
-@findex make-method-specializers-form
-@findex sb-pcl:make-method-specializers-form
-@findex make-method-lambda
-@findex sb-mop:make-method-lambda
+@findex @cl{defmethod}
+@findex @cl{find-class}
+@findex @sbmop{intern-eql-specializer}
+@findex @sbpcl{make-method-specializers-form}
+@findex @sbmop{make-method-lambda}
compile-time support for generating specializer metaobjects from
specializer names in @code{defmethod} forms is provided by the
@code{make-method-specializers-form} function, which returns a form
@var{x})} specializer name.
@item
-@findex find-method
-@findex parse-specializer-using-class
-@findex unparse-specializer-using-class
-@findex sb-pcl:parse-specializer-using-class
-@findex sb-pcl:unparse-specializer-using-class
+@findex @cl{find-method}
+@findex @sbpcl{parse-specializer-using-class}
+@findex @sbpcl{unparse-specializer-using-class}
run-time support for converting between specializer names and
specializer metaobjects, mostly for the purposes of
@code{find-method}, is provided by
@node Command-line arguments
@subsection Command-line arguments
-@vindex sb-ext:*posix-argv*
-@vindex *posix-argv*
+@vindex @sbext{@earmuffs{posix-argv}}
The UNIX command line can be read from the variable
@code{sb-ext:*posix-argv*}.
@node Tools To Help Developers
@comment node-name, next, previous, up
@section Tools To Help Developers
-@findex trace
-@findex inspect
+@findex @cl{trace}
+@findex @cl{inspect}
SBCL provides a profiler and other extensions to the ANSI @code{trace}
facility. For more information, see @ref{Macro common-lisp:trace}.
@node Resolution of Name Conflicts
@section Resolution of Name Conflicts
-@tindex sb-ext:name-conflict
-@tindex name-conflict
-@findex sb-ext:name-conflict-symbols
-@findex name-conflict-symbols
+@tindex @sbext{name-conflict}
+@findex @sbext{name-conflict-symbols}
The ANSI standard (section 11.1.1.2.5) requires that name conflicts in
packages be resolvable in favour of any of the conflicting symbols. In
(* x -5))))
@end lisp
-@deffn {Declaration} sb-ext:muffle-conditions
+@deffn {Declaration} @sbext{muffle-conditions}
Syntax: type*
Muffles the diagnostic messages that would be caused by compile-time
signals of given types.
@end deffn
-@deffn {Declaration} sb-ext:unmuffle-conditions
+@deffn {Declaration} @sbext{unmuffle-conditions}
Syntax: type*
-Cancels the effect of a previous @code{sb-ext:muffle-condition}
+Cancels the effect of a previous @code{sb-ext:muffle-conditions}
declaration.
@end deffn
@subsection Diagnostic Severity
@cindex Severity of compiler messages
@cindex Compiler Diagnostic Severity
-@tindex error
-@tindex warning
-@tindex style-warning
-@tindex compiler-note
-@tindex code-deletion-note
+@tindex @cl{error}
+@tindex @cl{warning}
+@tindex @cl{style-warning}
+@tindex @sbext{compiler-note}
+@tindex @sbext{code-deletion-note}
There are four levels of compiler diagnostic severity:
@enumerate
@item
-@findex with-compilation-unit
+@findex @cl{with-compilation-unit}
@samp{file: /tmp/foo.lisp} This is the name of the file that the
compiler read the relevant code from. The file name is displayed
because it may not be immediately obvious when there is an error
of appropriate type declarations can be very important for performance
as well.
-@findex satisfies
+@findex @cl{satisfies}
The SBCL compiler also has a greater knowledge of the Common Lisp
type system than other compilers. Support is incomplete only for types
involving the @code{satisfies} type specifier.
@node Declarations as Assertions
@comment node-name, next, previous, up
@subsection Declarations as Assertions
-@findex safety
+@cindex Safety optimization quality
The SBCL compiler treats type declarations differently from most other
Lisp compilers. Under default compilation policy the compiler doesn't
@comment node-name, next, previous, up
@section Interpreter
@cindex Interpreter
-@vindex sb-ext:*evaluator-mode*
+@vindex @sbext{@earmuffs{evaluator-mode}}
By default SBCL implements @code{eval} by calling the native code
compiler. SBCL also includes an interpreter for use in special cases
* Information Commands::
* Function Tracing::
* Single Stepping::
+* Enabling and Disabling the Debugger::
@end menu
@node Debugger Entry
function and the values of its arguments in the style of a Lisp
function call:
-@deffn {Debugger Command} up
+@deffn {Debugger Command} @nopkg{up}
Move up to the next higher frame. More recent function calls are
considered to be higher on the stack.
@end deffn
-@deffn {Debugger Command} down
+@deffn {Debugger Command} @nopkg{down}
Move down to the next lower frame.
@end deffn
-@deffn {Debugger Command} top
+@deffn {Debugger Command} @nopkg{top}
Move to the highest frame, that is, the frame where the debugger was
entered.
@end deffn
-@deffn {Debugger Command} bottom
+@deffn {Debugger Command} @nopkg{bottom}
Move to the lowest frame.
@end deffn
-@deffn {Debugger Command} frame [@var{n}]
+@deffn {Debugger Command} @nopkg{frame} [@var{n}]
Move to the frame with the specified number. Prompts for the number if not
supplied. The frame with number 0 is the frame where the debugger
was entered.
X#1 = 2
@end example
-@deffn {Debugger Command} list-locals [@var{prefix}]
+@deffn {Debugger Command} @nopkg{list-locals} [@var{prefix}]
This command prints the name and value of all variables in the current
frame whose name has the specified @var{prefix}. @var{prefix} may be
a string or a symbol. If no @var{prefix} is given, then all available
name unique.
@end deffn
-@defun sb-debug:var @var{name} &optional @var{identifier}
+@defun @sbdebug{var} @var{name} &optional @var{identifier}
This function returns the value of the variable in the current frame
with the specified @var{name}. If supplied, @var{identifier}
determines which value to return when there are ambiguous variables.
compiled code. These commands display the source location for the
current frame:
-@deffn {Debugger Command} source [@var{context}]
+@deffn {Debugger Command} @nopkg{source} [@var{context}]
This command displays the file that the current frame's function was
defined from (if it was defined from a file), and then the source form
responsible for generating the code that the current frame was
These commands get you out of the debugger.
-@deffn {Debugger Command} toplevel
+@deffn {Debugger Command} @nopkg{toplevel}
Throw to top level.
@end deffn
-@deffn {Debugger Command} restart [@var{n}]
+@deffn {Debugger Command} @nopkg{restart} [@var{n}]
Invokes the @var{n}th restart case as displayed by the @code{error}
command. If @var{n} is not specified, the available restart cases are
reported.
@end deffn
-@deffn {Debugger Command} continue
+@deffn {Debugger Command} @nopkg{continue}
Calls @code{continue} on the condition given to @code{debug}. If there is no
restart case named @var{continue}, then an error is signaled.
@end deffn
-@deffn {Debugger Command} abort
+@deffn {Debugger Command} @nopkg{abort}
Calls @code{abort} on the condition given to @code{debug}. This is
useful for popping debug command loop levels or aborting to top level,
as the case may be.
@end deffn
-@deffn {Debugger Command} return @var{value}
+@deffn {Debugger Command} @nopkg{return} @var{value}
Returns @var{value} from the current stack frame. This command is
available when the @code{debug} optimization quality is greater than
both @code{speed} and @code{space}. Care must be taken that the value
is of the same type as SBCL expects the stack frame to return.
@end deffn
-@deffn {Debugger Command} restart-frame
+@deffn {Debugger Command} @nopkg{restart-frame}
Restarts execution of the current stack frame. This command is
available when the @code{debug} optimization quality is greater than
both @code{speed} and @code{space} and when the frame is for is a global
Most of these commands print information about the current frame or
function, but a few show general information.
-@deffn {Debugger Command} help
-@deffnx {Debugger Command} ?
+@deffn {Debugger Command} @nopkg{help}
+@deffnx {Debugger Command} @nopkg{?}
Displays a synopsis of debugger commands.
@end deffn
-@deffn {Debugger Command} describe
+@deffn {Debugger Command} @nopkg{describe}
Calls @code{describe} on the current function and displays the number of
local variables.
@end deffn
-@deffn {Debugger Command} print
+@deffn {Debugger Command} @nopkg{print}
Displays the current function call as it would be displayed by moving to
this frame.
@end deffn
-@deffn {Debugger Command} error
+@deffn {Debugger Command} @nopkg{error}
Prints the condition given to @code{invoke-debugger} and the active
proceed cases.
@end deffn
-@deffn {Debugger Command} backtrace [@var{n}]
+@deffn {Debugger Command} @nopkg{backtrace} [@var{n}]
Displays all the frames from the current to the bottom. Only shows
@var{n} frames if specified. The printing is controlled by
@code{*debug-print-variable-alist*}.
The following debugger commands are used for controlling single stepping.
-@deffn {Debugger Command} start
+@deffn {Debugger Command} @nopkg{start}
Selects the @code{continue} restart if one exists and starts single stepping.
None of the other single stepping commands can be used before stepping has
been started either by using @code{start} or by using the standard
@code{step} macro.
@end deffn
-@deffn {Debugger Command} step
+@deffn {Debugger Command} @nopkg{step}
Steps into the current form. Stepping will be resumed when the next
form that has been compiled with stepper instrumentation is evaluated.
@end deffn
-@deffn {Debugger Command} next
+@deffn {Debugger Command} @nopkg{next}
Steps over the current form. Stepping will be disabled until evaluation of
the form is complete.
@end deffn
-@deffn {Debugger Command} out
+@deffn {Debugger Command} @nopkg{out}
Steps out of the current frame. Stepping will be disabled until the
topmost stack frame that had been stepped into returns.
@end deffn
-@deffn {Debugger Command} stop
+@deffn {Debugger Command} @nopkg{stop}
Stops the single stepper and resumes normal execution.
@end deffn
@include macro-common-lisp-step.texinfo
+
+@node Enabling and Disabling the Debugger
+@comment node-name, next, previous, up
+@section Enabling and Disabling the Debugger
+
+@cindex debugger, enabling
+@cindex debugger, disabling
+@cindex disabling debugger
+@cindex ldb, enabling
+@cindex ldb, disabling
+@cindex disabling ldb
+
+In certain contexts (e.g., non-interactive applications), it may be
+desirable to turn off the SBCL debugger (and possibly re-enable it).
+The functions here control the debugger.
+
+@include fun-sb-ext-disable-debugger.texinfo
+
+@include fun-sb-ext-enable-debugger.texinfo
(let ((kind (get-kind doc)))
(format nil "~:(~A~) ~(~A~)" kind (name-using-kind/name kind (get-name doc) doc))))
-(defun short-package-name (package)
- (car (sort (copy-list (cons (package-name package) (package-nicknames package)))
- #'< :key #'length)))
+(defun package-shortest-name (package)
+ (let* ((names (cons (package-name package) (package-nicknames package)))
+ (sorted (sort (copy-list names) #'< :key #'length)))
+ (car sorted)))
+
+(defun package-macro-name (package)
+ (let ((short-name (package-shortest-name package)))
+ (remove-if-not #'alpha-char-p (string-downcase short-name))))
;;; Definition titles for DOCUMENTATION instances
(defmethod title-using-kind/name (kind (name symbol) doc)
(declare (ignore kind))
- (format nil "~A:~A" (short-package-name (get-package doc)) name))
+ (let* ((symbol-name (symbol-name name))
+ (earmuffsp (and (char= (char symbol-name 0) #\*)
+ (char= (char symbol-name (1- (length symbol-name))) #\*)
+ (some #'alpha-char-p symbol-name))))
+ (if earmuffsp
+ (format nil "@~A{@earmuffs{~A}}" (package-macro-name (get-package doc)) (subseq symbol-name 1 (1- (length symbol-name))))
+ (format nil "@~A{~A}" (package-macro-name (get-package doc)) name))))
(defmethod title-using-kind/name (kind (name list) doc)
(declare (ignore kind))
(assert (setf-name-p name))
- (format nil "(setf ~A:~A)" (short-package-name (get-package doc)) (second name)))
+ (format nil "@setf{@~A{~A}}" (package-macro-name (get-package doc)) (second name)))
(defmethod title-using-kind/name ((kind (eql 'method)) name doc)
(format nil "~{~A ~}~A"
name))
(lambda-list doc)))))
-(defun texinfo-index (doc)
- (let ((title (title-name doc)))
- (case (get-kind doc)
- ((structure type class condition)
- (format *texinfo-output* "@tindex ~A~%" title))
- ((variable constant)
- (format *texinfo-output* "@vindex ~A~%" title))
- ((compiler-macro function method-combination macro generic-function)
- (format *texinfo-output* "@findex ~A~%" title)))))
-
(defun texinfo-inferred-body (doc)
(when (member (get-kind doc) '(class structure condition))
(let ((name (get-name doc)))
"Writes TexInfo for a DOCUMENTATION instance to *TEXINFO-OUTPUT*."
(texinfo-anchor doc)
(texinfo-begin doc)
- (texinfo-index doc)
(texinfo-inferred-body doc)
(texinfo-body doc)
(texinfo-end doc)
:if-exists :supersede)
,@forms))
+(defun write-package-macro (package)
+ (let* ((package-name (package-shortest-name package))
+ (macro-name (package-macro-name package)))
+ (write-packageish-macro package-name macro-name)))
+
+(defun write-packageish-macro (package-name macro-name)
+ ;; a word of explanation about the iftex branch here is probably
+ ;; warranted. The package information should be present for
+ ;; clarity, because these produce body text as well as index
+ ;; entries (though in info output it's more important to use a
+ ;; very restricted character set because the info reader parses
+ ;; the link, and colon is a special character). In TeX output we
+ ;; make the package name unconditionally small, and arrange such
+ ;; that the start of the symbol name is at a constant horizontal
+ ;; offset, that offset being such that the longest package names
+ ;; have the "sb-" extending into the left margin. (At the moment,
+ ;; the length of the longest package name, sb-concurrency, is
+ ;; hard-coded).
+ (format *texinfo-output* "~
+@iftex
+@macro ~A{name}
+{@smallertt@phantom{concurrency:}~@[@llap{~(~A~):}~]}\\name\\
+@end macro
+@end iftex
+@ifinfo
+@macro ~2:*~A{name}
+\\name\\
+@end macro
+@end ifinfo
+@ifnottex
+@ifnotinfo
+@macro ~:*~A{name}
+\\name\\ ~@[[~(~A~)]~]
+@end macro
+@end ifnotinfo
+@end ifnottex~%"
+ macro-name package-name))
+
(defun generate-includes (directory &rest packages)
"Create files in `directory' containing Texinfo markup of all
docstrings of each exported symbol in `packages'. `directory' is
(dolist (doc (collect-documentation (find-package package)))
(with-texinfo-file (merge-pathnames (include-pathname doc) directory)
(write-texinfo doc))))
+ (with-texinfo-file (merge-pathnames "package-macros.texinfo" directory)
+ (dolist (package packages)
+ (write-package-macro package))
+ (write-packageish-macro nil "nopkg"))
directory)))
(defun document-package (package &optional filename)
@node Dynamic-extent allocation
@comment node-name, next, previous, up
@section Dynamic-extent allocation
-@cindex Dynamic-extent declaration
+@cindex @code{dynamic-extent} declaration
+@cindex declaration, @code{dynamic-extent}
SBCL has limited support for performing allocation on the stack when a
variable is declared @code{dynamic-extent}. The @code{dynamic-extent}
@code{&rest} lists, when these are declared @code{dynamic-extent}.
@item
+@findex @cl{cons}
+@findex @cl{list}
+@findex @cl{list*}
+@findex @cl{vector}
@code{cons}, @code{list}, @code{list*}, and @code{vector} when the
result is bound to a variable declared @code{dynamic-extent}.
@item
+@findex @cl{make-array}
simple forms of @code{make-array}, whose result is bound to a variable
declared @code{dynamic-extent}: stack allocation is possible only if
the resulting array is known to be both simple and one-dimensional,
and has a constant @code{:element-type}.
+@cindex Safety optimization quality
@strong{Note}: stack space is limited, so allocation of a large vector
may cause stack overflow. For this reason potentially large vectors,
which might circumvent stack overflow detection, are stack allocated
only in zero @code{safety} policies.
@item
+@findex @cl{flet}
+@findex @cl{labels}
+@cindex @code{safety} optimization quality
+@cindex optimization quality, @code{safety}
closures defined with @code{flet} or @code{labels}, with a bound
@code{dynamic-extent} declaration. Closed-over variables, which are
assigned to (either inside or outside the closure) are still allocated
@cindex Modular arithmetic
@cindex Arithmetic, modular
@cindex Arithmetic, hardware
-
+@findex @cl{logand}
Some numeric functions have a property: @var{N} lower bits of the
result depend only on @var{N} lower bits of (all or some)
arguments. If the compiler sees an expression of form @code{(logand
@include macro-sb-ext-defglobal.texinfo
-@deftp {Declaration} sb-ext:global
+@deffn {Declaration} @sbext{global}
Syntax: @code{(sb-ext:global symbol*)}
variable name as @code{global} signal an error. Allows more efficient
value lookup in threaded environments in addition to expressing
programmer intention.
-@end deftp
+@end deffn
-@deftp {Declaration} sb-ext:always-bound
+@deffn {Declaration} @sbext{always-bound}
Syntax: @code{(sb-ext:always-bound symbol*)}
Specifies that the named symbols is always bound. Inhibits @code{makunbound}
of the named symbols. Proclaiming an unbound symbol as @code{always-bound} signals
an error. Allows compiler to elide boundness checks from value lookups.
-@end deftp
+@end deffn
@node Miscellaneous Efficiency Issues
@comment node-name, next, previous, up
@itemize
@item
+@findex @cl{let}
+@findex @cl{let*}
+@findex @cl{setq}
+@findex @cl{setf}
The CMUCL manual doesn't seem to state it explicitly, but Python has a
mental block about type inference when assignment is involved. Python
is very aggressive and clever about inferring the types of values
@comment node-name, next, previous, up
@subsection Accessing Foreign Values
-@defun sb-alien:deref @var{pointer-or-array} &rest @var{indices}
-@findex deref
+@defun @sbalien{deref} @var{pointer-or-array} &rest @var{indices}
The @code{sb-alien:deref} function returns the value pointed to by a
foreign pointer, or the value of a foreign array element. When
value.
@end defun
-@defun sb-alien:slot @var{struct-or-union} @var{slot-name}
-@findex slot
+@defun @sbalien{slot} @var{struct-or-union} @var{slot-name}
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
used with caution; corrupting the Lisp heap or other memory with
@acronym{SAP}s is trivial.
-@defun sb-sys:int-sap @var{machine-address}
-@findex int-sap
+@defun @sbsys{int-sap} @var{machine-address}
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
+@defun @sbsys{sap-ref-32} @var{sap} @var{offset}
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
memory at that location.
@end defun
-@defun sb-sys:sap= @var{sap1} @var{sap2}
-@findex sap=
+@defun @sbsys{sap=} @var{sap1} @var{sap2}
Compare @var{sap1} and @var{sap2} for equality.
@end defun
@comment node-name, next, previous, up
@subsection Coercing Foreign Values
-@defun sb-alien:addr @var{alien-expr}
-@findex addr
+@defmac @sbalien{addr} @var{alien-expr}
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
@code{sb-alien:slot}, or a use of @code{sb-alien:extern-alien}.
-@end defun
+@end defmac
-@defun sb-alien:cast @var{foreign-value} @var{new-type}
-@findex cast
+@defmac @sbalien{cast} @var{foreign-value} @var{new-type}
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
resulting Lisp foreign variable object is not @code{eq} to the
argument, but it does refer to the same foreign data bits.
-@end defun
+@end defmac
-@defun sb-alien:sap-alien @var{sap} @var{type}
-@findex sap-alien
+@defmac @sbalien{sap-alien} @var{sap} @var{type}
-The @code{sb-alien:sap-alien} function converts @var{sap} (a system
+The @code{sb-alien:sap-alien} macro converts @var{sap} (a system
area pointer) to a foreign value with the specified
@var{type}. @var{type} is not evaluated.
The @var{type} must be some foreign pointer, array, or record type.
-@end defun
+@end defmac
-@defun sb-alien:alien-sap @var{foreign-value}
-@findex alien-sap
+@defun @sbalien{alien-sap} @var{foreign-value}
The @code{sb-alien:alien-sap} function returns the @acronym{SAP} which
points to @var{alien-value}'s data.
@code{sb-alien:free-alien} on foreign objects allocated by C
code.
-@defmac sb-alien:make-alien @var{type} @var{size}
-@findex make-alien
+@defmac @sbalien{make-alien} @var{type} @var{size}
The @code{sb-alien:make-alien} macro
returns a dynamically allocated foreign value of the specified
@end defmac
-@defun sb-alien:free-alien @var{foreign-value}
-@findex free-alien
+@defun @sbalien{free-alien} @var{foreign-value}
-The @code{sb-alien:free-alien} function
+The @code{sb-alien:free-alien} macro
frees the storage for @var{foreign-value},
which must have been allocated with Lisp @code{make-alien}
or C @code{malloc}.
@comment node-name, next, previous, up
@subsection Local Foreign Variables
-@defmac sb-alien:with-alien @var{var-definitions} &body @var{body}
-@findex with-alien
+@defmac @sbalien{with-alien} @var{var-definitions} &body @var{body}
The @code{with-alien} macro establishes local foreign variables with
the specified alien types and names. This form is analogous to
@end itemize
-@defmac sb-alien:define-alien-variable @var{name} @var{type}
-@findex define-alien-variable
+@defmac @sbalien{define-alien-variable} @var{name} @var{type}
The @code{define-alien-variable} macro defines @var{name} as an
external foreign variable of the specified foreign @code{type}.
@end lisp
@end defmac
-@defun sb-alien:get-errno
-@findex get-errno
+@defun @sbalien{get-errno}
Since in modern C libraries, the @code{errno} ``variable'' is typically
no longer a variable, but some bizarre artificial construct
the operator @code{sb-alien:get-errno} to allow Lisp code to read it.
@end defun
-@defmac sb-alien:extern-alien @var{name} @var{type}
-@findex extern-alien
+@defmac @sbalien{extern-alien} @var{name} @var{type}
The @code{extern-alien} macro returns an alien with the specified
@var{type} which points to an externally defined value. @var{name} is
@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
+@defun @sbalien{alien-funcall} @var{alien-function} &rest @var{arguments}
The @code{alien-funcall} function is the foreign function call
primitive: @var{alien-function} is called with the supplied
@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
+@defmac @sbalien{define-alien-routine} @var{name} @var{result-type} &rest @var{arg-specifiers}
The @code{define-alien-routine} macro is a convenience for
automatically generating Lisp interfaces to simple foreign functions.
@node Defining Constants
@comment node-name, next, previous, up
@subsection Defining Constants
-@findex defconstant
+@findex @cl{defconstant}
SBCL is quite strict about ANSI's definition of @code{defconstant}.
ANSI says that doing @code{defconstant} of the same symbol more than
@node Implementation Packages
@subsection Implementation Packages
-@vindex *package*
-@findex defpackage
+@vindex @cl{@earmuffs{package}}
+@findex @cl{defpackage}
Each package has a list of associated implementation packages. A
locked package, and the symbols whose home package it is, can be
@node Package Lock Violations
@subsection Package Lock Violations
-@tindex sb-ext:package-lock-violation
-@tindex sb-ext:package-locked-error
-@tindex sb-ext:symbol-package-locked-error
-@tindex package-lock-violation
-@tindex package-locked-error
-@tindex symbol-package-locked-error
-@tindex package-error
+@tindex @sbext{package-lock-violation}
+@tindex @sbext{package-locked-error}
+@tindex @sbext{symbol-package-locked-error}
+@tindex @cl{package-error}
@subsubsection Lexical Bindings and Declarations
-@findex let
-@findex let*
-@findex flet
-@findex labels
-@findex macrolet
-@findex symbol-macrolet
-@findex declare
+@findex @cl{let}
+@findex @cl{let*}
+@findex @cl{flet}
+@findex @cl{labels}
+@findex @cl{macrolet}
+@findex @cl{symbol-macrolet}
+@findex @cl{declare}
@cindex Declarations
-@findex sb-ext:disable-package-locks
-@findex sb-ext:enable-package-locks
-@findex disable-package-locks
-@findex enable-package-locks
+@findex @sbext{disable-package-locks}
+@findex @sbext{enable-package-locks}
Lexical bindings or declarations that violate package locks cause
result in a @code{program-error} being signalled at when the form that
@node Package Lock Dictionary
@section Package Lock Dictionary
-@deftp {Declaration} sb-ext:disable-package-locks
+@deffn {Declaration} @sbext{disable-package-locks}
Syntax: @code{(sb-ext:disable-package-locks symbol*)}
in the lexical scope of the declaration. Disabling locks on symbols
whose home package is unlocked, or disabling an already disabled lock,
has no effect.
-@end deftp
+@end deffn
-@deftp {Declaration} sb-ext:enable-package-locks
+@deffn {Declaration} @sbext{enable-package-locks}
Syntax: @code{(sb-ext:enable-package-locks symbol*)}
in the lexical scope of the declaration. Enabling locks that were not
first disabled with @code{sb-ext:disable-package-locks} declaration, or
enabling locks that are already enabled has no effect.
-@end deftp
+@end deffn
@include condition-sb-ext-package-lock-violation.texinfo
@include condition-sb-ext-package-locked-error.texinfo
@include condition-sb-ext-symbol-package-locked-error.texinfo
-@defun sb-ext:package-locked-error-symbol symbol-package-locked-error
+@defun @sbext{package-locked-error-symbol} symbol-package-locked-error
Returns the symbol that caused the @code{symbol-package-locked-error}
condition.
@include macro-sb-ext-without-package-locks.texinfo
@include macro-sb-ext-with-unlocked-packages.texinfo
-@defmac defpackage name [[option]]* @result{} package
+@defmac @cl{defpackage} name [[option]]* @result{} package
Options are extended to include the following:
@cindex Logical pathnames
@cindex Pathnames, logical
-@findex logical-pathname-translations
-@findex (setf logical-pathname-translations)
+@findex @cl{logical-pathname-translations}
+@findex @setf{@cl{logical-pathname-translations}}
@c * The existence and meaning of SYS: logical pathnames is
@c implementation-defined. (19.3.1.1.1)
@setfilename sbcl.info
@settitle SBCL User Manual
@c %**end of header
-
+@afourwide
@include texinfo-macros.texinfo
@include variables.texinfo
@set EDITION 0.1
@node Shebang Scripts
@comment node-name, next, previous, up
@subsection Shebang Scripts
-@vindex sb-ext:*posix-argv*
-@vindex *posix-argv*
+@vindex @sbext{@earmuffs{posix-argv}}
Standard Unix tools that are interpreters follow a common command line
protocol that is necessary to work with ``shebang scripts''. SBCL supports
@code{--disable-debugger} options.
@item --disable-ldb
+@cindex ldb
+@cindex ldb, disabling
+@cindex disabling ldb
Disable the low-level debugger. Only effective if SBCL is compiled
with LDB.
@item --lose-on-corruption
+@cindex ldb
There are some dangerous low level errors (for instance, control stack
exhausted, memory fault) that (or whose handlers) can corrupt the
image. By default SBCL prints a warning, then tries to continue and
malfunction or even hang. With this option, upon encountering such an
error SBCL will invoke ldb (if present and enabled) or else exit.
+
@item --script @var{filename}
As a runtime option this is equivalent to @code{--noinform}
@code{--disable-ldb} @code{--lose-on-corruption}
@section External Formats
@cindex External formats
-@findex stream-external-format
+@findex @cl{stream-external-format}
The encodings supported by SBCL as external formats are named by
keyword. Each encoding has a canonical name, which will be encoding
returned by @code{stream-external-format}, and a number of aliases for
@include encodings.texi-temp
-@findex open
-@findex with-open-file
+@findex @cl{open}
+@findex @cl{with-open-file}
In situations where an external file format designator is required, such
as the @code{:external-format} argument in calls to @code{open} or
@code{with-open-file}, users may supply the name of an encoding to
feel free to ask for advice on the sbcl-help list.
@table @strong
-@item Christophe Rhodes
-is a long-time SBCL developer, available for custom programming.
-
-Email: @email{csr21@@cam.ac.uk}
-
@item Steel Bank Studio Ltd
provides commercial SBCL support and custom development, is run by
SBCL developer @emph{Nikodemus Siivola}, and has another SBCL
Website: @url{http://sb-studio.net/}
Email: @email{info@@sb-studio.net}
+
+@item Christophe Rhodes
+is a researcher and long-time SBCL developer, available for custom
+development, particularly in the area of language extension.
+
+Email: @email{c.rhodes@@gold.ac.uk}
+
@end table
@node Reporting Bugs
@enumerate
@item
+@cindex ldb
Compile sbcl with ldb support (feature @code{:sb-ldb}, see
@file{base-target-features.lisp-expr}) and change @code{#define QSHOW_SIGNAL 0} to
@code{#define QSHOW_SIGNAL 1} in @file{src/runtime/runtime.h}.
Don't forget to include OS and SBCL version.
@item
-If available include, information on outcome of the same test with
+If available, include information on outcome of the same test with
other versions of SBCL, OS, ...
@end enumerate
\word\@c
@end ifnottex
@end macro
+
+@c Some index prettification helper macros, for tricking the texindex
+@c collation "engine"
+@macro earmuffs{name}
+*\name\*
+@end macro
+@macro setf{name}
+(setf \name\)
+@end macro
+@include docstrings/package-macros.texinfo
;;; halt-on-failures and prompt-on-failures modes, suitable for
;;; noninteractive and interactive use respectively
(defun disable-debugger ()
+ "When invoked, this function will turn off both the SBCL debugger
+and LDB (the low-level debugger). See also ENABLE-DEBUGGER."
;; *DEBUG-IO* used to be set here to *ERROR-OUTPUT* which is sort
;; of unexpected but mostly harmless, but then ENABLE-DEBUGGER had
;; to set it to a suitable value again and be very careful,
(function sb!alien:void))))
(defun enable-debugger ()
+ "Restore the debugger if it has been turned off by DISABLE-DEBUGGER."
(when (eql *invoke-debugger-hook* 'debugger-disabled-hook)
(setf *invoke-debugger-hook* *old-debugger-hook*
*old-debugger-hook* nil))
;;; 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".)
-"1.0.39.8"
+"1.0.39.9"
projects / sbcl.git / commitdiff