@c Generated by the sb-manual contrib. Do not edit.

@node starting and stopping
@chapter Starting and Stopping

@menu
* Starting SBCL: starting sbcl.
* Stopping SBCL: stopping sbcl.
* Command Line Options: command line options.
* Initialization Files: initialization files.
* Initialization and Exit Hooks: initialization and exit hooks.
@end menu

@node starting sbcl
@section Starting SBCL

@menu
* Running from Shell: running from shell.
* Running from Emacs: running from emacs.
* Shebang Scripts: shebang scripts.
@end menu

@node running from shell
@subsection Running from Shell

To run SBCL, type @code{sbcl} at the command line.

You should end up in the toplevel @emph{REPL} (read-eval-print loop),
where you can interact with SBCL by typing expressions.

@example
$ sbcl
This is SBCL 0.8.13.60, an implementation of ANSI Common Lisp.
More information about SBCL is available at <http://www.sbcl.org/>.

SBCL is free software, provided as is, with absolutely no warranty.
It is mostly in the public domain; some portions are provided under
BSD-style licenses.  See the CREDITS and COPYING files in the
distribution for more information.
* (+ 2 2)
4
* (exit)
$
@end example

Also see @ref{command line options} and @ref{stopping sbcl}.

@node running from emacs
@subsection Running from Emacs

To run SBCL as an @code{inferior-lisp} from Emacs, in your @code{.emacs} do
something like:

@example
;;; The SBCL binary and command-line arguments
(setq inferior-lisp-program "/usr/local/bin/sbcl --noinform")
@end example

For more information on using SBCL with Emacs, see
@ref{editor integration}.

@node shebang scripts
@subsection Shebang Scripts

Standard Unix tools that are interpreters follow a common command line
protocol that is necessary to work with "shebang scripts". SBCL
supports this via the @code{--script} command line option (see
@ref{command line options}).

Example file (@code{hello.lisp}):

@example
#!/usr/local/bin/sbcl --script
(write-line "Hello, World!")
@end example

Usage from the command line:

@example
$ ./hello.lisp
Hello, World!
@end example

Note that SBCL skips the shebang line when it reads the file:

@example
$ sbcl --script hello.lisp
Hello, World!
@end example

@node stopping sbcl
@section Stopping SBCL

@menu
* Exit: exit.
* End of File: end of file.
* Saving a Core Image: saving a core image.
* Exit on Errors: exit on errors.
@end menu

@node exit
@subsection Exit

SBCL can be stopped at any time by calling @code{sb-ext:exit},
optionally returning a specified numeric value to the calling
process. See @ref{threading} for information about terminating individual
threads.

@anchor{Function sb-ext exit}
@ffindex @sortas{exit sb-ext} exit [sb-ext]
@deffn{Function} sb-ext:exit &key code abort timeout
Terminates the process, causing SBCL to exit with @code{code}. @code{code}
defaults to 0 when @code{abort} is false, and 1 when it is true.

When @code{abort} is false (the default), current thread is first unwound,
@code{*exit-hooks*} are run, other threads are terminated, and standard
output streams are flushed before SBCL calls @code{exit(3)} -- at which point
@code{atexit(3)} functions will run. If multiple threads call @code{exit} with @code{abort}
being false, the first one to call it will complete the protocol.

When @code{abort} is true, SBCL exits immediately by calling @code{_exit(2)}
without unwinding stack, or calling exit hooks. Note that @code{_exit(2)}
does not call @code{atexit(3)} functions unlike @code{exit(3)}.

Recursive calls to @code{exit} cause @code{exit} to behave as if @code{abort} was true.

@code{timeout} controls waiting for other threads to terminate when @code{abort} is
@code{nil}. Once current thread has been unwound and @code{*exit-hooks*} have been
run, spawning new threads is prevented and all other threads are
terminated by calling @code{sb-thread:terminate-thread} on them. The system
then waits for them to finish using @code{sb-thread:join-thread}, waiting at
most a total @code{timeout} seconds for all threads to join. Those threads
that do not finish in time are simply ignored while the exit protocol
continues. @code{timeout} defaults to @code{*exit-timeout*}, which in turn defaults
to 60. @code{timeout} @code{nil} means to wait indefinitely.

