Add doc describing the env variables

2 files changed, 21 insertions, 0 deletions

diff --git a/doc/api_ref/contents.rst b/doc/api_ref/contents.rst
index 2cdfbc4d9..a77ca703b 100644
--- a/doc/api_ref/contents.rst
+++ b/doc/api_ref/contents.rst
@@ -34,4 +34,5 @@ API Reference
    tpm
    otp
    ffi
+   env_vars
    python
diff --git a/doc/api_ref/env_vars.rst b/doc/api_ref/env_vars.rst
new file mode 100644
index 000000000..221a22545
--- /dev/null
+++ b/doc/api_ref/env_vars.rst
@@ -0,0 +1,20 @@
+Environment Variables
+======================
+
+Certain environment variables can affect or tune the behavior of the
+library. The variables and their behavior are described here.
+
+* ``BOTAN_THREAD_POOL_SIZE`` controls the number of threads which will be
+  created for a thread pool used for some purposes within the library. If not
+  set then it defaults to the number of CPUs available on the system.
+
+* ``BOTAN_MLOCK_POOL_SIZE`` controls the total amount of memory which will be
+  locked in memory using ``mlock`` or ``VirtualLock`` and managed in a memory
+  pool. If set to ``0`` (or indeed any value smaller than the system page size),
+  then the memory pool is disabled.
+
+* ``BOTAN_FFI_PRINT_EXCEPTIONS`` if this variable is set (to any value), then
+  if an exception is caught by the FFI layer, before returning an error code, it
+  will print the text message of the exception to stderr. This is primarily
+  intended for debugging.
+