SICStus Prolog stores some information in named variables called system properties. System properties are used since release 4.1, whereas previous releases used environment variables.
The default value when reading a system property is taken from the corresponding environment variable. This makes system properties largely backward compatible with how environment variables were used in previous releases. Any exceptions to this rule are explicitly mentioned in the documentation.
You can obtain the value of system properties and environment variables
using system:environ/[2,3]
(see lib-system) and
SP_getenv()
.
Some system properties affect the SICStus Prolog initialization process and must therefore be set before SICStus Prolog has been initialized. There are three ways to affect the initial values of system properties:
System properties get their default value from the environment so this is often a convenient method. It was the only method available prior to release 4.1.
sicstus
command line tool. See too-sicstus.
SP_initialize()
if you initialize
the SICStus runtime from C. See Initializing the Prolog Engine.
Looking up system properties follows the platform convention for environment variables. This means that the lookup is case sensitive on UNIX-like platforms and case insensitive on Windows.
On UNIX-like systems, the environment is assumed to use the UTF-8 character encoding; on Windows, the native Unicode encoding is used.
SICStus reads and copies the process environment during
initialization, e.g. in SP_initialize()
. Any subsequent
changes to the process environment will not be detected by
SICStus. Note that, at least on UNIX-like systems, changing the
process environment, e.g. using setenv()
, has undefined behavior
when the process has multiple threads, which is the case for any
process running SICStus.
While copying the environment, each entry in the environment is normalized as follows:
In particular, on UNIX-like systems, this means that the environment should preferably be in UTF-8.
The following system properties are set automatically on startup.
SP_APP_DIR
The absolute path to the directory that contains the executable.
Also available as the application
file search path.
SP_APP_PATH
The absolute path to the executable. Unlike SP_APP_DIR
, this
system property may not be available under all circumstances.
SP_RT_DIR
The full path to the directory that contains the SICStus runtime. If
the application was linked statically to the SICStus runtime, then SP_RT_DIR
is the same as SP_APP_DIR
.
Also available as the runtime
file search path.
SP_RT_PATH
The absolute path to the SICStus runtime. Unlike SP_RT_DIR
, this
system property may not be available under all circumstances, e.g. if
the runtime is not a shared library.
SP_LIBRARY_DIR
The absolute path to the directory that contains the SICStus library files.
Also available as the initial value of the library
file search path.
SP_TEMP_DIR
A directory suitable for storing temporary files. It is particularly
useful with the open/4
option
if_exists(generate_unique_name)
.
Also available as the temp
file search path.
SP_STARTUP_DIR
During initialization the SP_STARTUP_DIR
system property will be
set to the working directory used by SICStus.
Note that this system property can also be set prior to initialization, in order to tell SICStus which working directory to use. See below.
The following system properties can be set before starting SICStus Prolog.
Some of these override the default sizes of certain areas. For variables ending with ‘SIZE’, the size is in bytes, but may be followed by ‘K’, ‘M’, or ‘G’ meaning 2**10, 2**20 and 2**30 respectively.
Boolean values true and false are represented by ‘yes’ and ‘no’, respectively.
See Memory Use and Garbage Collection for more information about the properties that affect memory management.
SP_PATH
Can be used to specify the location of the Runtime Library. In most cases there is no need to use it, but see CPL Notes.
SP_STARTUP_DIR
The value of this system property, if set, is used as the initial working directory. Note that this system property is also set automatically during initialization; see above.
This value of this system property is not read from the corresponding environment variable.
SP_ALLOW_CHDIR
If this system property is set to ‘no’, then SICStus will not change the process’s working directory when the SICStus working directory changes. This is useful when embedding SICStus and would probably be the better default behavior except for backwards compatibility.
GLOBALSTKSIZE
Controls the initial size of the global stack. Please note: The global stack will not be subsequently trimmed to a size smaller than this initial size.
LOCALSTKSIZE
Controls the initial size of the local stack. Please note: The local stack will not be subsequently trimmed to a size smaller than this initial size.
CHOICESTKSIZE
Controls the initial size of the choicepoint stack. Please note: The choicepoint stack will not be subsequently trimmed to a size smaller than this initial size.
TRAILSTKSIZE
Controls the initial size of the trail stack. Please note: The trail stack will not be subsequently trimmed to a size smaller than this initial size.
GROWTHFACTOR since release 4.0.8
Meaningful values are between 10 and 100; the default is 62. Controls the rate at which the Prolog stacks grow when they are expanded. These stacks are stored in two data areas: one holding the global and local stacks; another one holding the choicepoint and trail stacks. In addition, both data areas hold some memory reserved for the garbage collector.
The sizes of the two data areas are constrained to take certain
discrete values only. The initial size as well as the size after
expansion is constrained to be w*((1+g)^n) kilobytes, rounded up
to an integral number of words, where w is the word length in
bits, g is GROWTHFACTOR
/100, and n is an integer.
PROLOGINITSIZE
Controls the size of Prolog’s initial memory allocation.
Please note: This initially allocated memory will be kept by
the Prolog process until SP_deinitialize()
is called or the
process exits.
PROLOGMAXSIZE
Defines an upper bound on the amount of memory that Prolog will use. If not set, then Prolog will try to use the available address space. Thus if Prolog needs to allocate memory beyond this bound, then a memory resource error will be raised.
PROLOGINCSIZE
Controls the amount of memory Prolog asks the operating system for in any given memory expansion.
PROLOGKEEPSIZE
Defines a lower bound on the amount of memory retained by
trimcore/0
. By default, Prolog gets memory from the O/S as the
user program executes, whereas trimcore/0
endeavors to return
free memory back to the O/S. If the programmer knows that their
program, once it has grown to a certain size, then is likely to need as
much memory for future computations, they can advise Prolog not to
return all the free memory back to the operating system by setting
this variable. trimcore/0
only endeavors to return memory that is
allocated above and beyond PROLOGKEEPSIZE
; the rest will be
kept.
Please note: The initially allocated memory will be kept by
the Prolog process forever, so it is not meaningful to set
PROLOGKEEPSIZE
smaller than PROLOGINITSIZE
.
SP_ULIMIT_DATA_SEGMENT_SIZE
Sets the maximum size of the data segment of the Prolog process. The
value can be unlimited
or a numeric value as described in the
first paragraph in this section. A numeric value of zero (0) is
equivalent to unlimited
. Not used under Windows.
SP_USE_MALLOC
If yes
, then malloc()
et al. will be used for memory
management instead of the default memory allocator. This is sometimes
useful, e.g$: with debugging tools like
valgrind
.
Please note: Enabling malloc()
allocation is not
compatible with JIT compilation.
SP_JIT since release 4.3
Affects whether the JIT (Just In Time) compiler should be used to compile Prolog code into native (machine) code. One of:
yes
JIT compilation is enabled and happens automatically. This is the default on platforms that support JIT compilation.
no
JIT compilation is enabled but does not happen automatically. Currently, there is no documented way to JIT compile predicates manually.
disabled
JIT compilation is disabled completely. Please report if you encounter any reason to disable the JIT compiler.
JIT compilation may need to be disabled on certain security-hardened operating systems, e.g. because they do not permit memory to be both writable and executable.
This system property is ignored on platforms that do not support the JIT compiler.
SP_JIT_COUNTER_LIMIT since release 4.3
Determines how many times a predicate can be called before it is JIT compiled. The default is 0.
The heuristics used in order to decide when, and whether, a predicate should be JIT compiled, is subject to change without notice. In particular, this system property may be treated differently in some future release.
SP_JIT_CLAUSE_LIMIT since release 4.3
Sets an upper bound on the number of clauses of a predicate for JIT compilation to be attempted. The default is 1024.
SP_SPTI_PATH since release 4.3
Specify a plugin that will be told when predicates are JIT compiled. The details of writing or using such plugins are currently not documented, and subject to change without notice.
There are two predefined plugins,
verbose
Write verbose information when a predicate is JIT compiled. This can be useful when troubleshooting problems with JIT compilation, e.g. if some predicate takes too long to JIT-compile.
This plugin can be activated by passing
-DSP_SPTI_PATH=verbose to sicstus
.
perf
Tell the Linux perf profiler about the location and name of the JIT compiled
predicates. This makes it possible to use perf record
etc. for getting
accurate and low-overhead profiling info about JIT compiled
code.
This plugin can be activated either by passing
-DSP_SPTI_PATH=perf to sicstus
, or, once
SICStus has started, with the goal
use_module(library(perf))
.
The perf
integration is only available on Linux.
In addition some system properties are read during normal execution. In
this case the system property is typically not meant to be explicitly
set, instead the value is intended to be taken from the corresponding
environment variable. Examples of such system properties include
PATH
and HOME
.