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 (usually 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. Functions to be called by the driver can be public
        or static, but not private.

        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_imp (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_file_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)
