2.11 Environment Control (Prolog flags)

The predicates current_prolog_flag/2 and set_prolog_flag/2 allow the user to examine and modify the execution environment. It provides access to whether optional features are available on this version, operating system, foreign-code environment, command-line arguments, version, as well as runtime flags to control the runtime behaviour of certain predicates to achieve compatibility with other Prolog environments.

[ISO]current_prolog_flag(?Key, -Value)
The predicate current_prolog_flag/2 defines an interface to installation features: options compiled in, version, home, etc. With both arguments unbound, it will generate all defined Prolog flags. With the `Key' instantiated it unifies the value of the Prolog flag. Flag values are typed. Flags marked as bool can have the values true and false. Some Prolog flags are not defined in all versions, which is normally indicated in the documentation below as ``if present and true''. A Boolean Prolog flag is true iff the Prolog flag is present and the Value is the atom true. Tests for such flags should be written as below.
        (   current_prolog_flag(windows, true)
        ->  <Do MS-Windows things>
        ;   <Do normal things>
abort_with_exception(bool, changeable)
Determines how abort/0 is realised. See the description of abort/0 for details.
Address-size of the hosting machine. Typically 32 or 64. Except for the maximum stack limit, this has few implications to the user. See also the Prolog flag arch.
agc_margin(integer, changeable)
If this amount of atoms has been created since the last atom-garbage collection, perform atom garbage collection at the first opportunity. Initial value is 10,000. May be changed. A value of 0 (zero) disables atom garbage collection. See also PL_register_atom().
allow_variable_name_as_functor(bool, changeable)
If true (default is false), Functor(arg) is read as if it was written 'Functor'(arg). Some applications use the Prolog read/1 predicate for reading an application defined script language. In these cases, it is often difficult to explain to non-Prolog users of the application that constants and functions can only start with a lowercase letter. Variables can be turned into atoms starting with an uppercase atom by calling read_term/2 using the option variable_names and binding the variables to their name. Using this feature, F(x) can be turned into valid syntax for such script languages. Suggested by Robert van Engelen. SWI-Prolog specific.
List is a list of atoms representing the command-line arguments used to invoke SWI-Prolog. Please note that all arguments are included in the list returned.
Identifier for the hardware and operating system SWI-Prolog is running on. Used to select foreign files for the right architecture. See also section 9.4 and file_search_path/2.
associate(atom, changeable)
On Windows systems, this is set to the filename extension (pl (default) or pro (can be selected in the installer)) associated with plwin.exe.
autoload(bool, changeable)
If true (default) autoloading of library functions is enabled. Note that autoloading only works if the flag unknown is not set to fail. See section 2.13.
backquoted_string(bool, changeable)
If true (default false), read translates text between backquotes into a string object (see section 4.23). This flag is mainly for compatibility to LPA Prolog.
ISO Prolog flag. If true, integer representation is bound by min_integer and max_integer. If false integers can be arbitrarily large and the min_integer and max_integer are not present. See section
Name of the C-compiler used to compile SWI-Prolog. Normally either gcc or cc. See section 9.7.
Special linker flags passed to link SWI-Prolog. See section 9.7.
Libraries passed to the C-linker when SWI-Prolog was linked. May be used to determine the libraries needed to create statically linked extensions for SWI-Prolog. See section 9.7.
char_conversion(bool, changeable)
Determines whether character-conversion takes place while reading terms. See also char_conversion/2.
character_escapes(bool, changeable)
If true (default), read/1 interprets \ escape sequences in quoted atoms and strings. May be changed. This flag is local to the module in which it is changed.
Describes when the system has been compiled. Only available if the C-compiler used to compile SWI-Prolog provides the __DATE__ and __TIME__ macros.
Set to true in plwin.exe to indicate the console supports menus. See also section 4.34.2.
cpu_count(integer, changeable)
Number of physical CPUs in the system. Unfortunately there is no standard to get this number, so on most operating systems this flag is not available. It is marked read-write both to allow obtaining this value later and to allow pretending the system has more or less processors. See also thread_setconcurrency/2 and the library library(thread). Currently this flag is supported in Windows and Linux if /proc is enabled. If you can provide us with a C-code fragment getting the number for a specific OS, please submit an enhancement report at http://gollem.science.uva.nl/bugzilla/
Set to true if this instance of Prolog supports DDE as described in section 4.42.
debug(bool, changeable)
Switch debugging mode on/off. If debug mode is activated the system traps encountered spy-points (see spy/1) and trace-points (see trace/1). In addition, last-call optimisation is disabled and the system is more conservative in destroying choice points to simplify debugging.

Disabling these optimisations can cause the system to run out of memory on programs that behave correctly if debug mode is off.

debug_on_error(bool, changeable)
If true, start the tracer after an error is detected. Otherwise just continue execution. The goal that raised the error will normally fail. See also fileerrors/2 and the Prolog flag report_error. May be changed. Default is true, except for the runtime version.
debugger_print_options(term, changeable)
This argument is given as option-list to write_term/2 for printing goals by the debugger. Modified by the `w', `p' and `<N> d' commands of the debugger. Default is [quoted(true), portray(true), max_depth(10), attributes(portray)].
debugger_show_context(bool, changeable)
If true, show the context module while printing a stack-frame in the tracer. Normally controlled using the `C' option of the tracer.
Fixed to swi. The code below is a reliable and portable way to detect SWI-Prolog.
is_dialect(swi) :-
        catch(current_prolog_flag(dialect, swi), _, fail).
