Added public files
Roughly added all public files. Probably missed some, though.
diff --git a/doc/master/compile_object b/doc/master/compile_object
new file mode 100644
index 0000000..1b55658
--- /dev/null
+++ b/doc/master/compile_object
@@ -0,0 +1,11 @@
+SYNOPSIS
+ object compile_object(string filename)
+
+DESCRIPTION
+ This function is caled if the interpreter cannot find the
+ file for an object to be loaded. The master object has now
+ the opportunity to return an object that will then serve as if
+ compiled from the given filename.
+
+ If 0 is returned, the usual ``Could not load descr for'' error
+ will occur.
diff --git a/doc/master/connect b/doc/master/connect
new file mode 100644
index 0000000..a1c7315
--- /dev/null
+++ b/doc/master/connect
@@ -0,0 +1,13 @@
+SYNOPSIS
+ object connect(void)
+
+DESCRIPTION
+ Return a login object that the requested connection should be
+ bound to. Note that the connection is not bound yet.
+
+ The lfun logon() will be applied to the login object after
+ binding the connection to it. That lfun has to return != 0 to
+ indicate success.
+
+SEE ALSO
+ logon(A), disconnect(M), interactive(E), exec(E)
diff --git a/doc/master/dangling_lfun_closure b/doc/master/dangling_lfun_closure
new file mode 100644
index 0000000..6bfaeb5
--- /dev/null
+++ b/doc/master/dangling_lfun_closure
@@ -0,0 +1,26 @@
+SYNOPSIS
+ void dangling_lfun_closure()
+
+DESCRIPTION
+ Handle a dangling lfun-closure.
+
+ This is called when the gamedriver executes a closure using a
+ vanished lfun. A proper handling is to raise a runtime error.
+
+ Technical:
+ Upon replacing programs (see efun replace_program()), any
+ existing lambda closures of the object are adjusted to the
+ new environment. If a closure uses a lfun which vanished in
+ the replacement process, the reference to this lfun is
+ replaced by a reference to this function. The error will
+ then occur when the execution of the adjusted lambda reaches
+ the point of the lfun reference. There are two reasons for
+ the delayed handling. First is that the program replacement
+ and with it the closure adjustment happens at the end of a
+ backend cycle, outside of any execution thread: noone would
+ see the error at this time. Second, smart closures might
+ know/recognize the program replacement and skip the call to
+ the vanished lfun.
+
+SEE ALSO
+ closures(LPC)
diff --git a/doc/master/disconnect b/doc/master/disconnect
new file mode 100644
index 0000000..f7a9f3d
--- /dev/null
+++ b/doc/master/disconnect
@@ -0,0 +1,13 @@
+SYNOPSIS
+ void disconnect(object ob)
+
+DESCRIPTION
+ Handle the loss of the IP connection for the (formerly)
+ interactive object ob. The connection can be lost because the
+ the underlying transport connection was lost (``netdead''), or
+ because of a call to exec() or remove_interactive(). The
+ connection will be unbound upon return from this call.
+
+SEE ALSO
+ connect(M), remove_player(M), remove_interactive(E), exec(E),
+ interactive(E)
diff --git a/doc/master/epilog b/doc/master/epilog
new file mode 100644
index 0000000..eb51d75
--- /dev/null
+++ b/doc/master/epilog
@@ -0,0 +1,24 @@
+SYNOPSIS
+ void epilog(void) /* compat in 3.2 */
+ string *epilog(int eflag) /* !compat or 3.2.1 */
+
+DESCRIPTION
+ Perform final actions before opening the system to users.
+ The semantics of this function differ for compat and !compat
+ mode, and between 3.2 and 3.2.1.
+
+ Compat in 3.2: the objects from the INIT_FILE (#defined to
+ "room/init_file" at compile time in the parser) are already
+ loaded at this time. Normally there is nothing left to do for
+ this function.
+
+ !Compat and 3.2.1: the argument is the number of -e options that were
+ given to the parser on the commandline. Normally it is just 0
+ or 1. The function should return an array of strings, which
+ traditionally denote the objects to be preloaded with
+ master->preload(). Any other return value is interpreted as
+ ``no object to preload''. The resulting strings will be passed
+ one at a time as arguments to preload().
+
+SEE ALSO
+ preload(M), master(M)
diff --git a/doc/master/external_master_reload b/doc/master/external_master_reload
new file mode 100644
index 0000000..57913f0
--- /dev/null
+++ b/doc/master/external_master_reload
@@ -0,0 +1,10 @@
+SYNOPSIS
+ void external_master_reload()
+
+DESCRIPTION
+ Master was reloaded on external request by SIGUSR1.
+ It will be called after inaugurate_master() of course.
+ If you plan to do additional magic here, you're welcome.
+
+SEE ALSO
+ inaugurate_master(M)
diff --git a/doc/master/flag b/doc/master/flag
new file mode 100644
index 0000000..e04e91d
--- /dev/null
+++ b/doc/master/flag
@@ -0,0 +1,41 @@
+SYNOPSIS
+ void flag(string arg)
+
+DESCRIPTION
+ Evaluate an argument given as option '-f' to the driver.
+ If several '-f' options are given, this function will be
+ called sequentially with all given arguments.
+ This function can be used to pass the master commands via
+ arguments to the driver. This is useful when building a new
+ mudlib from scratch. It is called only when the system is
+ started.
+
+EXAMPLE
+ // The code given implements these commands:
+ // '-fcall <ob> <fun> <arg>': call function <fun> in object <ob> with
+ // argument <arg>.
+ // '-fshutdown': shutdown the system immediately.
+ // Thus, starting the driver as
+ // 'parse "-fcall foo bar Yow!" -fshutdown' would
+ // first do foo->bar("Yow!") and then shut down the system.
+
+ {
+ string obj, fun, rest;
+
+ if (arg == "shutdown")
+ {
+ shutdown();
+ return;
+ }
+ if (sscanf(arg, "call %s %s %s", obj, fun, rest) >= 2)
+ {
+ write(obj+"->"+fun+"(\""+rest+"\") = ");
+ write(call_other(obj, fun, rest));
+ write("\n");
+ return;
+ }
+ write("master: Unknown flag "+arg+"\n");
+ }
+
+SEE ALSO
+ master(M)
diff --git a/doc/master/get_bb_uid b/doc/master/get_bb_uid
new file mode 100644
index 0000000..5a4dc8b
--- /dev/null
+++ b/doc/master/get_bb_uid
@@ -0,0 +1,18 @@
+SYNOPSIS
+ string get_bb_uid(void)
+
+DESCRIPTION
+ Is called to get the ``backbone id''. Objects whose creator is
+ the backbone id are ``trusted'', and will automagically get
+ the uid and euid of the object that caused to load or clone
+ them.
+
+ The backbone id is also temporary given to objects while being
+ called via process_string().
+
+HISTORY
+ Since 3.2.1, get_bb_uid() is needed just for process_string()
+ if no this_object() is present.
+
+SEE ALSO
+ uids(C), creator_file(M), creator(E), get_root_id(M)
diff --git a/doc/master/get_ed_buffer_save_file_name b/doc/master/get_ed_buffer_save_file_name
new file mode 100644
index 0000000..50a23c3
--- /dev/null
+++ b/doc/master/get_ed_buffer_save_file_name
@@ -0,0 +1,22 @@
+SYNOPSIS
+ string get_ed_buffer_save_object_name(string edited_file)
+
+DESCRIPTION
+ This function is called when an interactive user object is
+ destructed or looses connection through remove_interactive()
+ while editing with ed() the file edite_file (emergency save).
+ this_player() is set to the object that loosing connection.
+ The function should return a file name for the emergency save
+ file.
+
+EXAMPLE
+ string get_ed_buffer_save_object_name(string file) {
+ return "/players/"+getuid(this_player())+"/.dead_ed_files/"
+ + explode(file, "/")[<1];
+ }
+
+ This breaks up file into its components and stores it in the
+ user's emergency save directory under the file's basename.
+
+SEE ALSO
+ ed(E), destruct(E), remove_interactive(E), valid_write(M)
diff --git a/doc/master/get_master_uid b/doc/master/get_master_uid
new file mode 100644
index 0000000..a0c6737
--- /dev/null
+++ b/doc/master/get_master_uid
@@ -0,0 +1,12 @@
+SYNOPSIS
+ string get_master_uid(void)
+
+DESCRIPTION
+ Return the string to be used as root-uid.
+ Under !native, the function is expendable.
+
+HISTORY
+ Introduced in 3.2.1@40 replacing get_root_uid().
+
+SEE ALSO
+ get_bb_uid(M), get_master_uid(M), uids(C), creator_file(M), creator(E)
diff --git a/doc/master/get_simul_efun b/doc/master/get_simul_efun
new file mode 100644
index 0000000..88adba0
--- /dev/null
+++ b/doc/master/get_simul_efun
@@ -0,0 +1,24 @@
+SYNOPSIS
+ mixed get_ simul_efun(void) // 3.2
+ string|string* get_simul_efun(void) // 3.2.1
+
+DESCRIPTION
+ Load the simul_efun object(s) and return one or more paths of it.
+// Note that the object(s) must be loaded by this function!
+//
+// When you return an array of strings, the first string is taken as path
+// to the simul_efun object, and all other paths are used for backup
+// simul_efun objects to call simul_efuns that are not present in the
+// main simul_efun object. This allows to remove simul_efuns at runtime
+// without getting errors from old compiled programs that still use the
+// obsolete simul_efuns. A side use of this mechanism is to provide
+// a 'spare' simul_efun object in case the normal one fails to load.
+//
+ Should return either the object_name of the simul_efun object as
+ a string, or an array containing as first element a string
+ with the file name of the simul_efun object and the following
+ elements strings with file names of alternate simul_efun
+ objects that will be used if the first one cannot be loaded.
+
+SEE ALSO
+ simul_efun(C)
diff --git a/doc/master/get_wiz_name b/doc/master/get_wiz_name
new file mode 100644
index 0000000..6056965
--- /dev/null
+++ b/doc/master/get_wiz_name
@@ -0,0 +1,13 @@
+SYNOPSIS
+ string get_wiz_name(string file)
+
+DESCRIPTION
+ Argument is a file name, which we want to get the owner of.
+ This used for the wizlist, to determine who gets the score for
+ the file being used.
+
+ For 3.2.1, it is used only to score errors to the right wizard.
+
+SEE ALSO
+ wizlist(E), get_wiz_info(E), query_real_name(A),
+ query_creator(M), getuid(E)
diff --git a/doc/master/handle_external_signal b/doc/master/handle_external_signal
new file mode 100644
index 0000000..6fe81ef
--- /dev/null
+++ b/doc/master/handle_external_signal
@@ -0,0 +1,26 @@
+SYNOPSIS
+ #include <signals.h>
+
+ int handle_external_signal(int signal)
+
+DESCRIPTION
+ If the driver receives a signal from the OS it forwards it to the
+ mudlib master by calling this function. The signal received by the
+ driver is given in <signal> and may be one of the following:
+ SIGHUP, SIGINT, SIGTERM, SIGUSR1, SIGUSR2.
+
+ If this function returns != 0, the driver will assume the signal has
+ been dealt with and take NO further action.
+ The exception is SIGTERM, which can't be handled. The driver will
+ perform a graceful shutdown of the game after this function returns.
+
+ If the master does not handle the signal (returns 0 or this function
+ doe not exit), the driver will perform the following default actions:
+
+ SIGHUP: begin a graceful shutdown
+ SIGINT: send itself an unhandled SIGINT. This usually causes an
+ immediate and non-graceful shutdown.
+ SIGUSR1: the driver will reload the master object
+ SIGUSR2: the driver will re-open its debug log file
+ (this will happen the next time the driver writes to it)
+
diff --git a/doc/master/heart_beat_error b/doc/master/heart_beat_error
new file mode 100644
index 0000000..d4d15f2
--- /dev/null
+++ b/doc/master/heart_beat_error
@@ -0,0 +1,24 @@
+SYNOPSIS
+ mixed heart_beat_error(object culprit, string err, string prg,
+ string curobj, int line)
+
+DESCRIPTION
+ This function is called when a runtime error occurs while
+ executing the heart_beat() function of the object culprit. prg
+ is program where the actual error happened, in object curobj
+ at the given line.
+
+ At time of call, the heart_beat has been turned off.
+ Return anything != 0 to restart the heart_beat in culprit.
+
+ If culprit is a user, it should at least get the message ``You
+ have no heartbeat''. A more advanced handling would destruct
+ the offending object curobj and and allow the heartbeat to
+ restart.
+
+ Note that prg denotes the program actually executed (which
+ might be an inherited one) whereas curobj is just the
+ offending object.
+
+SEE ALSO
+ set_heart_beat(E), heart_beat(A), runtime_error(M)
diff --git a/doc/master/inaugurate_master b/doc/master/inaugurate_master
new file mode 100644
index 0000000..85c9526
--- /dev/null
+++ b/doc/master/inaugurate_master
@@ -0,0 +1,30 @@
+SYNOPSIS
+ void inaugurate_master(int arg)
+
+DESCRIPTION
+ This function is called in the master object after it has been
+ created and is fully functional. Note that the create()
+ function is of little use in the master object, because at the
+ time it is called there is no simul_efun object yet, and the
+ interpreter does not know anything about the user-ids and
+ access permissions.
+
+ The argument <arg> denotes why this function is called:
+ arg = 0: the mud just started, this is the first master of all.
+ = 1: the master was destructed and then reactivated
+ (because a new one couldn't be loaded).
+ = 2: the master was destructed and then reactivated, but
+ additionally lost all variable contents.
+ = 3: this is a reloaded master.
+
+ This function has at least to set up the driverhooks to use
+ (in 3.2.1). Also, any mudwho or wizlist handling has to be
+ initialized here.
+
+ Besides that, do whatever you feel you need to do,
+ e.g. set_auto_include_string(), or give the master a decent euid.
+
+SEE ALSO
+ initialisation(M), create(M), simul_efun(C), get_bb_id(M),
+ get_root_id(M), get_master_uid(M), flag(M),
+ reactivate_destructed_master(M)
diff --git a/doc/master/include_file b/doc/master/include_file
new file mode 100644
index 0000000..68568ee
--- /dev/null
+++ b/doc/master/include_file
@@ -0,0 +1,32 @@
+SYNOPSIS
+ mixed include_file (string file, string compiled_file, int sys_include)
+
+DESCRIPTION
+ Generate the pathname of an included file.
+
+ Arguments:
+ previous_object(): The object causing the compile.
+ file : The name given in the #include directive.
+ compiled_file : The object file which is just compiled.
+ (compat: name given without leading "/")
+ sys_include : TRUE for #include <> directives.
+
+ Result:
+ 0: use the normal include filename generation (""-includes are
+ used as they are, <>-includes are handled according to
+ H_INCLUDE_DIRS).
+
+ <path>: the full absolute pathname of the file to include,
+ without parentdir parts ("/../"). Leading slashes ("/")
+ may be omitted.
+
+ else: The include directive is not legal.
+
+ If the function does not generate a valid pathname, the driver
+ will next try to resolve the include using the H_INCLUDE_DIRS hook.
+
+HISTORY
+ Introduced in LDMud 3.2.8.
+
+SEE ALSO
+ hooks(C), inherit_file(M), include_dirs(H)
diff --git a/doc/master/inherit_file b/doc/master/inherit_file
new file mode 100644
index 0000000..7914fac
--- /dev/null
+++ b/doc/master/inherit_file
@@ -0,0 +1,26 @@
+SYNOPSIS
+ mixed inherit_file (string file, string compiled_file)
+
+DESCRIPTION
+ Generate the pathname of an inherited object.
+
+ Arguments:
+ previous_object(): The object causing the compile.
+ file : The name given in the inherit directive.
+ compiled_file : The object file which is just compiled.
+ (compat: name given without leading "/")
+
+ Result:
+ 0: use the given filename as it is.
+
+ <path>: the full absolute pathname of the file to inherit,
+ without parentdir parts ("/../"). Leading slashes ("/")
+ are ignored.
+
+ else: The inherit directive is not legal.
+
+HISTORY
+ Introduced in LDMud 3.2.8.
+
+SEE ALSO
+ hooks(C), include_file(M)
diff --git a/doc/master/initialisation b/doc/master/initialisation
new file mode 100644
index 0000000..e08d34a
--- /dev/null
+++ b/doc/master/initialisation
@@ -0,0 +1,16 @@
+SYNOPSIS
+ Initialization of the master object (since 3.2.1).
+
+ As since 3.2.1 the lfuns which are called to initialize
+ objects after a load are defined through driver hooks, and
+ these hooks are cleared prior to a master (re)load, the first
+ function called is inaugurate_master(). Anyway it's not very
+ sensible to do anything earlier as the master is not
+ recognized as such at that time, and so a number of
+ (important) things would not work.
+ Which lfun is called during runtime to reset the master is also
+ depending on the driverhook settings. Arbitrary actions may be done
+ on a reset.
+
+SEE ALSO
+ inaugurate_master(M)
diff --git a/doc/master/log_error b/doc/master/log_error
new file mode 100644
index 0000000..afc3385
--- /dev/null
+++ b/doc/master/log_error
@@ -0,0 +1,11 @@
+SYNOPSIS
+ void log_error(string file, string err)
+
+DESCRIPTION
+ Announce a compiler-time error in the named file. Whenever the
+ LPC compiler detects an error, this function is called. It
+ should at least log the error in a file, and also announce it
+ to the active user.
+
+SEE ALSO
+ runtime_error(M)
diff --git a/doc/master/make_path_absolute b/doc/master/make_path_absolute
new file mode 100644
index 0000000..e0a0019
--- /dev/null
+++ b/doc/master/make_path_absolute
@@ -0,0 +1,10 @@
+SYNOPSIS
+ string make_path_absolute(string str)
+
+DESCRIPTION
+ Absolutize a relative filename str given to the editor. Should
+ return the full pathname of the file to use. Any non-string
+ result will act as ``bad file name''.
+
+SEE ALSO
+ ed(E), valid_write(M)
diff --git a/doc/master/master b/doc/master/master
new file mode 100644
index 0000000..7d88855
--- /dev/null
+++ b/doc/master/master
@@ -0,0 +1,30 @@
+NAME
+ master
+
+DESCRIPTION
+ This directory contains descriptions for the functions that
+ Amylaar's version of the LPC parser, expects to find in the
+ master object (similar to lfuns, but for the master object
+ only). The name of the master object is hardcoded in the
+ parser (to "secure/master").
+
+ The master is the gateway between the interpreter and the
+ mudlib to perform actions with mudlib specific effects. Calls
+ to the master by the interpreter have an automatic catch() in
+ effect.
+
+ Note that the master is loaded first of all objects. Thus you
+ shouldn't inherit an other object, nor is the compiler able to
+ search include files (read: they must be specified with full
+ path).
+
+ Amylaar says: actually, you can inherit, but the file will be
+ loaded then before the master, which isn't good for most
+ files.
+
+ Refer to 'master-3.2' and 'master-3.2.1' for the surveys of
+ the masters internals.
+
+SEE ALSO
+ master-3.2(M), master-3.2.1(M)
+ efun(E), applied(A), concepts(C), driver(D), lpc(LPC)
diff --git a/doc/master/master-3.2 b/doc/master/master-3.2
new file mode 100644
index 0000000..b55a931
--- /dev/null
+++ b/doc/master/master-3.2
@@ -0,0 +1,248 @@
+NAME
+ master for LPMud 3.2
+
+DESCRIPTION
+ This directory contains descriptions for the functions that
+ Amylaar's version of the LPC parser, expects to find in the
+ master object (similar to lfuns, but for the master object
+ only). The name of the master object is hardcoded in the
+ parser (to "secure/master").
+
+ The master is the gateway between the interpreter and the
+ mudlib to perform actions with mudlib specific effects. Calls
+ to the master by the interpreter have an automatic catch() in
+ effect.
+
+ Note that the master is loaded first of all objects. Thus you
+ shouldn't inherit an other object, nor is the compiler able to
+ search include files (read: they must be specified with full
+ path).
+
+ Amylaar says: actually, you can inherit, but the file will be
+ loaded then before the master, which isn't good for most
+ files.
+
+ A short survey of the things that happen at system startup
+ time:
+
+ The Initialisation functions are called after (re)loading the
+ master to establish the most basic operation parameters.
+
+ The initialisation of LPMud on startup follows this schedule:
+ - The interpreter evaluates the commandline options and
+ initializes itself.
+ - The master is loaded, and thus it's create() (!compat only) and
+ its reset() is called, though it's not much use, since
+ most of the important things won't work already.
+ - get_root_uid() is called. If the result is valid, it
+ becomes the masters uid and euid.
+ - get_bb_uid() is called.
+ - inaugurate_master() is called.
+ - flag() is called for each given '-f' commandline option.
+ - get_simul_efun() is called.
+ - define_include_dirs() is called.
+ - Preloading is done:
+ compat : The filenames of the objects are read from
+ INIT_FILE and the objects are loaded. Then
+ epilog() is called.
+ !compat: epilog() is called. If it returns an array of
+ strings, it is considered holding the filenames
+ of the objects to preload. They are then given
+ one at a time as argument to preload() which
+ does the actual preloading.
+ - The interpreter sets up the IP communication and enters
+ the backend loop.
+
+ If the master is reloaded during system operation, this
+ actions are taken:
+ - The master is loaded, and thus it's create() (!compat only) and
+ its reset() is called.
+ - Any auto-include string is cleared.
+ - get_root_uid() is called. If the result is valid, it becomes the
+ masters uid and euid.
+ - inaugurate_master() is called.
+
+ If the master was destructed, but couldn't be reloaded, the old
+ master object could be reactivated. In that case:
+ - reactivate_destructed_master() is called.
+ - inaugurate_master() is called.
+
+
+ Security hint: most of this functions are not useful to be
+ called directly from other objects and can be made private or
+ static. Unlike create(), these functions that are applied to
+ the master object are found by the interpreter even if not
+ publicly accessible.
+
+
+
+ A short reference to all expected master functions...
+ ----------------------------------------------------------------
+ Initialisation
+
+ void create () // !compat
+ Initialize the object. Not very useful, though.
+
+ void reset (int flag) // !native
+ void reset () // native
+ Initialize (compat only) or reset the object.
+
+ void inaugurate_master ()
+ Perform mudlib specific setup of the master.
+
+ void flag (string arg)
+ Evaluate an argument given as option '-f' to the driver.
+
+ string *define_include_dirs ()
+ Define where the include files are searched.
+
+ void epilog () // compat
+ string *epilog (int eflag) // !compat
+ Perform final actions before opening the system to users.
+ The semantics of this function differ for compat and !compat mode.
+
+ void preload (string file) // !compat
+ Preload a given object.
+
+ void external_master_reload ()
+ Called after a reload of the master on external request.
+
+ void reactivate_destructed_master (int removed)
+ Reactivate a formerly destructed master.
+
+ string|string * get_simul_efun ()
+ Load the simul_efun object and return one or more paths of it.
+
+ ----------------------------------------------------------------
+ Handling of user connections
+
+ object connect ()
+ Handle the request for a new connection.
+
+ void disconnect (object obj)
+ Handle the loss of an IP connection.
+
+ void remove_player (object user)
+ Remove a user object from the system.
+
+ -----------------------------------------------------------------
+ Runtime Support
+
+ object compile_object (string filename)
+ Compile an virtual object.
+
+ string get_wiz_name (string file)
+ Return the author of a file.
+
+ string object_name (object obj)
+ Return a printable name for an object.
+
+ mixed prepare_destruct (object obj)
+ Prepare the destruction of the given object.
+
+ void quota_demon (void)
+ Handle quotas in times of memory shortage.
+
+ void receive_udp (string host, string msg)
+ Handle a received IMP message.
+
+ void slow_shut_down (int minutes)
+ Schedule a shutdown for the near future.
+
+ void notify_shutdown ()
+ Notify the master about an immediate shutdown.
+
+ -----------------------------------------------------------------
+ Error Handling
+
+ void dangling_lfun_closure ()
+ Handle a dangling lfun-closure.
+
+ void log_error (string file, string err)
+ Announce a compiler-time error.
+
+ mixed heart_beat_error (object culprit, string err,
+ string prg, string curobj, int line)
+ Announce an error in the heart_beat() function.
+
+ void runtime_error (string err, string prg, string curobj, int line)
+ Announce a runtime error.
+
+ -----------------------------------------------------------------
+ Security and Permissions
+
+ int privilege_violation (string op, mixed who, mixed arg3, mixed arg4)
+ Validate the execution of a privileged operation.
+
+ int query_allow_shadow (object victim)
+ Validate a shadowing.
+
+ int query_player_level (string what)
+ Check if the user is of high enough level for several things.
+
+ int valid_exec (string name)
+ Validate the rebinding of an IP connection by usage of efun
+ exec().
+
+ int valid_query_snoop (object obj)
+ Validate if the snoopers of an object may be revealed by
+ usage of the efun query_snoop().
+
+ int valid_snoop (object snoopee, object snooper)
+ Validate the start/stop of a snoop.
+
+ ------------------------------------------------------------------
+ Userids and depending Security
+
+ string creator_file (mixed obj)
+ Return the name of the creator of an object.
+ This is called in every mode!
+
+ string get_root_uid () // !compat
+ Return the string to be used as root-uid.
+
+ string get_bb_uid() // !compat
+ Return the string to be used as root-uid.
+
+ int valid_seteuid (object obj, string neweuid) // !compat
+ Validate the change of an objects euid by efun seteuid().
+
+ int|string valid_read (string path, string euid, string fun, object caller)
+ int|string valid_write (string path, string euid, string fun, object caller)
+ Validate a reading/writing file operation.
+
+ -----------------------------------------------------------------
+ ed() Support
+
+ string make_path_absolute (string str)
+ Absolutize a relative filename given to the editor.
+
+ int save_ed_setup (object who, int code)
+ Save individual settings of ed for a wizard.
+
+ int retrieve_ed_setup (object who)
+ Retrieve individual settings of ed for a wizard.
+
+ string get_ed_buffer_save_object_name (string file)
+ Return a filename for the ed buffer to be saved into.
+
+ ----------------------------------------------------------------
+ parse_command() Support (!compat)
+
+ string *parse_command_id_list ()
+ Return generic singular ids.
+
+ string *parse_command_plural_id_list ()
+ Return generic plural ids.
+
+ string *parse_command_adjectiv_id_list ()
+ Return generic adjective ids.
+
+ string *parse_command_prepos_list ()
+ Return common prepositions.
+
+ string parse_command_all_word()
+ Return the one(!) 'all' word.
+
+SEE ALSO
+ master(M), efun(E), applied(A), concepts(C), driver(D), lpc(LPC)
diff --git a/doc/master/master-3.2.1 b/doc/master/master-3.2.1
new file mode 100644
index 0000000..03e4339
--- /dev/null
+++ b/doc/master/master-3.2.1
@@ -0,0 +1,231 @@
+NAME
+ master for LPMud 3.2.1
+
+DESCRIPTION
+ This directory contains descriptions for the functions that
+ Amylaar's version of the LPC parser, expects to find in the
+ master object (similar to lfuns, but for the master object
+ only). The name of the master object is hardcoded in the
+ parser (to "secure/master").
+
+ The master is the gateway between the interpreter and the
+ mudlib to perform actions with mudlib specific effects. Calls
+ to the master by the interpreter have an automatic catch() in
+ effect.
+
+ Note that the master is loaded first of all objects. Thus you
+ shouldn't inherit an other object, nor is the compiler able to
+ search include files (read: they must be specified with full
+ path).
+
+ Amylaar says: actually, you can inherit, but the file will be
+ loaded then before the master, which isn't good for most
+ files.
+
+ A short survey of the things that happen at system startup
+ time:
+
+ The Initialisation functions are called after (re)loading the
+ master to establish the most basic operation parameters.
+
+ The initialisation of LPMud on startup follows this schedule:
+ - The interpreter evaluates the commandline options and
+ initializes itself.
+ - The master is loaded, but since the driverhooks are not set yet,
+ no standard initialisation lfun is called.
+ - get_master_uid() is called. If the result is valid, it becomes the
+ - inaugurate_master() is called.
+ - flag() is called for each given '-f' commandline option.
+ - get_simul_efun() is called.
+ - the WIZLIST is read in.
+ - epilog() is called. If it returns an array of strings,
+ they are given one at a time as argument to preload().
+ Traditionally, these strings are the filenames of the objects to
+ preload, which preload() then does.
+ - The interpreter sets up the IP communication and enters
+ the backend loop.
+
+ If the master is reloaded during system operation, this
+ actions are taken:
+ - The master is loaded, and its initialisation lfun is
+ called according to the settings of the driverhooks (if set).
+ - Any auto-include string and all driverhooks are cleared.
+ - get_master_uid() is called. If the result is valid, it becomes the
+ masters uid and euid.
+ - inaugurate_master() is called.
+
+ If the master was destructed, but couldn't be reloaded, the old
+ master object could be reactivated. In that case:
+ - reactivate_destructed_master() is called.
+ - inaugurate_master() is called.
+
+
+ Security hint: most of this functions are not useful to be
+ called directly from other objects and can be made private or
+ static. Unlike create(), these functions that are applied to
+ the master object are found by the interpreter even if not
+ publicly accessible.
+
+
+
+ A short reference to all expected master functions...
+ ----------------------------------------------------------------
+ Initialisation
+
+ void inaugurate_master ()
+ Perform mudlib specific setup of the master.
+
+ string get_master_uid ()
+ Return the string to be used as uid (and -euid) of a
+ (re)loaded master.
+
+ void flag (string arg)
+ Evaluate an argument given as option '-f' to the driver.
+
+ string *define_include_dirs ()
+ Define where the include files are searched.
+
+ string *epilog (int eflag)
+ Perform final actions before opening the system to users.
+
+ void preload (string file)
+ Preload a given object.
+
+ void external_master_reload ()
+ Called after a reload of the master on external request.
+
+ void reactivate_destructed_master (int removed)
+ Reactivate a formerly destructed master.
+
+ string|string * get_simul_efun ()
+ Load the simul_efun object and return one or more paths of it.
+
+ ----------------------------------------------------------------
+ Handling of user connections
+
+ object connect ()
+ Handle the request for a new connection.
+
+ void disconnect (object obj)
+ Handle the loss of an IP connection.
+
+ void remove_player (object user)
+ Remove a user object from the system.
+
+ void stale_erq (closure callback)
+ Notify the loss of the erq demon.
+
+ -----------------------------------------------------------------
+ Runtime Support
+
+ object compile_object (string filename)
+ Compile an virtual object.
+
+ string get_wiz_name (string file)
+ Return the author of a file.
+
+ string object_name (object obj)
+ Return a printable name for an object.
+
+ mixed prepare_destruct (object obj)
+ Prepare the destruction of the given object.
+
+ void quota_demon (void)
+ Handle quotas in times of memory shortage.
+
+ void receive_udp (string host, string msg, int port)
+ Handle a received IMP message.
+
+ void slow_shut_down (int minutes)
+ Schedule a shutdown for the near future.
+
+ void notify_shutdown ()
+ Notify the master about an immediate shutdown.
+
+ -----------------------------------------------------------------
+ Error Handling
+
+ void dangling_lfun_closure ()
+ Handle a dangling lfun-closure.
+
+ void log_error (string file, string err)
+ Announce a compiler-time error.
+
+ mixed heart_beat_error (object culprit, string err,
+ string prg, string curobj, int line)
+ Announce an error in the heart_beat() function.
+
+ void runtime_error (string err, string prg, string curobj, int line)
+ Announce a runtime error.
+
+ -----------------------------------------------------------------
+ Security and Permissions
+
+ int privilege_violation (string op, mixed who, mixed arg3, mixed arg4)
+ Validate the execution of a privileged operation.
+
+ int query_allow_shadow (object victim)
+ Validate a shadowing.
+
+ int query_player_level (string what)
+ Check if the user is of high enough level for several things.
+
+ int valid_exec (string name)
+ Validate the rebinding of an IP connection by usage of efun
+ exec().
+
+ int valid_query_snoop (object obj)
+ Validate if the snoopers of an object may be revealed by
+ usage of the efun query_snoop().
+
+ int valid_snoop (object snoopee, object snooper)
+ Validate the start/stop of a snoop.
+
+ ------------------------------------------------------------------
+ Userids and depending Security
+
+ string get_bb_uid() // euids
+ Return the string to be used as root-uid.
+
+ int valid_seteuid (object obj, string neweuid) // euids
+ Validate the change of an objects euid by efun seteuid().
+
+ int|string valid_read (string path, string euid, string fun, object caller)
+ int|string valid_write (string path, string euid, string fun, object caller)
+ Validate a reading/writing file operation.
+
+ -----------------------------------------------------------------
+ ed() Support
+
+ string make_path_absolute (string str)
+ Absolutize a relative filename given to the editor.
+
+ int save_ed_setup (object who, int code)
+ Save individual settings of ed for a wizard.
+
+ int retrieve_ed_setup (object who)
+ Retrieve individual settings of ed for a wizard.
+
+ string get_ed_buffer_save_object_name (string file)
+ Return a filename for the ed buffer to be saved into.
+
+ ----------------------------------------------------------------
+ parse_command() Support (!compat, SUPPLY_PARSE_COMMAND defined)
+
+ string *parse_command_id_list ()
+ Return generic singular ids.
+
+ string *parse_command_plural_id_list ()
+ Return generic plural ids.
+
+ string *parse_command_adjectiv_id_list ()
+ Return generic adjective ids.
+
+ string *parse_command_prepos_list ()
+ Return common prepositions.
+
+ string parse_command_all_word()
+ Return the one(!) 'all' word.
+
+SEE ALSO
+ master(M), efun(E), applied(A), concepts(C), driver(D), lpc(LPC)
diff --git a/doc/master/notify_shutdown b/doc/master/notify_shutdown
new file mode 100644
index 0000000..d23cd98
--- /dev/null
+++ b/doc/master/notify_shutdown
@@ -0,0 +1,29 @@
+SYNOPSIS
+ varargs void notify_shutdown (string crash_reason)
+
+DESCRIPTION
+ Notify the master about an immediate shutdown. If <crash_reason> is 0,
+ it is a normal shutdown, otherwise it is a crash and <crash_reason>
+ gives a hint at the reason.
+
+ The function has the opportunity to perform any cleanup operation,
+ like informing the mudwho server that the mud is down. This can not be
+ done when remove_player() is called because the udp connectivity is
+ already gone then.
+
+ If the gamedriver shuts down normally , this is the last function
+ called before the mud shuts down the udp connections and the accepting
+ socket for new players.
+
+ If the gamedriver crashes, this is the last function called before the
+ mud attempts to dump core and exit. WARNING: Since the driver is in an
+ unstable state, this function may not be able to run to completion!
+ The following crash reasons are defined:
+ "Fatal Error": an internal sanity check failed.
+
+HISTORY
+ LDMud 3.2.9 added the <crash_reason> argument and that the function
+ is called for a crash at all.
+
+SEE ALSO
+ slow_shut_down(M), remove_player(M),
diff --git a/doc/master/object_name b/doc/master/object_name
new file mode 100644
index 0000000..2990b6d
--- /dev/null
+++ b/doc/master/object_name
@@ -0,0 +1,10 @@
+SYNOPSIS
+ string object_name(object ob)
+
+DESCRIPTION
+ Return a printable name for an object. This function is called
+ by sprintf() to print a meaningful name in addition to the
+ normal object_name().
+
+SEE ALSO
+ sprintf(E), object_name(E)
diff --git a/doc/master/parse_command_all_word b/doc/master/parse_command_all_word
new file mode 100644
index 0000000..b57ab05
--- /dev/null
+++ b/doc/master/parse_command_all_word
@@ -0,0 +1,9 @@
+SYNOPSIS
+ string *parse_command_all_word(void)
+
+DESCRIPTION
+ Used by parse_command(). Return the word for ``all'' in the
+ installations native language.
+
+SEE ALSO
+ parse_command(E)
diff --git a/doc/master/parse_command_prepos_list b/doc/master/parse_command_prepos_list
new file mode 100644
index 0000000..24706ce
--- /dev/null
+++ b/doc/master/parse_command_prepos_list
@@ -0,0 +1,9 @@
+SYNOPSIS
+ string *parse_command_prepos_list(void)
+
+DESCRIPTION
+ Used by parse_command(). Return an array of common
+ prepositions in the installations native language.
+
+SEE ALSO
+ parse_command(E)
diff --git a/doc/master/preload b/doc/master/preload
new file mode 100644
index 0000000..95f27d7
--- /dev/null
+++ b/doc/master/preload
@@ -0,0 +1,18 @@
+SYNOPSIS
+ void preload(string file)
+
+DESCRIPTION
+ Load the object with the given file name, that was returned by
+ epilog(). It is task of the epilog()/preload() pair to ensure
+ the validity of the given strings (e.g. filtering out comments
+ and blank lines). For preload itself a call_other(file, "???")
+ s sufficient, but it should be guarded by a catch() to avoid
+ premature blockings. Also it is wise to change the master's
+ euid from root_uid to something less privileged for the time
+ of the preload.
+
+ You can of course do anything else with the passed strings -
+ preloading is just the traditional task.
+
+SEE ALSO
+ epilog(M), master(M)
diff --git a/doc/master/prepare_destruct b/doc/master/prepare_destruct
new file mode 100644
index 0000000..3121b88
--- /dev/null
+++ b/doc/master/prepare_destruct
@@ -0,0 +1,22 @@
+SYNOPSIS
+ mixed prepare_destruct(object obj)
+
+DESCRIPTION
+ Prepare the destruction of the object obj. Return 0 if the
+ object is ready for destruction, any other value will abort
+ the attempt. If a string is returned, an error with the string
+ as message will be issued.
+
+ The interpreter calls this function whenever an object shall
+ be destructed. It expects, that this function cleans the
+ inventory of the object, or the destruct will fail.
+ Furthermore, the function could notify the former inventory
+ objects that their holder is under destruction (useful to move
+ users out of rooms which re updated); and it could announce
+ systemwide the destruction(quitting) of users.
+
+ Strange things will happen if the mastor object does not
+ provide this function.
+
+SEE ALSO
+ remove_player(M), destruct(E)
diff --git a/doc/master/privilege_violation b/doc/master/privilege_violation
new file mode 100644
index 0000000..957a4b9
--- /dev/null
+++ b/doc/master/privilege_violation
@@ -0,0 +1,63 @@
+SYNOPSIS
+ int privilege_violation(string op, mixed who, mixed arg3, mixed arg4)
+
+DESCRIPTION
+ Validate the execution of a privileged operation.
+ op denotes the requested operation, who is the object
+ requesting the operation (object_name or object pointer), arg3
+ and arg4 are additional arguments, depending on the operation.
+
+ The function should return >0 to grant the privilege, 0 to
+ indicate that the caller was probably misleaded and the error
+ might be fixed, and anything else to indicate a real
+ violation, that will be handled as run time error.
+
+ The privileged operations are:
+ attach_erq_demon Attach the erq demon to object <arg> with
+ flag <args>.
+ bind_lambda Bind a lambda-closure to object arg3.
+ call_out_info Return an array with all call_out
+ informations.
+ nomask simul_efun Attempt to get an efun <arg> via efun:: when
+ it is shadowed by a nomask type simul_efun.
+ rename_object The object who tries to rename the object
+ arg3 to the name arg4.
+ send_udp Send UDP-data to host arg3.
+ set_auto_include_string Set the string automatically included
+ by the compiler into every object.
+ get_extra_wizinfo Get the additional wiz-list info for user
+ arg3.
+ set_extra_wizinfo Set the additional wiz-list info for user
+ arg3.
+ set_extra_wizinfo_size Set the size of the additional user
+ info in the wiz-list to arg3.
+ set_driver_hook : Set hook <arg> to <arg2>.
+ set_this_object Set this_object() to arg3.
+ shadow_add_action Add an action to function arg4 that is
+ shadowed by the object arg3.
+ symbol_variable Attempt to make a symbol from a hidden
+ inherited variable. arg3 is the object in
+ question, arg4 the number of the variable in
+ the variable table.
+ wizlist_info Return an array with all wiz-list
+ information.
+
+ call_out_info() can return the arguments to functions and
+ lambda closures to be called by call_out(); you should
+ consider that read access to closures, mappings and arrays
+ means write access and/or other privileges.
+ wizlist_info() will return an array which holds, among others,
+ the extra wizlist field. While a toplevel array, if found,
+ will be copied, this does not apply to nested arrays or to any
+ mappings. You might also have some sensitive closures there.
+ send_udp() should be watched as it could be abused to mess up
+ the IMP.
+ The xxx_extra_wizinfo operations are necessary for a proper
+ wizlist and should therefore be restricted to admins.
+ All other operations are potential sources for direct security
+ breaches - any use of them should be scrutinized closely.
+
+SEE ALSO
+ simul_efun(C), call_out_info(E), shadow(E), add_action(E),
+ wizlist(E), set_this_object(E), rename_object(E),
+ bind_lambda(E), send_udp(E), set_auto_include_string(E)
diff --git a/doc/master/query_allow_shadow b/doc/master/query_allow_shadow
new file mode 100644
index 0000000..47d2e95
--- /dev/null
+++ b/doc/master/query_allow_shadow
@@ -0,0 +1,23 @@
+query_allow_shadow(M)
+FUNKTION:
+ int query_allow_shadow(object victim)
+
+DEFINITION:
+ /secure/master.c
+
+BESCHREIBUNG:
+ Gibt 1 zurueck, wenn das Objekt victim von previous_object() beschattet
+ werden darf, 0 sonst.
+
+ Die Funktion prueft, ob das Objekt victim ein Root-Objekt ist, oder
+ ob es beim Aufruf von query_prevent_shadow() 1 zurueckgibt.
+
+BEMERKUNGEN:
+ Wird automatisch bei shadow() ausgefuehrt.
+
+SIEHE AUCH:
+ Rechte: query_prevent_shadow(L)
+ Generell: shadow(E), unshadow(E)
+ Informationen: query_shadowing(E)
+
+20. Mai 2004 Gloinson
\ No newline at end of file
diff --git a/doc/master/query_player_level b/doc/master/query_player_level
new file mode 100644
index 0000000..484e18e
--- /dev/null
+++ b/doc/master/query_player_level
@@ -0,0 +1,15 @@
+SYNOPSIS
+ int query_player_level(string what)
+
+DESCRIPTION
+ Check if the user is of high enough level for several things.
+
+ The argument denotes the action for which permission is to be
+ checked:
+
+ "trace" Is the user allowed to use tracing?
+ "inspect memory" Is the user allowed to issue the
+ special command "showsmallnewmalloced"?
+
+SEE ALSO
+ trace(E), showsmallnewmalloced(D), malloc(D), status(D), memory(C)
diff --git a/doc/master/quota_demon b/doc/master/quota_demon
new file mode 100644
index 0000000..f7f8d95
--- /dev/null
+++ b/doc/master/quota_demon
@@ -0,0 +1,18 @@
+SYNOPSIS
+ void quota_demon(void)
+
+DESCRIPTION
+ Handle quotas in times of memory shortage.
+
+ This function is called during the final phase of a garbage
+ collection if the reserved user area couldn't be reallocated.
+ This function (or a called demon) has now the opportunity to
+ remove some (still active) objects from the system. If this does
+ not free enough memory to reallocate the user reserve,
+ slow_shut_down() will be called to start Armageddon.
+
+ Up to now, the wizlist lacks various informations needed to
+ detect the memory-hungriest users.
+
+SEE ALSO
+ slow_shut_down(M), wizlist(E)
diff --git a/doc/master/reactivate_destructed_master b/doc/master/reactivate_destructed_master
new file mode 100644
index 0000000..e90d2a1
--- /dev/null
+++ b/doc/master/reactivate_destructed_master
@@ -0,0 +1,15 @@
+SYNOPSIS
+ void reactivate_destructed_master(int flag)
+
+DESCRIPTION
+ This function is called in an already destructed master object
+ if no new master object could be loaded. flag will be 1 if the
+ old master object could be reclaimed form the list of objects
+ that were marked for destruction but not yet terminated. If
+ flag is 0, all variables of the object have been set to 0 and
+ must be re-initialized.
+
+ After this function, inaugurate_master() will be applied again.
+
+SEE ALSO
+ destruct(E), inaugurate_master(M), master(M)
diff --git a/doc/master/receive_udp b/doc/master/receive_udp
new file mode 100644
index 0000000..a1b58c5
--- /dev/null
+++ b/doc/master/receive_udp
@@ -0,0 +1,17 @@
+SYNOPSIS
+ void receive_udp(string host, string msg, int hostport)
+
+DESCRIPTION
+ Handle a received IMP message.
+
+ This function is called for every message received on the IMP
+ port. Usually it is passed on to some object that handles
+ inter mud communications.
+
+HISTORY
+ The 'hostport' argument was added in 3.2.1.
+
+SEE ALSO
+ send_udp(E), query_udp_port(E)
+
+29.10.2006 Zesstra
diff --git a/doc/master/remove_player b/doc/master/remove_player
new file mode 100644
index 0000000..b70a1fb
--- /dev/null
+++ b/doc/master/remove_player
@@ -0,0 +1,14 @@
+SYNOPSIS
+ void remove_player(object ob)
+
+DESCRIPTION
+ Remove an interactive user object ob from the system. This
+ function is called by the interpreter to expell remaining
+ users from the system on shutdown in a polite way. If this
+ functions fails to quit/destruct the user, he will be
+ destructed the hard way by the interpreter.
+
+ This function must not cause runtime errors.
+
+SEE ALSO
+ remove_interactive(E), slow_shut_down(M)
diff --git a/doc/master/retrieve_ed_setup b/doc/master/retrieve_ed_setup
new file mode 100644
index 0000000..4d92ef0
--- /dev/null
+++ b/doc/master/retrieve_ed_setup
@@ -0,0 +1,9 @@
+SYNOPSIS
+ int retrieve_ed_setup(object command_giver)
+
+DESCRIPTION
+ Should return an integer that gives the ed setup flags for the
+ user that is denoted by command_giver.
+
+SEE ALSO
+ save_ed_setup(M)
diff --git a/doc/master/runtime_error b/doc/master/runtime_error
new file mode 100644
index 0000000..d109df8
--- /dev/null
+++ b/doc/master/runtime_error
@@ -0,0 +1,16 @@
+SYNOPSIS
+ void runtime_error(string err, string prg, string curobj, int line)
+
+DESCRIPTION
+ This function has to announce a runtime error to the active
+ user. If the user has enough privileges, it might give him the
+ full error message together with the source line. Else it
+ should issue a decent message ("Your sensitive mind notices a
+ wrongness in the fabric of space").
+
+ Note that prg denotes the program actually executed (which
+ might be an inherited one) whereas curobj is just the
+ offending object.
+
+SEE ALSO
+ log_error(M), heart_beat_error(M), raise_error(E)
diff --git a/doc/master/runtime_warning b/doc/master/runtime_warning
new file mode 100644
index 0000000..80864ab
--- /dev/null
+++ b/doc/master/runtime_warning
@@ -0,0 +1,27 @@
+SYNOPSIS
+ void runtime_warning( string msg, string curobj, string prog, int line
+ , int inside_catch)
+
+DESCRIPTION
+ This function is called to let the mudlib handle a runtime warning,
+ e.g. by logging it into a database.
+
+ <msg> is the warning message.
+ <curobj> is the name of the current object which caused the message
+ (the object itself might already be destructed), or 0 if there
+ is none.
+ <prog>, <line> determine the name of the program and the line where
+ the error occured if the current object exists, otherwise
+ they are 0.
+ <inside_catch> : != 0 if the warning occurs inside a catch().
+
+ The driver is limited to three nested warnings, to prevent
+ an endless recursion in case runtime_warning() itself causes
+ warnings.
+
+HISTORY
+ Introduced in LDMud 3.3.551.
+ LDMud 3.3.705 added the <inside_catch> argument.
+
+SEE ALSO
+ runtime_error(M)
diff --git a/doc/master/save_ed_setup b/doc/master/save_ed_setup
new file mode 100644
index 0000000..feaaf71
--- /dev/null
+++ b/doc/master/save_ed_setup
@@ -0,0 +1,33 @@
+SYNOPSIS
+ int save_ed_setup(object who, int code)
+
+DESCRIPTION
+ Save individual option settings of the builtin ed, encoded
+ into code, for the user denoted by who. These functions are
+ located in the master object so that the local gods can decide
+ what strategy they want to use. suggestions:
+ A setup file for every user.
+ advantages: transparent to the user
+ independent of user count
+ disadvantage: extra file access at ed invocation
+ An array in the master object, users are searched by member_array
+ advantage: easy to implement
+ disadvantage: performance degradation with high user counts
+ An AVL-tree to access users by name
+ advantage: can fit any need
+ disadvantage: hard to implement, will need more
+ overhead on small and medium
+ installations than it can ever make
+ good by lg(usercount) complexity
+ Dedicated flags in every user object.
+ advantages: easy to implement
+ independent of user count
+ Will also work for nusers w/o file
+ access privileges.
+ disadvantage: care has to be taken to avoid
+ collision with other uses of the flags
+ in the user object
+
+SEE ALSO
+ ed(E), retrieve_ed_setup(M), valid_write(M),
+ get_ed_buffer_save_object_name(M)
diff --git a/doc/master/slow_shut_down b/doc/master/slow_shut_down
new file mode 100644
index 0000000..9a7fe8d
--- /dev/null
+++ b/doc/master/slow_shut_down
@@ -0,0 +1,40 @@
+SYNOPSIS
+ void slow_shut_down(int minutes)
+
+DESCRIPTION
+ Schedule a shutdown for the near future. minutes is the
+ desired time in minutes till the shutdown:
+ six, if just the user reserve has been put into use.
+ one, if the (smaller) master reserve has been put into use as
+ well.
+
+ The interpreter calls this function when it runs low on
+ memory. At this time, it has freed its reserve, but since it
+ won't last long, the interpreter needs to be shut down. The
+ delay is to give the users the opportunity to finish their
+ current tasks, but don't take the 'minutes' for granted, just
+ deduce the urgency from it.
+ It is possible that the driver may reallocate some memory
+ after the function has been called, and then run again into a
+ low memory situation, calling this function again.
+ This function might load an 'Armageddon' object and tell it
+ what to do. It is the Armageddon object then which performs
+ the shutdown.
+
+ Technical: The memory handling of the interpreter includes
+ three reserved areas: user, system and master. All three are
+ there to insure that the system shuts down gracefully when the
+ memory runs out: the user area to give the users time to
+ quit normally, the others to enable emergency-logouts when the
+ user reserve is used up as well.
+ The areas are allocated at start of the interpreter, and
+ released when no more memory could be obtained from the host.
+ In such a case, one of the remaining areas is freed (so the
+ operation can continue a short while) and a garbage collection
+ is initiated. If the garbage collection recycles enough memory
+ (either true garbage or by the aid of the quota_demon) to
+ reallocate the areas, all is fine, else the system shut down
+ is invoked by a call to this function.
+
+SEE ALSO
+ quota_demon(M), notify_shutdown(M), shutdown(E), malloc(D), memory(C)
diff --git a/doc/master/stale_erq b/doc/master/stale_erq
new file mode 100644
index 0000000..a05ca31
--- /dev/null
+++ b/doc/master/stale_erq
@@ -0,0 +1,17 @@
+SYNOPSIS
+ void stale_erq (closure callback)
+
+DESCRIPTION
+ Notify the loss of the erq demon.
+ Argument is the callback closure set for an erq request.
+
+ If the erq connection dies prematurely, the driver will call
+ this lfun for every pending request with set callback. This
+ function should notify the originating object that the answer
+ will never arrive.
+
+HISTORY
+ Introduced in 3.2.1@61.
+
+SEE ALSO
+ erq(C)
diff --git a/doc/master/valid_exec b/doc/master/valid_exec
new file mode 100644
index 0000000..2c0b67b
--- /dev/null
+++ b/doc/master/valid_exec
@@ -0,0 +1,15 @@
+SYNOPSIS
+ int valid_exec(string name, object ob, object obfrom)
+
+DESCRIPTION
+ Validate the rebinding of an IP connection by usage of efun
+ exec(). Arguments are the <name> of the _program_ attempting
+ to rebind the connection, the object <ob> to receive the
+ connection, and the object <obfrom> giving the connection.
+ Note that the program name is not the object_name() of the
+ object, and has no leading slash.
+
+ Return 0 to disallow the action, any other value to allow it.
+
+SEE ALSO
+ exec(E)
diff --git a/doc/master/valid_query_snoop b/doc/master/valid_query_snoop
new file mode 100644
index 0000000..e92378a
--- /dev/null
+++ b/doc/master/valid_query_snoop
@@ -0,0 +1,12 @@
+SYNOPSIS
+ valid_query_snoop(object ob)
+
+DESCRIPTION
+ Should return 1 if previous_object() (the one that called the
+ efun query_snoop()) is allowed to query wether ob is being
+ snooped, 0 if not.
+
+ The master object is always allowed to use query_snoop().
+
+SEE ALSO
+ valid_snoop(M), query_snoop(E), snoop(E)
diff --git a/doc/master/valid_read b/doc/master/valid_read
new file mode 100644
index 0000000..2dafbae
--- /dev/null
+++ b/doc/master/valid_read
@@ -0,0 +1,32 @@
+SYNOPSIS
+ string valid_read(string path, string uid, string func, object ob)
+
+DESCRIPTION
+ This function is called to check if the object ob with the
+ user-id uid has read permissions for the file given by path
+ for the operation named by func. It should return 0 if
+ permission is denied, or the normalized path if permission is
+ granted. You can also return 1 to indicate that the path can
+ be used unchanged.
+
+ The returned pathname must not contain ``..'', a leading /
+ will be stripped by the interpreter.
+
+ Func denotes the efun call or other operation that caused
+ valid_read() to be called:
+ ed_start (check if the file to be edited is readable),
+ file_size,
+ get_dir,
+ print_file (efun cat()),
+ read_bytes,
+ read_file,
+ restore_object,
+ tail.
+
+ Note that this function is called in compat mode as well. If
+ you need to be compatible with the old 2.4.5-mudlib, redirect
+ these calls to the valid_read/valid_write in the user
+ object.
+
+SEE ALSO
+ valid_write(M), make_path_absolute(M)
diff --git a/doc/master/valid_seteuid b/doc/master/valid_seteuid
new file mode 100644
index 0000000..3afc0d2
--- /dev/null
+++ b/doc/master/valid_seteuid
@@ -0,0 +1,9 @@
+SYNOPSIS
+ int valid_seteuid(object ob, string newid)
+
+DESCRIPTION
+ Should return 1 if ob is allowed to set its euid to newid.
+ Objects are always allowed to set their euid to 0.
+
+SEE ALSO
+ seteuid(E), uids(C)
diff --git a/doc/master/valid_snoop b/doc/master/valid_snoop
new file mode 100644
index 0000000..5bff987
--- /dev/null
+++ b/doc/master/valid_snoop
@@ -0,0 +1,8 @@
+SYNOPSIS
+ int valid_snoop(object me, object you)
+
+DESCRIPTION
+ Should return 1 if me is allowed to snoop you, 0 if not.
+
+SEE ALSO
+ snoop(E), query_snoop(E), valid_query_snoop(M)
diff --git a/doc/master/valid_write b/doc/master/valid_write
new file mode 100644
index 0000000..31fe43b
--- /dev/null
+++ b/doc/master/valid_write
@@ -0,0 +1,33 @@
+SYNOPSIS
+ string valid_write(string path, string uid, string func, object ob)
+
+DESCRIPTION
+ This function is called to check if the object ob with the
+ user-id uid has write permissions to the file given by path
+ for the operation named by func. It should return 0 if
+ permission is denied, or the normalized path if permission is
+ granted. You can also return 1 to indicate that the path can
+ be used unchanged.
+
+ The returned pathname must not contain ``..'', a leading /
+ will be stripped by the interpreter.
+
+ Func denotes the efun call or other operation that caused
+ valid_write() to be called:
+ cindent,
+ do_rename (efun rename(), for the old and then for the new name),
+ ed_start (whenever the builtin ed tries to write to a file),
+ mkdir,
+ remove_file (efun rm()),
+ rmdir,
+ save_object,
+ write_bytes,
+ write_file.
+
+ Note that this function is called in compat mode as well. If
+ you need to be compatible with the old 2.4.5-mudlib, redirect
+ these calls to the valid_read/valid_write in the user
+ object.
+
+SEE ALSO
+ valid_read(M), make_path_absolute(M)