MG Mud User | 88f1247 | 2016-06-24 23:31:02 +0200 | [diff] [blame^] | 1 | NAME |
| 2 | driver/invocation |
| 3 | |
| 4 | PURPOSE |
| 5 | Description of the invocation of the gamedriver, especially of the command |
| 6 | arguments. This document describes the commandline version of the driver |
| 7 | only; non-commandline versions are platform specific and described in |
| 8 | the related documentation. |
| 9 | |
| 10 | DESCRIPTION |
| 11 | The driver is invoked from the commandline as other normal programs. |
| 12 | Neither the current directory nor the directory the executable is in need |
| 13 | to be in any special relation the directory of the mudlib. Once the driver |
| 14 | is running, it emits two streams of outputs: |
| 15 | |
| 16 | - driver-related messages on stderr; this unfortunately includes |
| 17 | LPC compiler diagnostics |
| 18 | - LPC runtime-related messages in the logfile <mudlib>/<host>.parse.log |
| 19 | (the name can be changed). |
| 20 | |
| 21 | It is possible to start the driver without any commandline arguments as |
| 22 | suitable defaults are specified at compile time. The invocation syntax |
| 23 | is: |
| 24 | |
| 25 | driver [options] [<portnumber>]... |
| 26 | |
| 27 | <portnumber> the number of the port the driver shall use to accept |
| 28 | connections. The maximum number of ports is determined by MAXNUMPORTS |
| 29 | in the source file config.h. |
| 30 | |
| 31 | The options modify the behaviour of the gamedriver. Some of them are only |
| 32 | available if a certain compile-time option was enabled (typically in |
| 33 | the source file config.h). The following options are recognized: |
| 34 | |
| 35 | -P|--inherit <fd-number> |
| 36 | Inherit filedescriptor <fd-number> from the parent process |
| 37 | as socket to listen for connections. |
| 38 | Only available if compiled with MAXNUMPORTS. |
| 39 | |
| 40 | -u|--udp <portnumber> |
| 41 | Specify the <portnumber> for the UDP port, overriding the compiled-in |
| 42 | default. |
| 43 | Only available if compiled with CATCH_UDP_PORT. |
| 44 | |
| 45 | -D|--define <macro>[=<text>] |
| 46 | Add <macro> (optionally to be expanded to <text>) to the list of |
| 47 | predefined macros known by the LPC compiler. |
| 48 | |
| 49 | -E|--eval-cost <ticks> |
| 50 | Set the number of <ticks> available for one evaluation thread. |
| 51 | If 0, execution is unlimited. |
| 52 | |
| 53 | -M|--master <filename> |
| 54 | Use <filename> for the master object. |
| 55 | |
| 56 | -m|--mudlib <pathname> |
| 57 | Use <pathname> as the top directory of the mudlib. |
| 58 | |
| 59 | --debug-file <filename> |
| 60 | Log all debug output in <filename> instead of |
| 61 | <mudlib>/<host>.debug.log . |
| 62 | |
| 63 | --hostname <name> |
| 64 | Use <name> as hostname instead of what the system says. |
| 65 | |
| 66 | --hostaddr <addr> |
| 67 | Use <addr> as address of this machine, instead of what the |
| 68 | system says. In particular this address will be used to open |
| 69 | the driver ports. |
| 70 | |
| 71 | --no-compat |
| 72 | --compat |
| 73 | Select the mode (plain or compat) of the driver. |
| 74 | This choice does not affect the default name of the master object. |
| 75 | |
| 76 | -d|--debug |
| 77 | Generate debug output; repeat the argument for even more output: |
| 78 | >= 1: log resets, clean ups, swaps, reception of urgend data, |
| 79 | telnet negotiation states. |
| 80 | check_a_lot_of_refcounts() on startup when swapping of |
| 81 | variables is disabled. |
| 82 | >= 2: log all add_message()s, name lookup failures, new players. |
| 83 | >= 3: progress of garbage collection |
| 84 | >= 4: even more junk from garbage collection |
| 85 | |
| 86 | -c|--list-compiles |
| 87 | List the name of every compiled file on stderr. |
| 88 | |
| 89 | -e|--no-preload |
| 90 | Pass a non-zero argument (the number of occurences of this option) |
| 91 | to master->preload(), which usually inhibits all preloads of castles |
| 92 | and other objects. |
| 93 | |
| 94 | --erq <filename> |
| 95 | --erq "<filename> <erq args>" |
| 96 | Use <filename> instead of 'erq' as the basename of the ERQ executable. |
| 97 | If the name starts with a '/', it is take to be an absolute pathname, |
| 98 | otherwise it is interpreted relative to <bindir>. If not specified, |
| 99 | 'erq' is used as the executable name. |
| 100 | |
| 101 | By enclosing the argument value in quotes, it is possible to pass |
| 102 | arguments (e.g. --execdir) to the erq. These arguments however must |
| 103 | not contain embedded spaces. |
| 104 | |
| 105 | -N|--no-erq |
| 106 | Don't start the erq demon (if it would be started at all). |
| 107 | |
| 108 | --alarm-time <seconds> |
| 109 | Set the granularity of call_out() and heartbeat timing. Minimum |
| 110 | value is 1. |
| 111 | |
| 112 | --heart-interval <seconds> |
| 113 | Set the interval between two heartbeats. Minimum value is 1. |
| 114 | |
| 115 | --sync-heart |
| 116 | All heartbeats occur at the same time (modulo granularity). |
| 117 | |
| 118 | --async-heart |
| 119 | Heartbeats occur when they are due (modulo granularity). |
| 120 | |
| 121 | -t|--no-heart |
| 122 | Disable heartbeats and call_outs. |
| 123 | |
| 124 | -f|--funcall <word> |
| 125 | The lfun master->flag() is called with <word> as argument before the |
| 126 | gamedriver accepts netword connections. |
| 127 | |
| 128 | --regexp pcre | traditional |
| 129 | Select the default regexp package. |
| 130 | |
| 131 | --max-array <size> |
| 132 | The maximum number of elements an array can hold. |
| 133 | Set to 0, arrays of any size are allowed. |
| 134 | |
| 135 | --max-mapping <size> |
| 136 | The maximum number of elements a mapping can hold. |
| 137 | Set to 0, mappings of any size are allowed. |
| 138 | |
| 139 | --max-mapping-keys <size> |
| 140 | The maximum number of entries a mapping can hold. |
| 141 | Set to 0, mappings of any size are allowed. |
| 142 | |
| 143 | --max-callouts <size> |
| 144 | The maximum number of callouts at one time. |
| 145 | Set to 0, any number is allowed. |
| 146 | |
| 147 | --max-bytes <size> |
| 148 | The maximum number of bytes one read_bytes()/write_bytes() call |
| 149 | can handle. |
| 150 | Set to 0, reads and writes of any size are allowed. |
| 151 | |
| 152 | --max-file <size> |
| 153 | The maximum number of bytes one read_file()/write_file() call |
| 154 | can handle. |
| 155 | Set to 0, reads and writes of any size are allowed. |
| 156 | |
| 157 | --max-thread-pending <size>\n" |
| 158 | The maximum number of bytes to be kept pending by the socket write |
| 159 | thread. |
| 160 | Set to 0, an unlimited amount of data can be kept pending. |
| 161 | |
| 162 | This option is ignored if pthreads are not used. |
| 163 | |
| 164 | --cleanup-time <time> |
| 165 | The idle time in seconds for an object before the driver tries to |
| 166 | clean it up. It should be substantially longer than the reset time. |
| 167 | A time <= 0 disables the cleanup mechanism. |
| 168 | |
| 169 | --reset-time <time> |
| 170 | The time in seconds before an object is reset. A time <= 0 disables |
| 171 | the reset mechanism. |
| 172 | |
| 173 | -s <time> | --swap-time <time> |
| 174 | -s v<time> | --swap-variables <time> |
| 175 | Time in seconds before an object (or its variables) are swapped out. |
| 176 | A time less or equal 0 disables swapping. |
| 177 | |
| 178 | -s f<name> | --swap-file <name> |
| 179 | Swap into file <name> instead of <mudlib>/LP_SWAP.<host> . |
| 180 | |
| 181 | -s c | --swap-compact |
| 182 | Reuse free space in the swap file immediately. |
| 183 | Giving this option results in smaller, but also more fragmented |
| 184 | swapfiles, and the swap performance may degrade. |
| 185 | |
| 186 | --max-malloc <size> |
| 187 | Restrict total memory allocations to <size> bytes. |
| 188 | A <size> of 0 or 'unlimited' removes any restriction.\n" |
| 189 | |
| 190 | --min-malloc <size> |
| 191 | --min-small-malloc <size> |
| 192 | Determine the sizes for the explicite initial large resp. small chunk |
| 193 | allocation. A size of 0 disables the explicite initial allocations. |
| 194 | |
| 195 | -r u<size> | --reserve-user <size> |
| 196 | -r m<size> | --reserve-master <size> |
| 197 | -r s<size> | --reserve-system <size> |
| 198 | Reserve <size> amount of memory for user/master/system allocations to |
| 199 | be held until main memory runs out. |
| 200 | |
| 201 | --filename-spaces |
| 202 | --no-filename-spaces |
| 203 | Allow/disallow the use of spaces in filenames. |
| 204 | |
| 205 | --strict-euids |
| 206 | --no-strict-euids |
| 207 | Enable/disable the enforced use of euids. |
| 208 | |
| 209 | --share-variables |
| 210 | --init-variables |
| 211 | Select how clones initialize their variables: |
| 212 | - by sharing the current values of their blueprint |
| 213 | - by initializing them afresh (using __INIT()). |
| 214 | |
| 215 | --pidfile <filename>\n" |
| 216 | Write the pid of the driver process into <filename>.\n" |
| 217 | |
| 218 | --tls-key <pathname> |
| 219 | Use <pathname> as the x509 keyfile, default is 'key.pem'. |
| 220 | If relative, <pathname> is interpreted relative to <mudlib>. |
| 221 | |
| 222 | --tls-cert <pathname> |
| 223 | Use <pathname> as the x509 certfile, default is 'cert.pem'. |
| 224 | If relative, <pathname> is interpreted relative to <mudlib>. |
| 225 | |
| 226 | --tls-trustfile <pathname> |
| 227 | Use <pathname> as the filename holding your trusted PEM certificates. |
| 228 | If relative, <pathname> is interpreted relative to <mudlib>. |
| 229 | |
| 230 | --tls-trustdirectory <pathname> |
| 231 | Use <pathname> as the directory where your trusted |
| 232 | PEM certificates reside, default is '/etc/ssl/certs'. |
| 233 | If relative, <pathname> is interpreted relative to <mudlib>. |
| 234 | |
| 235 | --wizlist-file <filename> |
| 236 | --no-wizlist-file |
| 237 | Read and save the wizlist in the named file (always interpreted |
| 238 | relative the mudlib); resp. don't read or save the wizlist. |
| 239 | |
| 240 | --gcollect-outfd <filename>|<num> |
| 241 | Garbage collector output (like a log of all reclaimed memory blocks) |
| 242 | is sent to <filename> (or inherited fd <num>) instead of stderr. |
| 243 | Only available if compiled with MALLOC_smalloc. |
| 244 | |
| 245 | --y|--yydebug |
| 246 | Enable debugging of the LPC compiler. |
| 247 | Only available if compiled with YYDEBUG. |
| 248 | |
| 249 | --random-seed <num> |
| 250 | Seed value for the random number generator. If not given, the |
| 251 | driver chooses a seed value on its own. |
| 252 | This option is for debugging. |
| 253 | |
| 254 | --check-state <lvl> |
| 255 | Perform a regular simplistic check of the virtual machine according |
| 256 | to <lvl>: |
| 257 | = 0: no check |
| 258 | = 1: once per backend loop |
| 259 | = 2: at various points in the backend loop |
| 260 | Only available if compiled with DEBUG. |
| 261 | |
| 262 | --check-refcounts |
| 263 | Every backend cycle, all refcounts in the system are checked. |
| 264 | SLOW! Only available if compiled with DEBUG. |
| 265 | |
| 266 | --gobble-descriptors <num> |
| 267 | <num> (more) filedescriptors are used up. You'll know when you need it. |
| 268 | Only available if compiled with DEBUG. |
| 269 | |
| 270 | --check-strings |
| 271 | Every backend cycle, all shared strings in the system are checked. |
| 272 | SLOW! Only available if compiled with DEBUG and CHECK_STRINGS. |
| 273 | |
| 274 | -V|--version |
| 275 | Print the version of the driver and exit. |
| 276 | |
| 277 | --options |
| 278 | Print the version and compilation options of the driver and exit. |
| 279 | |
| 280 | -h|-?|--help |
| 281 | Display a command help and exit. |
| 282 | |
| 283 | --longhelp |
| 284 | Display a long command help and exit. |
| 285 | |
| 286 | --args <filename> |
| 287 | The driver reads and parses the given file and treats its contents |
| 288 | as if given on the commandline right where the --args option |
| 289 | occured. The file itself can again contain --args options. |
| 290 | |
| 291 | |
| 292 | DESCRIPTION -- Argument Parser |
| 293 | The parser analyses the commandline arguments given with the driver |
| 294 | invocation and distinguishes 'options', which start with a '-', from |
| 295 | proper arguments. Options are further distinguished by their name and |
| 296 | may take an additional value. In general, options and arguments can be |
| 297 | givein in any order. |
| 298 | |
| 299 | Options are recognized in two forms. In the short form the option must |
| 300 | be given as a single '-' followed by a single letter. In the long form, |
| 301 | options start with '--' followed by a string of arbitrary length. The |
| 302 | short options are case sensitive, the long options aren't. |
| 303 | Most options can be specified in both the short and long form, but that |
| 304 | is not mandatory. Examples: '-r' and '--recursive'. |
| 305 | |
| 306 | If an option takes a value, it must follow the option immediately after |
| 307 | a separating space or '='. Additionally, the value for a short option |
| 308 | may follow the option without separator. Examples are: '-fMakefile', |
| 309 | '-f Makefile', '--file=Makefile' and '--file Makefile'. |
| 310 | |
| 311 | Short options may be collated into one argument, e.g. '-rtl', but |
| 312 | of these only the last may take a value. |
| 313 | |
| 314 | The option '--' marks the end of options. All following command arguments |
| 315 | are considered proper arguments even if they start with a '-' or '--'. |
| 316 | |
| 317 | The arguments are usually taken from the commandline; but the parser |
| 318 | is also able to read them from a textfiles, which can be nested. The |
| 319 | content of the textfiles is broken down into words delimited by whitespace, |
| 320 | which are then treated as given on the commandline at the place where |
| 321 | the instruction to read the textfile stood. |
| 322 | |
| 323 | The file parser recognizes simple double-quoted strings, which must be |
| 324 | contained on a single line. Additionally, the '#' character given by |
| 325 | itself is a comment marker - everthing after the '#' until the end |
| 326 | of the current line is ignored. |
| 327 | |
| 328 | HISTORY |
| 329 | LDMud 3.2.9 added the --max-thread-pending, --hostname, |
| 330 | --hostaddr, --args and --random-seed options. |
| 331 | LDMud 3.2.10 added the --filename-spaces options. |
| 332 | LDMud 3.3.378 added --share-variables, --init-variables. |
| 333 | LDMud 3.3.475/3.2.11 added --tls-key, --tls-cert. |
| 334 | LDMud 3.3.672/3.2.11 added --tls-trustfile, --tls-trustdirectory. |
| 335 | LDMud 3.3.677 added --max-mapping-keys. |