Note that @code{timeout} applies only to @code{sb-thread:join-thread}, not
@code{*exit-hooks*}. Since @code{sb-thread:terminate-thread} is asynchronous,
getting multithreaded application termination with complex cleanups
right using it can be tricky. To perform an orderly synchronous
shutdown use an exit hook instead of relying on implicit thread
termination.

Consequences are unspecified if serious conditions occur during @code{exit}
excepting errors from @code{*exit-hooks*}, which cause warnings and stop
execution of the hook that signaled, but otherwise allow the exit
process to continue normally.
@end deffn
@node end of file
@subsection End of File

By default SBCL also exits on end of input, caused either by user
pressing @code{Control-D} on an attached terminal, or end of input when
using SBCL as part of a shell pipeline.

@node saving a core image
@subsection Saving a Core Image

SBCL has the ability to save its state as a file for later
execution. This functionality is important for its bootstrapping
process, and is also provided as an extension to the user.

@anchor{Function sb-ext save-lisp-and-die}
@ffindex @sortas{save-lisp-and-die sb-ext} save-lisp-and-die [sb-ext]
@deffn{Function} sb-ext:save-lisp-and-die core-file-name &key toplevel executable save-runtime-options callable-exports purify root-structures environment-name compression
Save a "core image", i.e. enough information to restart a Lisp
process later in the same state, in the file of the specified name.
Only global state is preserved: the stack is unwound in the process.

The following @code{&key} arguments are defined:

@itemize
@item @code{:toplevel}

The function to run when the created core file is resumed. The
default function handles command line toplevel option
processing (see @ref{toplevel options}) and runs the top
level read-eval-print loop. This function returning is equivalent
to (@code{sb-ext:exit} @code{:code} 0) being called.

@code{toplevel} functions should always provide an @code{abort} restart:
otherwise code they call will run without one.

@item @code{:executable}

If true, arrange to combine the SBCL runtime and the core image to
create a standalone executable. If false (the default), the core
image will not be executable on its own. Executable images always
behave as if they were passed the @code{--noinform} runtime option.
 If @code{:executable} is @code{:elf-object}, then the resulting core will be
 wrapped in a .o which requires further linking. (EXPERIMENTAL)

@item @code{:save-runtime-options}

If true, values of runtime options @code{--dynamic-space-size} and
@code{--control-stack-size} that were used to start SBCL are stored in
the standalone executable, and restored when the executable is
run. This also inhibits normal runtime option processing, causing
all command line arguments to be passed to the toplevel. If
@code{:accept-runtime-options} then @code{--dynamic-space-size} and
@code{--control-stack-size} are still processed by the runtime.
Meaningless if @code{:executable} is @code{nil}.

@item @code{:callable-exports}

This should be a list of symbols to be initialized to the
appropriate alien callables on startup. All exported symbols
should be present as global symbols in the symbol table of the
runtime before the saved core is loaded. When this list is
non-empty, the @code{:toplevel} argument cannot be supplied.

@item @code{:purify}

If true (the default), then some objects in the restarted core
will be memory-mapped as read-only. Among those objects are
numeric vectors that were determined to be compile-time constants,
and any immutable values according to the language specification
such as symbol names.

@item @code{:root-structures}

This should be a list of the main entry points in any newly loaded
systems. This need not be supplied, but locality and/or @code{gc}
performance may be better if they are. This has two different but
related meanings: If @code{:purify} is true - and only for cheneygc - the
root structures are those which anchor the set of objects moved
into static space. On gencgc - and only on platforms supporting
immobile code - these are the functions and/or function-names
which commence a depth-first scan of code when reordering based on
the statically observable call chain. The complete set of
reachable objects is not affected per se. This argument is
meaningless if neither enabling precondition holds.

@item @code{:environment-name}

This has no purpose; it is accepted only for legacy compatibility.

@item @code{:compression}

This is only meaningful if the runtime was built with the
@code{:sb-core-compression} feature enabled. If @code{nil} (the default),
saves to uncompressed core files. If @code{:sb-core-compression} was
enabled at build-time, the argument may also be an integer from -7
to 22, corresponding to zstd compression levels, or @code{t} (which is
equivalent to the default compression level, 9).