double_quotes(codes,chars,atom,string, changeable)
This flag determines how double quoted strings are read by Prolog and is ---like character_escapes--- maintained for each module. If codes (default), a list of character-codes is returned, if chars a list of one-character atoms, if atom double quotes are the same as single-quotes and finally, string reads the text into a Prolog string (see section 4.23). See also atom_chars/2 and atom_codes/2.
If true, the system uses some form of `sparse-memory management' to realise the stacks. If false, malloc()/realloc() are used for the stacks. In earlier days this had consequences for foreign code. As of version 2.5, this is no longer the case.

Systems using `sparse-memory management' are a bit faster as there is no stack-shifter. On most systems using sparse-memory management memory is actually returned to the system after a garbage collection or call to trim_stacks/0 (called by prolog/0 after finishing a user-query).

editor(atom, changeable)
Determines the editor used by edit/1. See section 4.4 for details on selecting the editor used.
If true, SWI-Prolog is running as an inferior process of (GNU/X-)Emacs. SWI-Prolog assumes this is the case if the environment variable EMACS is t and INFERIOR is yes.
encoding(atom, changeable)
Default encoding used for opening files in text mode. The initial value is deduced from the environment. See section 2.17.1 for details.
Path-name of the running executable. Used by qsave_program/2 as default emulator.
file_name_variables(bool, changeable)
If true (default false), expand $varname and ~ in arguments of built-in predicates that accept a file name (open/3, exists_file/1, access_file/2, etc.). The predicate expand_file_name/2 can be used to expand environment variables and wildcard patterns. This Prolog flag is intended for backward compatibility with older versions of SWI-Prolog.
float_format(atom, changeable)
C-library printf() format specification used by write/1 and friends to determine how floating point numbers are printed. The default is %g. The specified value is passed to printf() without further checking. For example, if you want more digits printed, %.12g will print all floats using 12 digits instead of the default 6.

When using quoted-write, the output is guaranteed to contain a decimal dot or exponent, so read/1 reads a floating point number. See also format/[1,2], write_term/[2,3].

gc(bool, changeable)
If true (default), the garbage collector is active. If false, neither garbage-collection, nor stack-shifts will take place, even not on explicit request. May be changed.
generate_debug_info(bool, changeable)
If true (default) generate code that can be debugged using trace/0, spy/1, etc. Can be set to false using the -nodebug. The predicate load_files/2 restores the value of this flag after loading a file, causing modifications to be local to a source file. Many of the libraries have :- set_prolog_flag(generate_debug_info, false) to hide their details from a normal trace.7In the current implementation this only causes a flag to be set on the predicate that causes children to be hidden from the debugger. The name anticipates on anticipated changes to the compiler.
If Prolog is linked with GMP, this flag gives the major version of the GMP library used. See also section 9.6.7.
Set to true if XPCE is around and can be used for graphics.
history(integer, changeable)
If integer> 0, support Unix csh(1) like history as described in section 2.7. Otherwise, only support reusing commands through the command-line editor. The default is to set this Prolog flag to 0 if a command-line editor is provided (see Prolog flag readline) and 15 otherwise.
SWI-Prolog's notion of the home-directory. SWI-Prolog uses its home directory to find its startup file as <home>/boot32.prc (32-bit machines) or <home>/boot64.prc (64-bit machines) and to find its library as <home>/library.
In plwin.exe, this refers to the MS-Windows window-handle of the console window.
ISO Prolog flag describing rounding by // and rem arithmetic functions. Value depends on the C-compiler used.
iso(bool, changeable)
Include some weird ISO compatibility that is incompatible to normal SWI-Prolog behaviour. Currently it has the following effect:
  • The //2 (float division) always return a float, even if applied to integers that can be divided.
  • In the standard order of terms (see section 4.6.1), all floats are before all integers.
  • atom_length/2 yields an instantiation error if the first argument is a number.
  • clause/[2,3] raises a permission error when accessing static predicates.
  • abolish/[1,2] raises a permission error when accessing static predicates.
