@var{string} contains @samp{%}, @samp{`}, or @samp{'} it may be
reformatted, with undesirable results. Instead, use @code{(error "%s"
@var{string})}.
+
+When @code{noninteractive} is non-@code{nil} (@pxref{Batch Mode}),
+this function kills Emacs if the signaled error has no handler.
@end defun
@defun signal error-symbol data
The function @code{signal} never returns.
@c (though in older Emacs versions it sometimes could).
+If the error @var{error-symbol} has no handler, and
+@code{noninteractive} is non-@code{nil} (@pxref{Batch Mode}),
+this function eventually kills Emacs.
@example
@group
@end defvar
@cindex @code{debug-on-error} use
-An error that has no explicit handler may call the Lisp debugger. The
-debugger is enabled if the variable @code{debug-on-error} (@pxref{Error
-Debugging}) is non-@code{nil}. Unlike error handlers, the debugger runs
-in the environment of the error, so that you can examine values of
-variables precisely as they were at the time of the error.
+An error that has no explicit handler may call the Lisp debugger
+(@pxref{Invoking the Debugger}). The debugger is enabled if the
+variable @code{debug-on-error} (@pxref{Error Debugging}) is
+non-@code{nil}. Unlike error handlers, the debugger runs in the
+environment of the error, so that you can examine values of variables
+precisely as they were at the time of the error. In batch mode
+(@pxref{Batch Mode}), the Emacs process then normally exits with a
+non-zero exit status.
@node Handling Errors
@subsubsection Writing Code to Handle Errors
to invoke the debugger.
@deffn Command debug &rest debugger-args
-This function enters the debugger. It switches buffers to a buffer
-named @file{*Backtrace*} (or @file{*Backtrace*<2>} if it is the second
-recursive entry to the debugger, etc.), and fills it with information
-about the stack of Lisp function calls. It then enters a recursive
-edit, showing the backtrace buffer in Debugger mode.
+This function enters the debugger. In interactive sessions, it
+switches to a buffer named @file{*Backtrace*} (or
+@file{*Backtrace*<2>} if it is the second recursive entry to the
+debugger, etc.), and fills it with information about the stack of Lisp
+function calls. It then enters a recursive edit, showing the
+backtrace buffer in Debugger mode. In batch mode (more generally,
+when @code{noninteractive} is non-@code{nil}, @pxref{Batch Mode}),
+this function shows the Lisp backtrace on the standard error stream,
+and then kills Emacs, causing it to exit with a non-zero exit code
+(@pxref{Killing Emacs}). Binding
+@code{backtrace-on-error-noninteractive} to @code{nil} suppresses the
+backtrace in batch mode, see below.
The Debugger mode @kbd{c}, @kbd{d}, @kbd{j}, and @kbd{r} commands exit
the recursive edit; then @code{debug} switches back to the previous
@end table
@end deffn
+@defvar backtrace-on-error-noninteractive
+If this variable is non-@code{nil}, the default, entering the debugger
+in batch mode shows the backtrace of Lisp functions calls. Binding
+the variable to the @code{nil} value suppresses the backtrace and
+shows only the error message.
+@end defvar
+
@node Internals of Debugger
@subsection Internals of the Debugger
loads the library named @var{file}, or @samp{-f @var{function}}, which
calls @var{function} with no arguments, or @samp{--eval=@var{form}}.
+@defvar noninteractive
+This variable is non-@code{nil} when Emacs is running in batch mode.
+@end defvar
+
+ If the specified Lisp program signals an unhandled error in batch
+mode, Emacs exits with a non-zero exit status after invoking the Lisp
+debugger which shows the Lisp backtrace (@pxref{Invoking the
+Debugger}) on the standard error stream:
+
+@example
+$ emacs -Q --batch --eval '(error "foo")'; echo $?
+
+@group
+Error: error ("foo")
+mapbacktrace(#f(compiled-function (evald func args flags) #<bytecode -0x4f85c5
+7c45e2f81>))
+debug-early-backtrace()
+debug-early(error (error "foo"))
+signal(error ("foo"))
+error("foo")
+eval((error "foo") t)
+command-line-1(("--eval" "(error \"foo\")"))
+command-line()
+normal-top-level()
+@end group
+foo
+255
+@end example
+
Any Lisp program output that would normally go to the echo area,
either using @code{message}, or using @code{prin1}, etc., with
@code{t} as the stream (@pxref{Output Streams}), goes instead to
@code{coding-system-for-write} to a coding system of you choice
(@pxref{Explicit Encoding}).
+@vindex gc-cons-percentage@r{, in batch mode}
In batch mode, Emacs will enlarge the value of the
@code{gc-cons-percentage} variable from the default of @samp{0.1} up to
@samp{1.0}. Batch jobs that are supposed to run for a long time
garbage collection will be performed by default (and more memory
consumed).
-@defvar noninteractive
-This variable is non-@code{nil} when Emacs is running in batch mode.
-@end defvar
-
-If Emacs exits due to signaling an error in batch mode, the exit
-status of the Emacs command is non-zero:
-
-@example
-$ emacs -Q --batch --eval '(error "foo")'; echo $?
-foo
-255
-@end example
-
@node Session Management
@section Session Management
@cindex session manager
;;;###autoload
(defun debug (&rest args)
"Enter debugger. \\<debugger-mode-map>`\\[debugger-continue]' returns from the debugger.
+
+In interactive sessions, this switches to a backtrace buffer and shows
+the Lisp backtrace of function calls there. In batch mode (more accurately,
+when `noninteractive' is non-nil), it shows the Lisp backtrace on the
+standard error stream (unless `backtrace-on-error-noninteractive' is nil),
+and then kills Emacs, causing it to exit with a negative exit code.
+
Arguments are mainly for use when this is called from the internals
of the evaluator.
Errors cause entry to the debugger when `debug-on-error' is non-nil.
This can be overridden by `debug-ignored-errors'.
+When `noninteractive' is non-nil (in particular, in batch mode), an
+unhandled error calls `kill-emacs', which terminates the Emacs
+session with a non-zero exit code.
+
To signal with MESSAGE without interpreting format characters
like `%', `\\=`' and `\\='', use (error \"%s\" MESSAGE).
In Emacs, the convention is that error messages start with a capital
doc: /* Signal an error. Args are ERROR-SYMBOL and associated DATA.
This function does not return.
+When `noninteractive' is non-nil (in particular, in batch mode), an
+unhandled error calls `kill-emacs', which terminates the Emacs
+session with a non-zero exit code.
+
An error symbol is a symbol with an `error-conditions' property
that is a list of condition names. The symbol should be non-nil.
A handler for any of those names will get to handle this signal.
projects / emacs.git / commitdiff