@item @code{:application-type}

Present only on Windows and is meaningful only with @code{:executable} @code{t}.
Specifies the subsystem of the executable, @code{:console} or @code{:gui}.
The notable difference is that @code{:gui} doesn't automatically create
a console window. The default is @code{:console}.
@end itemize

The save/load process changes the values of some global variables:

@itemize
@item @code{*standard-output*}, @code{*debug-io*}, etc

Everything related to open streams is necessarily changed, since
the OS won't let us preserve a stream across save and load.

@item @code{*default-pathname-defaults*}

This is reinitialized to reflect the working directory where the
saved core is loaded.
@end itemize

@code{save-lisp-and-die} interacts with @code{sb-alien:load-shared-object}: see its
documentation for details.

On threaded platforms only a single thread may remain running after
@code{sb-ext:*save-hooks*} have run. Applications using multiple threads can
be @code{save-lisp-and-die} friendly by registering a save-hook that quits
any additional threads, and an init-hook that restarts them.

This implementation is not as polished and painless as you might like:

@itemize
@item It corrupts the current Lisp image enough that the current process
  needs to be killed afterwards. This can be worked around by forking
  another process that saves the core.

@item There is absolutely no binary compatibility of core images between
  different runtime support programs. Even runtimes built from the
  same sources at different times are treated as incompatible for this
  purpose.
@end itemize

This isn't because we like it this way, but just because there don't
seem to be good quick fixes for either limitation and no one has been
sufficiently motivated to do lengthy fixes.
@end deffn
@anchor{Variable sb-ext *save-hooks*}
@vvindex @sortas{save-hooks* sb-ext} *save-hooks* [sb-ext]
@deffn{Variable} sb-ext:*save-hooks*
A list of function designators which are called in an unspecified
order before creating a saved core image.

Unused by SBCL itself: reserved for user and applications.
@end deffn
In cases where the standard initialization files have already been loaded
into the saved core, and alternative ones should be used (or none at
all), SBCL allows customizing the initfile pathname computation.

@anchor{Variable sb-ext *sysinit-pathname-function*}
@vvindex @sortas{sysinit-pathname-function* sb-ext} *sysinit-pathname-function* [sb-ext]
@deffn{Variable} sb-ext:*sysinit-pathname-function*
Designator for a function of zero arguments called to obtain a
pathname designator for the default sysinit file, or @code{nil}. If the
function returns @code{nil}, no sysinit file is used unless one has been
specified on the command-line.
@end deffn
@anchor{Variable sb-ext *userinit-pathname-function*}
@vvindex @sortas{userinit-pathname-function* sb-ext} *userinit-pathname-function* [sb-ext]
@deffn{Variable} sb-ext:*userinit-pathname-function*
Designator for a function of zero arguments called to obtain a
pathname designator or a stream for the default userinit file, or @code{nil}.
If the function returns @code{nil}, no userinit file is used unless one has
been specified on the command-line.
@end deffn
To facilitate distribution of SBCL applications using external
resources, the filesystem location of the SBCL core file being used
is available from Lisp.

@anchor{Variable sb-ext *core-pathname*}
@vvindex @sortas{core-pathname* sb-ext} *core-pathname* [sb-ext]
@deffn{Variable} sb-ext:*core-pathname*
The absolute pathname of the running SBCL core.
@end deffn
@node exit on errors
@subsection Exit on Errors

SBCL can also be configured to exit if an unhandled error occurs,
which is mainly useful for acting as part of a shell pipeline; doing
so under most other circumstances would mean giving up large parts
of the flexibility and robustness of Common Lisp. See
@ref{debugger entry} and the command line option @code{--disable-debugger} in
@ref{runtime options}.

@node command line options
@section Command Line Options

@menu
* Runtime Options: runtime options.
* Toplevel Options: toplevel options.
@end menu

Command line options can be considered an advanced topic; for ordinary
interactive use, no command line arguments should be necessary.

