Added public files
Roughly added all public files. Probably missed some, though.
diff --git a/doc/driver/codestyle b/doc/driver/codestyle
new file mode 100644
index 0000000..78a05b6
--- /dev/null
+++ b/doc/driver/codestyle
@@ -0,0 +1,247 @@
+ The LPMud gamedriver is by nature the result of the cooperative work
+ of multiple programmers, often separated by large oceans and years
+ of time. In order to keep the appearance of the driver source consistent
+ (and with that maintainable), the following guidelines should be followed
+ for all code contributions.
+
+ For a quick start in how good driver source should look like, take
+ a look at comm.{c,h}, object.{c,h} and mapping.{c.h}.
+
+ The guidelines have a strong emphasis on code layout and commenting,
+ stemming from the fact that proper layout and comments gave the
+ incentive for LDMud in the first place. Right now, 50% of all lines
+ are comments, and that has been proven to be a Good Thing.
+
+ Any reader of the "real programmers don't write comments"-school
+ of thought is asked to take his or her incompetence elsewhere.
+
+
+Language
+--------
+ The language is ISO Standard C (also known as 'C89' or 'ANSI C').
+ Common compiler extensions or features from the new C99 standard are
+ permitted if their addition is transparent for other C89 compilers.
+ For example: the 'inline' keyword permitted through the use of the
+ INLINE macro; so are the Metrowerks-pragmas and GNU-attributes. Not
+ permitted are GNU's local functions.
+
+ System/Platform specifics are to be detected by the configure script
+ and provided with transparent implementations in port.{c,h} (or for
+ module-specific dependencies in the respective modules).
+
+ Adherence to the Standard has the following implications:
+
+ - All functions must be fully prototyped.
+ - Standard types like size_t, ssize_t or ptrdiff_t are to be used
+ whereever possible.
+ - Unixisms like
+ {
+ a = malloc(20);
+ b = malloc(20);
+ c = b-a;
+ }
+ are not legal and shouldn't be used.
+ - Don't make assumptions about the size of the base types (e.g.
+ a char might have more than 8 bits). If such an assumption
+ is unavoidable, comment it clearly and if possible add a test
+ to raise a compile or runtime error if the assumption is not met.
+
+
+Style
+-----
+ All modules (.c-files) have to have their interface in an accompaning
+ .h-file. The header file must be guarded against repeated inclusion
+ with the normal
+ #ifndef HEADERNAME_H
+ #define HEADERNAME_H 1
+ ...
+ #endif /* HEADERNAME_H */
+ construct. To use a module, its headerfile must be included - no random
+ 'extern' declarations.
+
+ Every module must include "driver.h" which in turn includes the
+ portability headers and provides common defines.
+
+ Use the driver-provided types and macros like Bool or p_int.
+
+ Code should be written defensively and readable. This is not the IOCCC.
+
+ No magic numbers - use #defines to give them names.
+
+ Add sanity checks where useful. If the checks are costly, enclose
+ them in a #ifdef DEBUG...#endif bracket.
+
+ Comment questionable code or opportunities for possible extensions with a
+ 'TODO: ...' comment. For multiline comments, use 'TODO::' on the second
+ and following lines (this makes reading a grep easier).
+
+ Comment temporary debug code with a 'DEBUG:' comment. Similar, debug
+ output should always begin with 'DEBUG:'.
+
+ Variable identifiers should start with a lowercase letter, function
+ identifiers may start with upper or lowercase, constant identifiers
+ should start with an uppercase letter. Macro identifiers should be
+ all UPPERCASE, other identifiers may be under_scored or SkudlyCaps.
+ Hungarian notation is accepted only in a very light form: pFoo for
+ pointers, ppFoo for pointer to pointers, iFoo for integer types,
+ sFoo for string pointers, aFoo for complex types - you get the
+ idea. But no alpzsFoo and friends.
+
+ f_xxx() function names are reserved for efun implementations.
+ typedef'd typenames should end in _t (e.g. 'mapping_t'), struct
+ names should end in _s (e.g. 'struct instrs_s').
+
+ Indentation is 4 spaces per level. No tab characters anywhere!
+
+ The indentation style is a variant of the 'Allman style':
+
+ if (foo)
+ {
+ ...body...
+ } /* if (foo) */
+
+ Note the comment at the closing brace!
+
+ One line bodies may be written as
+
+ if (foo) body;
+
+ or
+
+ if (foo)
+ body;
+
+ _if_ it improves the readability.
+
+ Similar, the typical layout of a function is:
+
+ static int
+ function_name ( arg1 , arg2)
+
+ /* Twiddle <arg1> with <arg2> and return the result.
+ */
+
+ {
+ ....
+ } /* function_name() */
+
+ If an expression (argument list, ...) extends over several, the first
+ literal element on a line should be an operator or syntactical marker:
+
+ if (condition1
+ && ( condition2
+ || condition3)
+ )
+
+ printf( "..."
+ , arg1, arg2, arg3
+ );
+
+ Be generous with whitespace - both horizontal and vertical.
+
+ [ The reasoning behind this style is to use the language elements
+ to create strong visual structures for the eyes to follow. By doing so,
+ the structure of the program becomes obvious without much
+ conscious thought.
+ ]
+
+
+Commenting
+----------
+ The comments also follow the idea of giving strong visual clues of
+ how the program is structured.
+
+ Horizontal lines should be created as
+
+ /*------...-------*/
+ /*======...=======*/
+ /* - - -... - - - */
+
+ The '---' line is the normal separator between the components of a
+ source file (includes, variable declarations, macro declarations,
+ the separate functions). The '===' line can be used to separate
+ larger sections of a source file (e.g. the lowlevel routines from
+ the efun implementations). '- -' lines, which usally span less than
+ the whole line, can be used to subdivide large functions (though then
+ it's often better to split the function into several small ones).
+
+ A '***' line is reserved for the end of every source file.
+
+ A '/* --- Subsection --- */' is also good to separate subsections.
+
+ Vertical lines are to be constructed as
+
+ /*
+ *
+ */
+
+ No box comments.
+
+ Every function must have a head comment explaining the meaning
+ of the arguments, what the function does, and the possible results.
+ For efun implementations, this comment should be identical to the
+ man page.
+
+ Within a function, every variable should be commented as
+
+ int foo; /* short comment */
+ int bar;
+ /* long comment which doesn't fit on one line.
+ */
+
+ The major steps in a function should be preceeded by a comment
+ explaining them. Also, wherever a critical design decision has
+ been made, a comment should line out the whats and whys:
+
+ /* Duplicate the stored arguments for the function call.
+ * (It's tempting to use the stored arguments directly
+ * in the last pass; however it's not guaranteed that
+ * the last pass actually comes this far.)
+ */
+
+
+ A typical file layout, commentwise, looks like this:
+
+ /*------------------------------------------------------
+ * Gamedriver Bouncing module.
+ *
+ * <reserved for future copyright notice>
+ *------------------------------------------------------
+ * 'Big picture' description of the module and its
+ * relation to the other gamedriver parts.
+ *
+ * Tricky design discussions also belong in here.
+ *------------------------------------------------------
+ */
+
+ #include "driver.h"
+ #include "typedefs.h"
+
+ #include <stdlib.h>
+
+ #include "bounce.h"
+ #include "backend.h"
+
+ /*--------------------------------------------------------*/
+
+ /* --- User information --- */
+ interactive_t *all_bouncers[MAX_PLAYERS];
+
+ /* --- Statistics --- */
+
+ p_int number_of_calls;
+
+ /*--------------------------------------------------------*/
+ void
+ add_bouncer (interactive_t *bouncer)
+
+ /* This function adds <bouncer> to the all_bouncers[].
+ */
+ {
+ int i; /* search index */
+
+ ....
+ } /* add_bouncer() */
+
+ /**********************************************************/
+
diff --git a/doc/driver/commandline b/doc/driver/commandline
new file mode 100644
index 0000000..6e197e9
--- /dev/null
+++ b/doc/driver/commandline
@@ -0,0 +1,60 @@
+NAME
+ commandline
+
+DESCRIPTION
+ The driver understands several command line options and
+ arguments.
+
+ -f<string>: When the master object is loaded and fully
+ operational after startup, the function flag()
+ with argument string is applied to the master
+ object for each occurence of -f in the command line.
+
+ -o : run in compat mode (thus sometimes also called
+ -o mode), instead of native mode. Note: the flag
+ is obsolete by now, the driver must be compiled
+ with the appropriate definitions in the config.h
+ instead.
+
+ -c : trace compilations.
+
+ -Dsymbol : Globally pre-#define symbol for preprocessor.
+
+ -D : without symbol, this logs specific trace messages
+ to /log/D_TRACE (if the driver was compiled for it)
+
+ -e : The number of occurences of the -e flag is
+ passed as argument to the epilog() function
+ in the master at startup time.
+
+ -N : Don't start the erq demon.
+
+ -M<master>: provide a different name for the master object.
+
+ -m<dir> : provide a different mudlib directory.
+
+ -ru<size> : set the size of the reserved user memory.
+ -rm<size> : set the size of the reserved master memory.
+ -rs<size> : set the size of the reserved system memory.
+
+ -E<cost> : set the maximum allowed evaluation cost.
+
+ --max_malloced : set maximum size of mallocable memory chunks.
+ --max_small_malloced : set max. size of mallocable memory chunks.
+
+ -u<port> : set the UDP port number for IMP communication.
+
+ -t : disable heart_beat and reset.
+
+ -d : run with debug.
+
+ -s<time> : Set the time between swapout attempts. -1 means
+ don't swap.
+
+ -y : If the driver has been compiled with YYDEBUG,
+ this will enable debug output for the LPC compiler.
+
+ <number> : the TCP port number to use for user connections.
+
+SEE ALSO
+ flag(M), epilog(M), native(C), imp(C)
diff --git a/doc/driver/copyright-issue b/doc/driver/copyright-issue
new file mode 100644
index 0000000..9f086a5
--- /dev/null
+++ b/doc/driver/copyright-issue
@@ -0,0 +1,252 @@
+The question of the Copyright and Terms of Use for the driver is an old
+one. Here is what I could salvage from the amylaar-users mailing list.
+Important is Jacob's mail I received in 1999 which essentially casts
+the current copyright terms in stone.
+
+ -- Lars (not /Lars)
+
+-------------------------------------------------------------------------------
+Date: Sat, 13 Nov 1993 03:11:29 +0100 (MET)
+From: amylaar@meolyon.hanse.de (Joern Rennecke)
+Subject: LPmud Copyright
+To: busey@ux1.cso.uiuc.edu (busey andrew), lars@cd.chalmers.se,
+ croes@swi.psy.uva.nl, gusar@uniwa.uwa.OZ.AU, duening@ibr.cs.tu-bs.de,
+ jacob@cd.chalmers.se, r_behren@informatik.uni-kl.de,
+ mud@alijku05.edvz.uni-linz.ac.at, alcaman@cs.tu-berlin.de
+
+Motivation of this letter:
+There seems to be a potential for muds that run on dedicated machines
+that charge fees from player to make the mud economically feasible.
+The Copyright file says that LPmud can freely used iff it is not for
+monetary gain. Now the debate what constitutes monetary gain and if
+an individual license is an license to break the copyright,
+is an interpretation of the license in Copyright or gives rights
+independent the restrictions in Copyright has become a normal flame
+war in the rec.games.mud.* groups. That is to say, one of the worst
+thinkable.
+
+To allow muds to charge fees to cover costs, without going through
+such debates every time, I suggest to amend the Copyright file
+with terms under witch such a mud is considered to comply to the
+'no monetary gain clause' .
+
+Explanation of the recipient list and some individual messages:
+
+Busey Andrew: wants to set up a mud that charges fees to cover costs.
+ If the below rules won't make it into the Copyright, you can regard this
+ as a license - of course only for the code written by me.
+Lars Pensj|: original author.
+ Please forward this letter to other authors that have contributed to 3.1.2
+ who have a say in the copyright.
+Felix A. Croes: wrote the non-corrupting indentation code for ed.
+Sean A Reith: wrote Mud-sprintf() .
+Lars Duening: wrote the Amiga port.
+Reimer Behrends: wrote mergesort based sort_array() .
+Herp: wrote get_object_actions() .
+Jacob Hallen: is one of the people involved with the CD driver; the email
+ address was in the news recently...
+ Please forward this letter to the person holding the copyright for the
+ UDP connectivity(unless it's yourself :-) .
+Alexander Weidt:
+ Please try to forward this letter to my brother...
+
+I hope to finally get terms which all autors can agree on that can be included
+into the Copyright file. I suggest group replies, so that we can get some
+kind of discussion going (unless there is immediate approval from all
+authors :-) . When you have objections, please try to point out what is
+wrong with these terms. Even better would it be if you had a solution
+to the problem.
+
+ Joern Rennecke (Amylaar)
+
+Proposed Terms:
+1. A LPmud may charge fees from players to cover running and machine costs.
+2. Running costs in these terms are the cost for the network connection,
+ electric power to operate the host machine, wear of backup media,
+ repair costs for the host machine, and cost for a bank account.
+ For the costs of a bank account to be considered runnung costs,
+ they must not habe been considered according to 8. , and the
+ institute has to be choosen with at least usual consideration on
+ terms and costs of the account and that there must be no affiliaton
+ with the institute.
+3. Money to cover running costs for a maximum of 18 month may be accumulated
+ in advance from fees to smoothe fluctation and to ensure stability of
+ the mud. The spare money has to be kept separate from personal money
+ and should be invested in trustee investment if liquidity allows.
+ If the mud is permanently put down, this money has to be refounded to the
+ playeres.
+4. Machine costs are costs for buying, installation and upgrade of the host
+ machine. The costs have to appear on a bona fide purchase / service
+ contract with a person/institution that is not affiliated with the
+ person who sets up the mud.
+ When the host machine is put out of use, or parts of it are removed for
+ other than technical reasons, are parts are nor re-inserted after the
+ technical resons for removal and not re-inserting have become void,
+ the current value of the machine that has put out of use/the removed
+ parts is to be subtracted from the machine costs.
+ If thus more money has been paid for machine costs than there are
+ currently, the surplus amount has to be refounded to the mud players.
+5. The machine cost share in the fee may not be more than 1/2400th
+ of the machine costs per month. If the mud has less than 100 players,
+ it may be up to machine costs / 24 / number of players, but not more than
+ 1/120th of the machine costs per month.
+6. When money has to be payed back to the mud players, only those that
+ have payed at least once a fee within the last 24 month are to be
+ considered. For these players, the money is distributed in the ratio
+ of the all fee shares ever payed to cover machine costs.
+7. All players pay equal fees.
+8. Banking costs that have to be paid by the mud administration and are
+ immediately connected to incoming money transactions can be subtracted
+ from the transferred amount before counting it as payment of fees,
+ provided that the institute was choosen with at least usual
+ consideration on terms and costs of the account, and that there is
+ no affiliaton with the institute.
+9. The amount of voluntary donations is unlimited. A donation is not
+ considered voluntary if it is connected with special features or
+ favours in the mud other than an hounarary mentioning of the donor,
+ or if the donor is made to believe that such a connection exists.
+ Reasonable measures have to be taken that there is no
+ misunderstanding on this point.
+
+Comments:
+3. You may not use the money of the mud to bridge personal inliquidity.
+ Don't gamble with other persons money, e.g. investing it in junk bonds.
+5. Fees should not be arbitrarily raised so that players can be driven
+ out. I considered a fixed minimal distributen of the costs to be
+ the best means to codify this.
+ Absolute figures are bound to become void by inflation.
+6. The 24 month period is introduced to allow to erease records of
+ clients after two years, and to keep overhead affordable.
+7. We don't want favourites to get a free lift, and others grudgingly
+ paying extra. If you think somebody needs free access, find someone
+ who pays for it, or make a found payed from voluntary donations.
+
+-------------------------------------------------------------------------------
+Date: Fri, 19 Nov 1993 17:10:44 +0100 (MET)
+From: Lars Pensj| <lars@cd.chalmers.se>
+Subject: Re: LPmud Copyright
+To: amylaar@meolyon.hanse.de (Joern Rennecke)
+Cc: busey@ux1.cso.uiuc.edu, lars@cd.chalmers.se, croes@swi.psy.uva.nl,
+ gusar@uniwa.uwa.OZ.AU, duening@ibr.cs.tu-bs.de, jacob@cd.chalmers.se,
+ r_behren@informatik.uni-kl.de, mud@alijku05.edvz.uni-linz.ac.at,
+ alcaman@cs.tu-berlin.de
+
+I agree that fix of the copyright is needed. I would prefer to use the
+Gnu Copyleft, as I don't care any longer if anyone makes money from it. The
+important thing is that it is free, which means noone will be able to make
+much money anyway.
+
+Any thoughts about it ?
+
+/Lars
+
+-------------------------------------------------------------------------------
+Date: Fri, 19 Nov 1993 20:14:10 +0100 (MET)
+From: Jacob Hallen <jacob@cd.chalmers.se>
+Subject: Re: LPmud Copyright
+To: amylaar@meolyon.hanse.de (Joern Rennecke)
+Cc: busey@ux1.cso.uiuc.edu, lars@cd.chalmers.se, croes@swi.psy.uva.nl,
+ gusar@uniwa.uwa.OZ.AU, duening@ibr.cs.tu-bs.de, jacob@cd.chalmers.se,
+ r_behren@informatik.uni-kl.de, mud@alijku05.edvz.uni-linz.ac.at,
+ alcaman@cs.tu-berlin.de
+
+> Jacob Hallen: is one of the people involved with the CD driver; the email
+> address was in the news recently...
+> Please forward this letter to the person holding the copyright for the
+> UDP connectivity(unless it's yourself :-) .
+
+I represent everyone involved in the CD driver. The UDP stuff is to be
+considered public domain. All other parts are covered by the non-profit clause.
+Code origination from me, Johan Andersson (Commander), Ronny Wikh (Mrpr),
+Lennart Augustsson (Marvin) is covered by it. We have no intention of
+allowing people to charge money for the usage of our driver, or borrowed
+pieces thereof.
+We consider the acceptance of volontary donations as fair practice, and we
+can accept the charging for the use of extra equipment needed to allow
+people to access the mud, as long as there is a reasonable way to access the
+mud without being charged. (Providing modem access at a cost while allowing
+free access over the internet is an example of such a setup.)
+
+My personal view is that an elaborate setup of terms like the one in the
+original letter is unreasonable. It is designed for a very specific set of
+circumstances. It is impossible to check and it is very bureaucratic.
+It does not have my support.
+
+Jacob Hallen
+
+-------------------------------------------------------------------------------
+Date: Sat, 20 Nov 1993 23:35:12 +0100 (MET)
+From: Multi User Dungeon <mud@alijku05.edvz.uni-linz.ac.at>
+Subject: Re: LPmud Copyright
+To: lars@cd.chalmers.se (Lars Pensj|)
+Cc: busey@ux1.cso.uiuc.edu, croes@swi.psy.uva.nl, gusar@uniwa.uwa.OZ.AU,
+ duening@ibr.cs.tu-bs.de, jacob@cd.chalmers.se,
+ r_behren@informatik.uni-kl.de, alcaman@cs.tu-berlin.de
+
+Lars> important thing is that it is free, which means noone will be able to make
+Lars> much money anyway.
+
+You are speaking about the GD,correct ? Normally, many a site uses an unmodified
+GD based upon which is a more or less heavily or not heavily Mudlib. Based upon
+this Mudlib is the work of the `wizards' ... Sorry for repeating known stuff.
+
+This makes most Muds differ from each other. So, the fact that the GD itself
+is free, doesn't imply that you won't make money.
+
+Another point to argue: maintainig a Mud takes time .. a LOT of time. Usually,
+doing so is not fun at all. I experienced that the more players you have, the
+less fun it is fore the adminstrators. You spend a lot of time coding,
+searching and fixing bugs ... and I think, this can be regarded as a
+service for players (... and players really can be a pain sometimes ...)
+Would it be legal to charge money for that ?
+
+Another thought: Internet Muds. They run on internet, usually on computers
+owned by a school or university, some with, some without the knowledge of
+the site adminstrators. Would it be legal to charge money when you run
+a Mud on equipment not owned by yourself ? And, even if you own the computer,
+do you pay for the internet link ? If not, I fear you must not charge money
+for a Mud without speaking with the network adminstrator since you are using
+the network components (router/bridges, even cables :-> ...) for free.
+
+How difficult is charging money in European Muds ? Not that I plan
+to do so for HM (it's closed for players currently anyway), but isn't there a
+big difference according to the "accounting mechanism" (ugh, bad english :-)
+that is used in the States ? I heard that it is much more easy to make
+financial transactions within the States. So, I suspect the "Mud money charging"
+discussion arrives from the US :-)
+
+Greetings, Herp (mud@mud.uni-linz.ac.at)
+
+------------------------------------------------------------------------------
+From jacob@cd.chalmers.se Sun Oct 24 17:02:53 1999
+Newsgroups: rec.games.mud.admin
+Subject: Re: Newsgroups
+From: jacob@cd.chalmers.se (Jacob Hallen)
+Date: 24 Oct 1999 16:02:53 GMT
+
+In article <380f817d.35916528@news.earthlink.net>,
+Lars Duening <lars@bearnip.com> wrote:
+>On Thu, 21 Oct 1999 12:11:36 -0700, Ilya
+><ilya@spam.free.gamecommandos.com> wrote:
+>
+>>Hey Lars, what hope is there, if any, of getting
+>>something going in the LP world, using LDmud or
+>>whatever, that can be used commercially?
+>
+>Unfortunately only slim hope: the parts written by the Genesis folks
+>are definitely non-commercial; but rewriting is difficult because
+>nobody remembers _which_ parts are concerned (and mailed requests
+>haven't been answered). And I haven't asked the other contributors
+>yet, either.
+
+I have a pretty good idea of who wrote what parts of the early version 3
+gamedrivers. All in all there have been about 30 people involved. Unless
+you recode the entire gamedriver from scratch, or build from assembled pieces
+with known copyright restrictions, there is no way you can come up with
+something that does not infringe on the rights of someone who will not
+allow commecial use.
+
+Jacob Hallén
+
+------------------------------------------------------------------------------
+
diff --git a/doc/driver/debugmalloc b/doc/driver/debugmalloc
new file mode 100644
index 0000000..8f78bae
--- /dev/null
+++ b/doc/driver/debugmalloc
@@ -0,0 +1,17 @@
+NAME
+ debugmalloc
+
+DESCRIPTION
+ This command is hardcoded into the driver.
+
+ Toggles the debug mode for the memory managment.
+ If the O_IS_WIZARD flag is used in the mudlib (i.e. if
+ set_is_wizard() was called), this command is allowed only for
+ users that have this flag set.
+
+HISTORY
+ Deactivated in 3.2.7 by default, it was effectless before anyway.
+
+SEE ALSO
+ malloc(D), status(D), memory(C), objects(C), debug_info(E),
+ set_is_wizard(E)
diff --git a/doc/driver/driver b/doc/driver/driver
new file mode 100644
index 0000000..40430e8
--- /dev/null
+++ b/doc/driver/driver
@@ -0,0 +1,15 @@
+NAME
+ driver
+
+DESCRIPTION
+ This directory contains descriptions of miscellaneous
+ internals of Amylaar's version of the LPC parser/interpreter,
+ that might be useful to know.
+
+ One thing described here are the special hardcoded commands
+ of the interpreter for querying the status of the memory
+ management.
+
+SEE ALSO
+ efun(E), applied(A), concepts(C), master(M), lpc(LPC),
+ malloc(D), status(D)
diff --git a/doc/driver/dumpallobj b/doc/driver/dumpallobj
new file mode 100644
index 0000000..24b884a
--- /dev/null
+++ b/doc/driver/dumpallobj
@@ -0,0 +1,49 @@
+NAME
+ dumpallobj
+
+DESCRIPTION
+ Write a list of all loaded or cloned objects into the file
+ OBJ_DUMP, and a list of all destructed objects into the
+ file DEST_OBJ_DUMP. Both files are located in the root directory of
+ the mudlib.
+
+ Warning: these files can be very large, and if the driver is low
+ on memory there is a certain crash probability.
+
+ If the O_IS_WIZARD flag is used in the mudlib (i.e. if
+ set_is_wizard() was called), this command is allowed only for
+ users that have this flag set.
+
+ For every live object, a line is written into the file with the
+ following information in the given order:
+ - object name
+ - size in memory, shared data counted only once
+ - size in memory if data wouldn't be shared
+ - number of references
+ - 'HB' if the object has a heartbeat, nothing if not.
+ - the name of the environment, or '--' if the object has no
+ environment
+ - in parentheses the number of execution ticks spent in this
+ object
+ - the swap status:
+ nothing if not swapped,
+ 'PROG SWAPPED' if only the program is swapped
+ 'VAR SWAPPED' if only the variabes are swapped
+ 'SWAPPED' if both program and variables are swapped
+ - the time the object was created
+
+ For every destructed object, a line is written into the file with the
+ following information in the given order:
+ - object name
+ - number of references
+ - 'NEW' if the object was destructed in this executiong
+ thread, nothing if it is older already.
+
+
+HISTORY
+ LDMud 3.2.9 added the DEST_OBJ_DUMP.
+ LDMud 3.2.10 added the object creation time to OBJ_DUMP.
+
+SEE ALSO
+ malloc(D), status(D), memory(C), objects(C), debug_info(E),
+ set_is_wizard(E)
diff --git a/doc/driver/invocation b/doc/driver/invocation
new file mode 100644
index 0000000..5760b46
--- /dev/null
+++ b/doc/driver/invocation
@@ -0,0 +1,335 @@
+NAME
+ driver/invocation
+
+PURPOSE
+ Description of the invocation of the gamedriver, especially of the command
+ arguments. This document describes the commandline version of the driver
+ only; non-commandline versions are platform specific and described in
+ the related documentation.
+
+DESCRIPTION
+ The driver is invoked from the commandline as other normal programs.
+ Neither the current directory nor the directory the executable is in need
+ to be in any special relation the directory of the mudlib. Once the driver
+ is running, it emits two streams of outputs:
+
+ - driver-related messages on stderr; this unfortunately includes
+ LPC compiler diagnostics
+ - LPC runtime-related messages in the logfile <mudlib>/<host>.parse.log
+ (the name can be changed).
+
+ It is possible to start the driver without any commandline arguments as
+ suitable defaults are specified at compile time. The invocation syntax
+ is:
+
+ driver [options] [<portnumber>]...
+
+ <portnumber> the number of the port the driver shall use to accept
+ connections. The maximum number of ports is determined by MAXNUMPORTS
+ in the source file config.h.
+
+ The options modify the behaviour of the gamedriver. Some of them are only
+ available if a certain compile-time option was enabled (typically in
+ the source file config.h). The following options are recognized:
+
+ -P|--inherit <fd-number>
+ Inherit filedescriptor <fd-number> from the parent process
+ as socket to listen for connections.
+ Only available if compiled with MAXNUMPORTS.
+
+ -u|--udp <portnumber>
+ Specify the <portnumber> for the UDP port, overriding the compiled-in
+ default.
+ Only available if compiled with CATCH_UDP_PORT.
+
+ -D|--define <macro>[=<text>]
+ Add <macro> (optionally to be expanded to <text>) to the list of
+ predefined macros known by the LPC compiler.
+
+ -E|--eval-cost <ticks>
+ Set the number of <ticks> available for one evaluation thread.
+ If 0, execution is unlimited.
+
+ -M|--master <filename>
+ Use <filename> for the master object.
+
+ -m|--mudlib <pathname>
+ Use <pathname> as the top directory of the mudlib.
+
+ --debug-file <filename>
+ Log all debug output in <filename> instead of
+ <mudlib>/<host>.debug.log .
+
+ --hostname <name>
+ Use <name> as hostname instead of what the system says.
+
+ --hostaddr <addr>
+ Use <addr> as address of this machine, instead of what the
+ system says. In particular this address will be used to open
+ the driver ports.
+
+ --no-compat
+ --compat
+ Select the mode (plain or compat) of the driver.
+ This choice does not affect the default name of the master object.
+
+ -d|--debug
+ Generate debug output; repeat the argument for even more output:
+ >= 1: log resets, clean ups, swaps, reception of urgend data,
+ telnet negotiation states.
+ check_a_lot_of_refcounts() on startup when swapping of
+ variables is disabled.
+ >= 2: log all add_message()s, name lookup failures, new players.
+ >= 3: progress of garbage collection
+ >= 4: even more junk from garbage collection
+
+ -c|--list-compiles
+ List the name of every compiled file on stderr.
+
+ -e|--no-preload
+ Pass a non-zero argument (the number of occurences of this option)
+ to master->preload(), which usually inhibits all preloads of castles
+ and other objects.
+
+ --erq <filename>
+ --erq "<filename> <erq args>"
+ Use <filename> instead of 'erq' as the basename of the ERQ executable.
+ If the name starts with a '/', it is take to be an absolute pathname,
+ otherwise it is interpreted relative to <bindir>. If not specified,
+ 'erq' is used as the executable name.
+
+ By enclosing the argument value in quotes, it is possible to pass
+ arguments (e.g. --execdir) to the erq. These arguments however must
+ not contain embedded spaces.
+
+ -N|--no-erq
+ Don't start the erq demon (if it would be started at all).
+
+ --alarm-time <seconds>
+ Set the granularity of call_out() and heartbeat timing. Minimum
+ value is 1.
+
+ --heart-interval <seconds>
+ Set the interval between two heartbeats. Minimum value is 1.
+
+ --sync-heart
+ All heartbeats occur at the same time (modulo granularity).
+
+ --async-heart
+ Heartbeats occur when they are due (modulo granularity).
+
+ -t|--no-heart
+ Disable heartbeats and call_outs.
+
+ -f|--funcall <word>
+ The lfun master->flag() is called with <word> as argument before the
+ gamedriver accepts netword connections.
+
+ --regexp pcre | traditional
+ Select the default regexp package.
+
+ --max-array <size>
+ The maximum number of elements an array can hold.
+ Set to 0, arrays of any size are allowed.
+
+ --max-mapping <size>
+ The maximum number of elements a mapping can hold.
+ Set to 0, mappings of any size are allowed.
+
+ --max-mapping-keys <size>
+ The maximum number of entries a mapping can hold.
+ Set to 0, mappings of any size are allowed.
+
+ --max-callouts <size>
+ The maximum number of callouts at one time.
+ Set to 0, any number is allowed.
+
+ --max-bytes <size>
+ The maximum number of bytes one read_bytes()/write_bytes() call
+ can handle.
+ Set to 0, reads and writes of any size are allowed.
+
+ --max-file <size>
+ The maximum number of bytes one read_file()/write_file() call
+ can handle.
+ Set to 0, reads and writes of any size are allowed.
+
+ --max-thread-pending <size>\n"
+ The maximum number of bytes to be kept pending by the socket write
+ thread.
+ Set to 0, an unlimited amount of data can be kept pending.
+
+ This option is ignored if pthreads are not used.
+
+ --cleanup-time <time>
+ The idle time in seconds for an object before the driver tries to
+ clean it up. It should be substantially longer than the reset time.
+ A time <= 0 disables the cleanup mechanism.
+
+ --reset-time <time>
+ The time in seconds before an object is reset. A time <= 0 disables
+ the reset mechanism.
+
+ -s <time> | --swap-time <time>
+ -s v<time> | --swap-variables <time>
+ Time in seconds before an object (or its variables) are swapped out.
+ A time less or equal 0 disables swapping.
+
+ -s f<name> | --swap-file <name>
+ Swap into file <name> instead of <mudlib>/LP_SWAP.<host> .
+
+ -s c | --swap-compact
+ Reuse free space in the swap file immediately.
+ Giving this option results in smaller, but also more fragmented
+ swapfiles, and the swap performance may degrade.
+
+ --max-malloc <size>
+ Restrict total memory allocations to <size> bytes.
+ A <size> of 0 or 'unlimited' removes any restriction.\n"
+
+ --min-malloc <size>
+ --min-small-malloc <size>
+ Determine the sizes for the explicite initial large resp. small chunk
+ allocation. A size of 0 disables the explicite initial allocations.
+
+ -r u<size> | --reserve-user <size>
+ -r m<size> | --reserve-master <size>
+ -r s<size> | --reserve-system <size>
+ Reserve <size> amount of memory for user/master/system allocations to
+ be held until main memory runs out.
+
+ --filename-spaces
+ --no-filename-spaces
+ Allow/disallow the use of spaces in filenames.
+
+ --strict-euids
+ --no-strict-euids
+ Enable/disable the enforced use of euids.
+
+ --share-variables
+ --init-variables
+ Select how clones initialize their variables:
+ - by sharing the current values of their blueprint
+ - by initializing them afresh (using __INIT()).
+
+ --pidfile <filename>\n"
+ Write the pid of the driver process into <filename>.\n"
+
+ --tls-key <pathname>
+ Use <pathname> as the x509 keyfile, default is 'key.pem'.
+ If relative, <pathname> is interpreted relative to <mudlib>.
+
+ --tls-cert <pathname>
+ Use <pathname> as the x509 certfile, default is 'cert.pem'.
+ If relative, <pathname> is interpreted relative to <mudlib>.
+
+ --tls-trustfile <pathname>
+ Use <pathname> as the filename holding your trusted PEM certificates.
+ If relative, <pathname> is interpreted relative to <mudlib>.
+
+ --tls-trustdirectory <pathname>
+ Use <pathname> as the directory where your trusted
+ PEM certificates reside, default is '/etc/ssl/certs'.
+ If relative, <pathname> is interpreted relative to <mudlib>.
+
+ --wizlist-file <filename>
+ --no-wizlist-file
+ Read and save the wizlist in the named file (always interpreted
+ relative the mudlib); resp. don't read or save the wizlist.
+
+ --gcollect-outfd <filename>|<num>
+ Garbage collector output (like a log of all reclaimed memory blocks)
+ is sent to <filename> (or inherited fd <num>) instead of stderr.
+ Only available if compiled with MALLOC_smalloc.
+
+ --y|--yydebug
+ Enable debugging of the LPC compiler.
+ Only available if compiled with YYDEBUG.
+
+ --random-seed <num>
+ Seed value for the random number generator. If not given, the
+ driver chooses a seed value on its own.
+ This option is for debugging.
+
+ --check-state <lvl>
+ Perform a regular simplistic check of the virtual machine according
+ to <lvl>:
+ = 0: no check
+ = 1: once per backend loop
+ = 2: at various points in the backend loop
+ Only available if compiled with DEBUG.
+
+ --check-refcounts
+ Every backend cycle, all refcounts in the system are checked.
+ SLOW! Only available if compiled with DEBUG.
+
+ --gobble-descriptors <num>
+ <num> (more) filedescriptors are used up. You'll know when you need it.
+ Only available if compiled with DEBUG.
+
+ --check-strings
+ Every backend cycle, all shared strings in the system are checked.
+ SLOW! Only available if compiled with DEBUG and CHECK_STRINGS.
+
+ -V|--version
+ Print the version of the driver and exit.
+
+ --options
+ Print the version and compilation options of the driver and exit.
+
+ -h|-?|--help
+ Display a command help and exit.
+
+ --longhelp
+ Display a long command help and exit.
+
+ --args <filename>
+ The driver reads and parses the given file and treats its contents
+ as if given on the commandline right where the --args option
+ occured. The file itself can again contain --args options.
+
+
+DESCRIPTION -- Argument Parser
+ The parser analyses the commandline arguments given with the driver
+ invocation and distinguishes 'options', which start with a '-', from
+ proper arguments. Options are further distinguished by their name and
+ may take an additional value. In general, options and arguments can be
+ givein in any order.
+
+ Options are recognized in two forms. In the short form the option must
+ be given as a single '-' followed by a single letter. In the long form,
+ options start with '--' followed by a string of arbitrary length. The
+ short options are case sensitive, the long options aren't.
+ Most options can be specified in both the short and long form, but that
+ is not mandatory. Examples: '-r' and '--recursive'.
+
+ If an option takes a value, it must follow the option immediately after
+ a separating space or '='. Additionally, the value for a short option
+ may follow the option without separator. Examples are: '-fMakefile',
+ '-f Makefile', '--file=Makefile' and '--file Makefile'.
+
+ Short options may be collated into one argument, e.g. '-rtl', but
+ of these only the last may take a value.
+
+ The option '--' marks the end of options. All following command arguments
+ are considered proper arguments even if they start with a '-' or '--'.
+
+ The arguments are usually taken from the commandline; but the parser
+ is also able to read them from a textfiles, which can be nested. The
+ content of the textfiles is broken down into words delimited by whitespace,
+ which are then treated as given on the commandline at the place where
+ the instruction to read the textfile stood.
+
+ The file parser recognizes simple double-quoted strings, which must be
+ contained on a single line. Additionally, the '#' character given by
+ itself is a comment marker - everthing after the '#' until the end
+ of the current line is ignored.
+
+HISTORY
+ LDMud 3.2.9 added the --max-thread-pending, --hostname,
+ --hostaddr, --args and --random-seed options.
+ LDMud 3.2.10 added the --filename-spaces options.
+ LDMud 3.3.378 added --share-variables, --init-variables.
+ LDMud 3.3.475/3.2.11 added --tls-key, --tls-cert.
+ LDMud 3.3.672/3.2.11 added --tls-trustfile, --tls-trustdirectory.
+ LDMud 3.3.677 added --max-mapping-keys.
diff --git a/doc/driver/malloc b/doc/driver/malloc
new file mode 100644
index 0000000..7fb2722
--- /dev/null
+++ b/doc/driver/malloc
@@ -0,0 +1,12 @@
+NAME
+ malloc
+
+DESCRIPTION
+ This command is hardcoded into the driver's input parser.
+ It shows the statistics of the memory management module.
+
+HISTORY
+ Since 3.2.7, 'status malloc' has the same effect.
+
+SEE ALSO
+ status(D), memory(C), debug_info(E)
diff --git a/doc/driver/opcdump b/doc/driver/opcdump
new file mode 100644
index 0000000..b75ea68
--- /dev/null
+++ b/doc/driver/opcdump
@@ -0,0 +1,13 @@
+NAME
+ opcdump
+
+DESCRIPTION
+ If the driver was compiled to do opcode profiling, this command
+ will save the collected profiling information into the file /OPC_DUMP.
+ If the O_IS_WIZARD flag is used in the mudlib (i.e. if
+ set_is_wizard() was called), this command is allowed only for
+ users that have this flag set.
+
+SEE ALSO
+ malloc(D), status(D), memory(C), objects(C), debug_info(E),
+ set_is_wizard(E)
diff --git a/doc/driver/predefined b/doc/driver/predefined
new file mode 100644
index 0000000..17a7eb0
--- /dev/null
+++ b/doc/driver/predefined
@@ -0,0 +1,130 @@
+NAME
+ predefined - predefined #defines by the parser
+
+DESCRIPTION
+ Several preprocessor macros are pre#defined by the parser,
+ to provide information about parser version, compile time
+ options and parser invocation options:
+
+ LPC3 : always defined.
+ __LDMUD__ : always defined.
+ __EUIDS__ : always (for compatibility).
+ COMPAT_FLAG : defined if the driver runs in compat mode.
+ __COMPAT_MODE__ : ditto
+ __STRICT_EUIDS__: defined if strict euid usage is enforced.
+ __FILENAME_SPACES__: defined if filenames may contain spaces.
+
+ __MASTER_OBJECT__ : the name of the master object (in compat mode
+ without leading '/').
+ __FILE__ : the name of the compiled file (in compat mode
+ without leading '/').
+ __LINE__ : the current line number.
+ __FUNCTION__ : the current function name.
+ __DIR__ : the directory path of the compiled file (in
+ compat mode without leading '/').
+ __PATH__(n) : the directory path of the compiled file without
+ the <n> trailing elements (in compat mode without
+ leading '/').
+ __VERSION__ : the version string of the driver.
+ __VERSION_MAJOR__ : the major version number of the driver.
+ __VERSION_MINOR__ : the minor version number of the driver.
+ __VERSION_MICRO__ : the micro version number of the driver.
+ __VERSION_PATCH__ : the patchlevel of the driver; a 0 here means
+ 'no patchlevel'.
+ __VERSION_COMMITID__ : the commit ID of the source of the driver
+ (attention: it might be <unknown>, if the driver
+ was not compiled from a git repository)
+ __VERSION_LOCAL__ : the (optional) LOCAL_LEVEL, the user has defined.
+
+
+ __DOMAIN_NAME__ : the domain the host is part of.
+ __HOST_IP_NUMBER__ : the hosts IP number (as a string).
+ __HOST_NAME__ : the full hostname.
+ __MAX_RECURSION__ : the max count of nested function calls
+ (this is config.h:MAX_USER_TRACE).
+ __MAX_EVAL_COST__ : the max evaluation cost.
+ __RESET_TIME__ : default interval time between object resets.
+ __CLEANUP_TIME__ : default interval time between object cleanups.
+ __ALARM_TIME__ : the configured timing granularity.
+ __HEART_BEAT_INTERVAL__: the configured heartbeat time.
+ __SYNCHRONOUS_HEART_BEAT__: defined if synchronous heartbeats are
+ enabled.
+ __MAX_COMMAND_LENGTH__: the maximum length a command can have.
+ __EFUN_DEFINED__(name) : if the efun 'name' exists, this
+ macro evaluates to " 1 ", else to " 0 ".
+ __DRIVER_LOG__ : the name of the default debug.log file (within
+ the mudlib); undefined if a different name
+ has been specified on the commandline.
+ __WIZLIST__ : the name of the (mudlib) file from where the
+ driver read the initial WIZLIST information.
+ It is undefined if the driver was configured
+ to not read the information.
+ __MAX_MALLOC__ : the internal upper limit for total memory
+ usage.
+ __INT_MAX__ : the largest integer number
+ __INT_MIN__ : the smallest integer number
+ __FLOAT_MAX__ : the largest (positive) float number
+ __FLOAT_MIN__ : the smallest (positive) float number
+
+ __LPC_NOSAVE__ : always defined
+ __LPC_STRUCTS__ : defined when struct support is enabled.
+ Once structs are fully supported, this macro
+ will always be defined.
+ __LPC_INLINE_CLOSURES__: defined when the 'real' inline closures
+ are enabled.
+ __LPC_ARRAY_CALLS__: call_other()s on arrays of objects enabled.
+ __BOOT_TIME__ : the time() the driver was started.
+
+ If the ERQ is supported, the following macros are defined:
+
+ __ERQ_MAX_SEND__ : the max size of the send buffer
+ __ERQ_MAX_REPLY__ : the max size of the reply buffer
+
+ The following macros are defined if their associated package
+ has been compiled into the driver:
+
+ __IDNA__ : support for IDNA
+ __IPV6__ : support for IP v.6
+ __MYSQL__ : support for mySQL
+ __PGSQL__ : support for PostgreSQL
+ __SQLITE__ : support for SQLite 3.
+ __XML_DOM__ : support for XML parsing.
+ __JSON__ : support for JSON parsing/serializing.
+ __MCCP__: support for MCCP http://www.randomly.org/projects/MCCP
+ __ALISTS__: support for alists
+ __PCRE__: support for PCRE
+ __TLS__: support for TLS (internal)
+ __GNUTLS__: if __TLS__: TLS support provided by GnuTLS.
+ __OPENSSL__: if __TLS__: TLS support provided by OpenSSL.
+ __GCRYPT__: cryptographic routines provided by libgcrypt.
+ __DEPRECATED__: support for obsolete and deprecated efuns.
+
+
+HISTORY
+ 3.2.1 added __DOMAIN_NAME__, __HOST_IP_NUMBER__, __HOST_NAME__,
+ __MAX_RECURSION__, __EFUN_DEFINED__().
+ 3.2.5 added __COMPAT_MODE__, __NATIVE_MODE__, __EUIDS__,
+ __ERQ_MAX_SEND__ and __ERQ_MAX_REPLY__.
+ 3.2.6 added __MAX_EVAL_COST__.
+ 3.2.7 added __STRICT_EUIDS__ and made __EUIDS__ standard.
+ 3.2.8 added __IPV6__, __LPC_NOSAVE__, __DIR__, __PATH__().
+ 3.2.9 added __LDMUD__, __MYSQL__, __DEPRECATED__, __VERSION_MAJOR__,
+ __VERSION_MINOR__, __VERSION_MICRO__, __VERSION_PATCH__,
+ __INT_MAX__, __INT_MIN__, __FLOAT_MIN__, __FLOAT_MAX__,
+ __CATCH_EVAL_COST__, __MASTER_EVAL_COST__, __RESET_TIME__,
+ __CLEANUP_TIME__, __DRIVER_LOG__, and __WIZLIST__.
+ 3.2.10 added __MAX_MALLOC__, __MSDOS_FS__, __LPC_ARRAY_CALLS__
+ and __FILENAME_SPACES__.
+ 3.3 made __LPC_NOSAVE__ always defined and added __ALISTS__,
+ __MCCP__, __LPC_STRUCTS__, __LPC_INLINE_CLOSURES__, __PGSQL__,
+ __PTHREADS__, __TLS__, __BOOT_TIME__, __ALARM_TIME__,
+ __HEART_BEAT_INTERVAL__, __SYNCHRONOUS_HEART_BEAT__, and __PCRE__.
+ 3.3.713 added __IDNA__, __SQLITE__.
+ 3.3.714 added __OPENSSL__, __GNUTLS__.
+ 3.3.718 added __XML_DOM__.
+ 3.3.719 removed __PTHREADS__, AMIGA, MSDOS_FS, __BEOS__
+ and added __GCRYPT__.
+ 3.3.721 added __FUNCTION__.
+
+SEE ALSO
+ pragma(LPC), preprocessor(LPC)
diff --git a/doc/driver/showsmallnewmalloced b/doc/driver/showsmallnewmalloced
new file mode 100644
index 0000000..17e2252
--- /dev/null
+++ b/doc/driver/showsmallnewmalloced
@@ -0,0 +1,17 @@
+NAME
+ showsmallnewmalloced
+
+DESCRIPTION
+ This command is hardcoded into the driver.
+
+ Shows a list of recently allocated small memory blocks.
+ If the O_IS_WIZARD flag is used in the mudlib (i.e. if
+ set_is_wizard() was called), this command is allowed only for
+ users that have this flag set.
+
+HISTORY
+ Deactivated in 3.2.7 by default.
+
+SEE ALSO
+ malloc(D), status(D), memory(C), objects(C), debug_info(E),
+ set_is_wizard(E)
diff --git a/doc/driver/status b/doc/driver/status
new file mode 100644
index 0000000..79759dd
--- /dev/null
+++ b/doc/driver/status
@@ -0,0 +1,18 @@
+NAME
+ status
+ status tables
+ status swap
+ status malloc
+
+DESCRIPTION
+ This command is hardcoded into the drivers input routine.
+ It displays information about the run status of the system.
+ If the O_IS_WIZARD flag is used in the mudlib (i.e. if
+ set_is_wizard() was called), this command is allowed only for
+ users that have this flag set.
+
+HISTORY
+ 3.2.7 added the 'status malloc' variant.
+
+SEE ALSO
+ malloc(D), memory(C), objects(C), debug_info(E), set_is_wizard(E)