If present and true, SWI-Prolog has been compiled with large file support (LFS) and is capable to access files larger than 2GB on 32-bit hardware. Large file-support is default on installations built using configure that support it and may be switched off using the configure option --disable-largefile.
ISO Prolog flag describing there is no maximum arity to compound terms.
Maximum integer value if integers are bounded. See also the flag bounded and section
Maximum integer value represented as a `tagged' value. Tagged integers require 1 word storage. Larger integers are represented as `indirect data' and require significantly more space.
Provided on multi-threaded versions to indicate the maximum number of Prolog threads supported. Currently (version 5.6.27) the limit is 100.
Minimum integer value if integers are bounded. See also the flag bounded and section
Start of the tagged-integer value range.
occurs_check(atom, changeable)
This flag controls unification that creates an infinite tree (also called cyclic term) and can have three values. Using false (default), unification succeeds, creating an infinite tree. Using true, unification behaves as unify_with_occurs_check/2, failing silently. Using error, an attempt to create a cyclic term results in an occurs_check exception. The latter is intended for debugging unintentional creations of cyclic terms. Note that this flag is a global flag modifying fundamental behaviour of Prolog. Changing the flag from its default may cause libraries to stop functioning properly.
If true, open_shared_object/2 and friends are implemented, providing access to shared libraries (.so files) or dynamic link libraries (.DLL files).
optimise(bool, changeable)
If true, compile in optimised mode. The initial value is true if Prolog was started with the -O command-line option.

Currently optimise compilation implies compilation of arithmetic, and deletion of redundant true/0 that may result from expand_goal/2.

Later versions might imply various other optimisations such as integrating small predicates into their callers, eliminating constant expressions and other predictable constructs. Source code optimisation is never applied to predicates that are declared dynamic (see dynamic/1).

