blob: 5760b465922762c3e49d3ca833875a6b8f0afd6c [file] [log] [blame]
MG Mud User88f12472016-06-24 23:31:02 +02001NAME
2 driver/invocation
3
4PURPOSE
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
10DESCRIPTION
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
292DESCRIPTION -- 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
328HISTORY
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.