System Properties and Environment Variables

4.17.1 System Properties and Environment Variables

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:

Set the corresponding environment variable.
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.
Pass the -Dvar=value option to the sicstus command line tool. See too-sicstus.
Pass an option block to 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 proces 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:

If it does not contain an equal sign, the entry is ignored.
On Windows only, if it starts with an equal sign but has no other equal signs, the entry is ignored.
If the entry consists of valid UTF-8, it is kept as is. This is always true on Windows where a Unicode encoding is used internally by the operating system.
If the entry does not consist of valid UTF-8, it is treated as Latin-1 and converted to UTF-8. This cannot happen on Windows.
On Windows only, if the entry starts with an equal sign, the equal sign is treated as part of the variable name.

In particular, on UNIX-like systems, this means that the environment should preferably be in UTF-8.

4.17.1.1 System Properties Set by SICStus Prolog

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, 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.

4.17.1.2 System Properties Affecting Initialization

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.

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: 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. Only used by the default memory allocator (see SP_set_memalloc_hooks). 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, Prolog will try to use the available address space. Only used by the default memory allocator (see SP_set_memalloc_hooks). Thus if Prolog needs to allocate memory beyond this bound, a memory resource error will be raised.
PROLOGINCSIZE: Controls the amount of memory Prolog asks the operating system for in any given memory expansion. Only used by the default memory allocator (see SP_set_memalloc_hooks).
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 her program, once it has grown to a certain size, is likely to need as much memory for future computations, she 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. Only used by the default memory allocator (see SP_set_memalloc_hooks). 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. Corresponds to the -m flag to sicstus and the --userhook=malloc flag to spld (see SP_set_memalloc_hooks).

See Memory Use and Garbage Collection for more information.

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.

Send feedback on this subject.