Process identifier of the running Prolog process. Existence of this flag is implementation defined.
pipe(bool, changeable)
If true, open(pipe(command), mode, Stream), etc. are supported. Can be changed to disable the use of pipes in applications testing this feature. Not recommended.
prompt_alternatives_on(atom, changeable)
Determines prompting for alternatives in the Prolog toplevel. Default is determinism, which implies the system prompts for alternatives if the goal succeeded while leaving choicepoints. Many classical Prolog systems behave as groundness: they prompt for alternatives if and only if the query contains variables.
If true, SWI-Prolog is linked with the readline library. This is done by default if you have this library installed on your system. It is also true for the Win32 plwin.exe version of SWI-Prolog, which realises a subset of the readline functionality.
Set to the absolute-filename of the attached state. Typically this is the file boot32.prc, the file specified with -x or the running executable. See also resource/3.
report_error(bool, changeable)
If true, print error messages, otherwise suppress them. May be changed. See also the debug_on_error Prolog flag. Default is true, except for the runtime version.
If present and true, SWI-Prolog is compiled with -DO_RUNTIME, disabling various useful development features (currently the tracer and profiler).
If present and true, Prolog has been started from a state saved with qsave_program/[1,2].
Extension used by the operating system for shared objects. .so for most Unix systems and .dll for Windows. Used for locating files using the file_type executable. See also absolute_file_name/3.
Name of the environment variable used by the system to search for shared objects.
Determine whether Prolog is handling signals (software interrupts). This flag is false if the hosting OS does not support signal handling or the command-line option -nosignals is active. See section for details.
Available in multi-threaded version (see section 8) where the operating system provides system-wide integer thread identifiers. The integer is the thread-identifier used by the operating system for the calling thread. See also thread_self/1.
last_call_optimisation(bool, changeable)
Determines whether or not last-call optimisation is enabled. Normally the value of this flag is equal to the debug flag. As programs may run out of stack if last-call optimisation is omitted, it is sometimes necessary to enable it during debugging.
Offset in seconds west of GMT of the current time-zone. Set at initialization time from the timezone variable associated with the POSIX tzset() function. See also convert_time/2.
toplevel_print_anon(bool, changeable)
If true, top-level variables starting with an underscore (_) are printed normally. If false they are hidden. This may be used to hide bindings in complex queries from the top-level.
toplevel_print_options(term, changeable)
This argument is given as option-list to write_term/2 for printing results of queries. Default is [quoted(true), portray(true), max_depth(10), attributes(portray)].
toplevel_var_size(int, changeable)
Maximum size counted in literals of a term returned as a binding for a variable in a top-level query that is saved for re-use using the $ variable reference. See section 2.8.
trace_gc(bool, changeable)
If true (false is the default), garbage collections and stack-shifts will be reported on the terminal. May be changed. Values are reported in bytes as G+T, where G is the global stack value and T the trail stack value. `Gained' describes the number of bytes reclaimed. `used' the number of bytes on the stack after GC and `free' the number of bytes allocated, but not in use. Below is an example output.
% GC: gained 236,416+163,424 in 0.00 sec; used 13,448+5,808; free 72,568+47,440
Determines whether the terminal is switched to raw mode for get_single_char/1, which also reads the user-actions for the trace. May be set. See also the +/-tty command-line option.
If present and true, the operating system is some version of Unix. Defined if the C-compiler used to compile this version of SWI-Prolog either defines __unix__ or unix. On other systems this flag is not available.
unknown(fail,warning,error, changeable)
Determines the behaviour if an undefined procedure is encountered. If fail, the predicates fails silently. If warn, a warning is printed, and execution continues as if the predicate was not defined and if error (default), an existence_error exception is raised. This flag is local to each module. Switching this flag to fail disables autoloading and thus forces complete and consistent use of use_module/[1,2] to load the required libraries.
verbose(Atom, changeable)
This flags is used by print_message/2. If its value is silent, messages of type informational and banner are suppressed. The -q switches the value from the initial normal to silent.
verbose_autoload(bool, changeable)
If true the normal consult message will be printed if a library is autoloaded. By default this message is suppressed. Intended to be used for debugging purposes.
verbose_load(bool, changeable)
If false normal consult messages will be suppressed. Default is true. The value of this flag is normally controlled by the option silent(Bool) provided by load_files/2.
verbose_file_search(bool, changeable)
If true (default false), print messages indicating the progress of absolute_file_name/[2,3] in locating files. Intended for debugging complicated file-search paths. See also file_search_path/2.
The version identifier is an integer with value:
10000 × Major + 100 × Minor + Patch
Note that in releases up to 2.7.10 this Prolog flag yielded an atom holding the three numbers separated by dots. The current representation is much easier for implementing version-conditional statements.
version_data(swi(Major, Minor, Patch, Extra))
Part of the dialect compatibility layer, See also the Prolog flag dialect and section C. Extra provides platform specific version information. Currently it is simply unified to [].
Available if created from a git repository. See git-describe for details.
If present and true, the operating system is an implementation of Microsoft Windows (NT/2000/XP, etc.). This flag is only available on MS-Windows based versions.
write_attributes(atom, changeable)
Defines how write/1 and friends write attributed variables. The option values are described with the attributes option of write_term/3. Default is ignore.
Internal flag used by help/1 when writing to a terminal. If present and true it prints bold and underlined text using overstrike.
Available and set to true if the XPCE graphics system is loaded.
Available and set to the version of the loaded XPCE system.
[ISO]set_prolog_flag(+Key, +Value)
Define a new Prolog flag or change its value. Key is an atom. If the flag is a system-defined flag that is not marked changeable above, an attempt to modify the flag yields a permission_error. If the provided Value does not match the type of the flag, a type_error is raised.

In addition to ISO, SWI-Prolog allows for user-defined Prolog flags. The type of the flag is determined from the initial value and cannot be changed afterwards. Defined types are boolean (if the initial value is one of false, true, on or off), atom if the initial value is any other atom, integer if the value is an integer that can be expressed as a 64-bit signed value. Any other initial value results in an untyped flag that can represent any valid Prolog term.