In order to understand the command line argument syntax for SBCL, it
is helpful to understand that the SBCL system is implemented as two
components, a low-level runtime environment written in C and a
higher-level system written in Common Lisp itself. Some command line
arguments are processed during the initialization of the low-level
runtime environment, some command line arguments are processed
during the initialization of the Common Lisp system, and any
remaining command line arguments are made available to user code via
@code{sb-ext:*posix-argv*}.

The full, unambiguous syntax for invoking SBCL at the command line
is:

@example
sbcl <runtime-option>* --end-runtime-options \
     <toplevel-option>* --end-toplevel-options \
     <user-option>*
@end example

For convenience, @code{--end-runtime-options} and
@code{--end-toplevel-options} can be omitted, which can be convenient
when you are running the program interactively, and you can see that
no ambiguities are possible with the option values you are using.
Omitting these elements is probably a bad idea for any batch file
where any of the options are under user control, since it makes it
impossible for SBCL to detect erroneous command line input, so that
erroneous command line arguments will be passed on to the user
program even if they was intended for the runtime system or the Lisp
system.

@node runtime options
@subsection Runtime Options

@cindex disabling LDB
@cindex LDB, disabling
@cindex LDB
@cindex enabling LDB
@cindex LDB, enabling
@itemize
@item @code{--core <corefilename>}

Run the specified Lisp core file instead of the default. Note
that if the Lisp core file is a user-created core file, it may
run a nonstandard toplevel which does not recognize the standard
toplevel options.

@item @code{--dynamic-space-size <megabytes>}

Size of the dynamic space reserved on startup in megabytes.
Default value is platform dependent.

@item @code{--control-stack-size <megabytes>}

Size of control stack reserved for each thread in megabytes.
Default value is 2.

@item @code{--tls-limit <positive integer>}

Maximum number of thread-local symbols in threaded builds.
Default value is 4096.

@item @code{--noinform}

Suppress the printing of any banner or other informational
message at startup. This makes it easier to write Lisp programs
which work cleanly in Unix pipelines. See also the @code{--noprint}
and @code{--disable-debugger} options.

@item @code{--disable-ldb}

Disable the low-level debugger. Only effective if SBCL is
compiled with LDB. disabling LDB

@item @code{--lose-on-corruption}

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 handle the error in Lisp, but this will not
always work, and SBCL may malfunction or even hang. With this
option, upon encountering such an error, SBCL will exit instead
of invoking LDB (if present and enabled enabling LDB).

@item @code{--script <filename>}

As a @emph{runtime} option, this is equivalent to @code{--noinform}
@code{--disable-ldb} @code{--lose-on-corruption}
@code{--end-runtime-options} @code{--script} @code{<filename>}. See
the description of @code{--script} as a @emph{toplevel} option below.
If there are no other command line arguments following
@code{--script}, the filename argument can be omitted.

@item @code{--merge-core-pages}

When platform support is present, provide hints to the operating
system that identical pages may be shared between processes
until they are written to. This can be useful to reduce the
memory usage on systems with multiple SBCL processes started
from similar but differently-named core files, or from
compressed cores. Without platform support, do nothing. By
default only compressed cores trigger hinting.

@item @code{--no-merge-core-pages}

Ensures that no sharing hint is provided to the operating
system.

@item @code{--help}

Print some basic information about SBCL, then exit.

@item @code{--version}

Print SBCL's version information, then exit.
@end itemize

In the future, runtime options may be added to control behaviour
such as lazy allocation of memory.

Runtime options, including any @code{--end-runtime-options} option, are
stripped out of the command line before the Lisp toplevel logic gets
a chance to see it.

@node toplevel options
@subsection Toplevel Options

The following options are processed and removed by the default
toplevel (see @code{sb-ext:save-lisp-and-die}).

@itemize
@item @code{--sysinit <filename>}

Load @code{filename} instead of the default system initialization
file (see @ref{initialization files}).

@item @code{--no-sysinit}

Don't load a system-wide initialization file. If this option is
given, the @code{--sysinit} option is ignored.

@item @code{--userinit <filename>}

Load @code{filename} instead of the default user initialization file
(see @ref{initialization files}.)

@item @code{--no-userinit}

Don't load a user initialization file. If this option is given,
the @code{--userinit} option is ignored.

@item @code{--eval <command>}

