doc/efun/configure_driver

SYNOPSIS
        #include <configuration.h>

        void configure_driver(int what, mixed data)

DESCRIPTION
        This efun configures runtime adjustable bahviour of the driver.

        Sets the option <what> to the value <data>.

        This function always causes the privilege_violation
        ("configure_driver", this_object(), what, data).

        <what> == DC_MEMORY_LIMIT
           Set new soft and hard memory limits for the driver.
           <data> is expected to be an array with two elements, which have to
           be integers giving the amount of memory in bytes.
           ({<soft memory limit>, <hard memory limit>})

        <what> == DC_ENABLE_HEART_BEATS
           Globally enable the calling of Heartbeats, if <data> is 1,
           globally disable them if <data> is 0.
           If called during heartbeat processing, the change comes into effect
           at the next backend cycle.

        <what> == DC_LONG_EXEC_TIME
           Set the time considered as (too) long for top-level executions. If
           an execution exceeds this time, a stack trace will be written to
           the debug log. The execution will continue at that point.
           <data> is an integer and measured in microseconds.
           A time of 0 disables the detection of long executions.

        <what> == DC_DATA_CLEAN_TIME
           Sets the average time between clean-ups of an objects data
           structures. This is not to be confused with the standard cleanup
           time which determines when H_CLEAN_UP is called. A long time for
           data cleanup may lead to larger memory consumption and prevents
           destructed objects being cleaned up. A too short time may lead to
           high loads and lag on the machine. The actual time delay will be a
           time between 0.9*DC_DATA_CLEAN_TIME and 1.1*DC_DATA_CLEAN_TIME.
           Default at driver startup are 3600s.
           <data> is an integer and measured in seconds.

        <what> == DC_TLS_CERTIFICATE
           Sets the current certificate used for new TLS sessions.
           It can be one of the certificates in the key directory
           (command line option --tls-keydirectory) or the main
           certificate (given with --tls-certfile).
           Default is the main certificate or else the first
           certificate found in the directory. The chosen certificate at the
           time of the tls_init_connection() call is used for that connection.
           <data> is a string containing the SHA1 fingerprint
           of the certificate with hexadecimal numbers,
           it may contain colons or whitespaces (for example
           "5A:FE:CA:57:1E:50:5E:1E:C7:ED:BA:11:AD:50:10:75:0F:7A:1E:50").
           When loading certificates their fingerprints are printed
           on stdout and into the logfile.

        <what> == DC_TLS_DHE_PARAMETER
           Sets new parameters for the Diffie-Hellman keyexchange for new TLS
           sessions. The paramters must be given as a PEM encoded string
           (e.g. the output of 'openssl dhparam -5 2048').
           If <data> is 0, the built-in defaults will be restored.
           If importing the new parameters fails (e.g. due to an incorrect
           format), the driver tries to keep the old parameters 

        <what> == DC_TLS_CIPHERLIST
           Sets a new list of ciphers (OpenSSL) or priorities (GnuTLS) to use.
           For the correct format, please refer to the help of 'openssl
           ciphers' or documentation of priority strings in GnuTLS.
           With GnuTLS a syntax error in the list causes an error.
           With OpenSSL an error is only raised of none of the given ciphers
           could be selected.
           By default, the preferred ciphers of the driver take precedence
           This can be changed in the priority strings for GnuTLS, but
           currently not for OpenSSL.

        <what> == DC_EXTRA_WIZINFO_SIZE
           Indicate that the wizlist should contain an array of the given size
           with extra info for each wizard. A negative value indicates
           a non-array value.

           The value is only used to allocate a proper empty 'extra' value
           for newly created wizlist entries.

        <what> == DC_DEFAULT_RUNTIME_LIMITS
           Sets the default runtime limits, that will be used for each thread.
           They will be in effect as the initial limits with the next thread.
           The limits must be given as an array with the following entries:

             int[LIMIT_EVAL]:         the max number of eval costs
             int[LIMIT_ARRAY]:        the max number of array entries
             int[LIMIT_MAPPING_SIZE]: the max number of mapping values
             int[LIMIT_MAPPING_KEYS]: the max number of mapping entries
             int[LIMIT_BYTE]:         the max number of bytes handled with
                                      one read_bytes()/write_bytes() call.
             int[LIMIT_FILE]:         the max number of bytes handled with
                                      one read_file()/write_file() call.
             int[LIMIT_CALLOUTS]:     the number of callouts at one time.
             int[LIMIT_COST]:         how to account the current cost.
             int[LIMIT_MEMROY]:       the max. number of bytes which can be 
                                        _additionally_ allocated/used
                                        _per top-level execution thread_.

          The limit settings recognize three special values:

            LIMIT_UNLIMITED:  the limit is deactivated
            LIMIT_KEEP:       the former setting is kept
            LIMIT_DEFAULT:    the 'global' default setting is used.

          For LIMIT_COST, the special values have these meaning:
            LIMIT_UNLIMITED:  at maximum 1 tick is accounted
            LIMIT_KEEP:        LIMIT_COST is set to 0
            LIMIT_DEFAULT:     LIMIT_COST is set to -100

        <what> == DC_SWAP_COMPACT_MODE
           Sets free swap space shall be reused immediately to keep
           the swap file as small as possible.
           (Same as the --swap-compact command line switch.)

        <what> == DC_SWAP_TIME
           Sets the time until the program of an unused object is swapped out
           (if possible). Setting the interval to 0 disables swapping of
           programs.
           <data> is an integer and measured in seconds.
           (Same as the --swap-time command line switch.)

        <what> == DC_SWAP_VAR_TIME
           Sets the time until the variables of an unused object are swapped
           out. Setting the interval to 0 disables swapping of variables.
           <data> is an integer and measured in seconds.
           (Same as the --swap-variables command line switch.)

        <what> == DC_CLEANUP_TIME
           Sets the time until the cleanup hook is called in unused objects.
           <data> is an integer and measured in seconds.
           (Same as the --cleanup-time command line switch.)

        <what> == DC_RESET_TIME
           Sets the default time until the reset hook is called in objects.
           The change will take effect for each object after its next reset.
           <data> is an integer and measured in seconds.
           (Same as the --reset-time command line switch.)

        <what> == DC_DEBUG_FILE
           Sets the debug log file.
           The filename can be given relative to the mudlib directory
           or absolute with regard to the operating system.
           Settings this option will force closing and reopening
           the log file (even if the name didn't change).

         <what> == DC_FILESYSTEM_ENCODING
           Sets the character encoding used in the filesystem.
           If not set, the default encoding is derived from the LC_CTYPE
           environment setting. If LC_CTYPE is not defined, or it is set to
           the "C" locale, then "UTF-8" is used as a default.

         <what> == DC_SIGACTION_SIGHUP
         <what> == DC_SIGACTION_SIGINT
         <what> == DC_SIGACTION_SIGUSR1
         <what> == DC_SIGACTION_SIGUSR2
           Sets the default action when the driver encounters those
           POSIX signals. It can be set to one of the following options:

             DCS_DEFAULT:
                 This is the default action: Call handle_external_signal()
                 in the master and act upon its result.

             DCS_IGNORE:
                 Ignore the signal.

             DCS_TERMINATE:
                 Terminate the process immediately.

             DCS_SHUTDOWN:
                 Do a graceful shutdown.

             DCS_INFORM_MASTER:
                 Call handle_external_signal(), but ignore its result.

             DCS_RELOAD_MASTER:
                 Reload the master object.

             DCS_THROW_EXCEPTION:
                 Cause an error in the currently running LPC or Python
                 function.

HISTORY
        Introduced in LDMud 3.3.719.
        DC_ENABLE_HEART_BEATS was added in 3.5.0.
        DC_LONG_EXEC_TIME was added in 3.5.0.
        DC_DATA_CLEAN_TIME was added in 3.5.0.
        DC_EXTRA_WIZINFO_SIZE was added in 3.5.0.
        DC_TLS_CERTIFICATE was added in 3.5.0.
        DC_TLS_DHE_PARAMETER was added in 3.5.0.
        DC_TLS_CIPHERLIST was added in 3.5.0.
        DC_SWAP_COMPACT_MODE was added in 3.5.0.
        DC_SWAP_TIME was added in 3.5.2
        DC_SWAP_VAR_TIME was added in 3.5.2
        DC_CLEANUP_TIME was added in 3.5.2
        DC_RESET_TIME was added in 3.5.2
        DC_DEBUG_FILE was added in 3.5.2.
        DC_SIGACTION_* were added in 3.5.2.

SEE ALSO
        configure_interactive(E)