After executing any initialization file, but before starting the
read-eval-print loop on standard input, read and evaluate
@code{command}. More than one @code{--eval} option can be used, and all
will be read and executed, in the order they appear on the
command line.

@item @code{--load <filename>}

This is equivalent to @code{--eval '(load "<filename>")'}. The
special syntax is intended to reduce quoting headaches when
invoking SBCL from shell scripts.

@item @code{--noprint}

When ordinarily the toplevel "read-eval-print loop" would be
executed, execute a "read-eval loop" instead, i.e. don't print
a prompt and don't echo results. Combined with the @code{--noinform}
runtime option, this makes it easier to write Lisp "scripts"
which work cleanly in Unix pipelines.

@item @code{--disable-debugger}

By default when SBCL encounters an error, it enters the builtin
debugger, allowing interactive diagnosis and possible
intercession. This option disables the debugger, causing errors
to print a backtrace and exit with status 1 instead. When given,
this option takes effect before loading of initialization files
or processing @code{--eval} and @code{--load} options. See
@code{sb-ext:disable-debugger} and @ref{debugger entry}.

@item @code{--script <filename>}

Implies @code{--no-userinit} @code{--no-sysinit} @code{--disable-debugger}
@code{--end-toplevel-options}.

Causes the system to load the specified file instead of entering
the read-eval-print-loop, and exit afterwards. If the file
begins with a shebang line, it is ignored.

If there are no other command line arguments following, the
filename can be omitted: this causes the script to be loaded
from standard input instead. Shebang lines in standard input
script are currently @emph{not} ignored.

In either case, if there is an unhandled error (e.g. end of
file, or a broken pipe) on either standard input, standard
output, or standard error, the script silently exits with code
0. This allows e.g. safely piping output from SBCL to @code{head -n1}
or similar.

Additionally, the option sets @code{*compile-verbose*} and
@code{*load-verbose*} to @code{nil} while loading the file to avoid
potentially verbose diagnostic messages printed on the standard
output.
@end itemize

@node initialization files
@section Initialization Files

SBCL processes initialization files with @code{read} and @code{eval},
not @code{load}; hence initialization files can be used to set startup
@code{*package*} and @code{*readtable*}, and for proclaiming a global optimization
policy.

@cindex Read-Eval-Print Loop
@cindex REPL
@itemize
@item @strong{System Initialization File:} Defaults to @code{$SBCL_HOME/sbclrc},
  or if that doesn't exist to @code{/etc/sbclrc}. Can be overridden with
  the command line option @code{--sysinit} or @code{--no-sysinit} (see
  @ref{toplevel options}).

The system initialization file is intended for system
administrators and software packagers to configure locations of
installed third party modules, etc.

@item @strong{User Initialization File:} Defaults to @code{$HOME/.sbclrc}. Can be
  overridden with the command line option @code{--userinit} or
  @code{--no-userinit} (see @ref{toplevel options}).

The user initialization file is intended for personal
customizations, such as loading certain modules at startup,
defining convenience functions to use in the REPL,
handling automatic recompilation of FASLs (see @ref{fasl format}),
etc.
@end itemize

Neither initialization file is required.

@node initialization and exit hooks
@section Initialization and Exit Hooks

SBCL provides hooks into the system initialization and exit.

@anchor{Variable sb-ext *init-hooks*}
@vvindex @sortas{init-hooks* sb-ext} *init-hooks* [sb-ext]
@deffn{Variable} sb-ext:*init-hooks*
A list of function designators which are called in an unspecified
order when a saved core image starts up, after the system itself has
been initialized, but before non-user threads such as the finalizer
thread have been started.

Unused by SBCL itself: reserved for user and applications.
@end deffn
@anchor{Variable sb-ext *exit-hooks*}
@vvindex @sortas{exit-hooks* sb-ext} *exit-hooks* [sb-ext]
@deffn{Variable} sb-ext:*exit-hooks*
A list of function designators which are called in an unspecified
order when SBCL process exits.

Unused by SBCL itself: reserved for user and applications.

Using (@code{sb-ext:exit} @code{:abort} @code{t}), or calling @code{exit(3)} directly circumvents
these hooks.
@end deffn
