MG Mud User | 88f1247 | 2016-06-24 23:31:02 +0200 | [diff] [blame^] | 1 | NAME |
| 2 | master for LPMud 3.2 |
| 3 | |
| 4 | DESCRIPTION |
| 5 | This directory contains descriptions for the functions that |
| 6 | Amylaar's version of the LPC parser, expects to find in the |
| 7 | master object (similar to lfuns, but for the master object |
| 8 | only). The name of the master object is hardcoded in the |
| 9 | parser (to "secure/master"). |
| 10 | |
| 11 | The master is the gateway between the interpreter and the |
| 12 | mudlib to perform actions with mudlib specific effects. Calls |
| 13 | to the master by the interpreter have an automatic catch() in |
| 14 | effect. |
| 15 | |
| 16 | Note that the master is loaded first of all objects. Thus you |
| 17 | shouldn't inherit an other object, nor is the compiler able to |
| 18 | search include files (read: they must be specified with full |
| 19 | path). |
| 20 | |
| 21 | Amylaar says: actually, you can inherit, but the file will be |
| 22 | loaded then before the master, which isn't good for most |
| 23 | files. |
| 24 | |
| 25 | A short survey of the things that happen at system startup |
| 26 | time: |
| 27 | |
| 28 | The Initialisation functions are called after (re)loading the |
| 29 | master to establish the most basic operation parameters. |
| 30 | |
| 31 | The initialisation of LPMud on startup follows this schedule: |
| 32 | - The interpreter evaluates the commandline options and |
| 33 | initializes itself. |
| 34 | - The master is loaded, and thus it's create() (!compat only) and |
| 35 | its reset() is called, though it's not much use, since |
| 36 | most of the important things won't work already. |
| 37 | - get_root_uid() is called. If the result is valid, it |
| 38 | becomes the masters uid and euid. |
| 39 | - get_bb_uid() is called. |
| 40 | - inaugurate_master() is called. |
| 41 | - flag() is called for each given '-f' commandline option. |
| 42 | - get_simul_efun() is called. |
| 43 | - define_include_dirs() is called. |
| 44 | - Preloading is done: |
| 45 | compat : The filenames of the objects are read from |
| 46 | INIT_FILE and the objects are loaded. Then |
| 47 | epilog() is called. |
| 48 | !compat: epilog() is called. If it returns an array of |
| 49 | strings, it is considered holding the filenames |
| 50 | of the objects to preload. They are then given |
| 51 | one at a time as argument to preload() which |
| 52 | does the actual preloading. |
| 53 | - The interpreter sets up the IP communication and enters |
| 54 | the backend loop. |
| 55 | |
| 56 | If the master is reloaded during system operation, this |
| 57 | actions are taken: |
| 58 | - The master is loaded, and thus it's create() (!compat only) and |
| 59 | its reset() is called. |
| 60 | - Any auto-include string is cleared. |
| 61 | - get_root_uid() is called. If the result is valid, it becomes the |
| 62 | masters uid and euid. |
| 63 | - inaugurate_master() is called. |
| 64 | |
| 65 | If the master was destructed, but couldn't be reloaded, the old |
| 66 | master object could be reactivated. In that case: |
| 67 | - reactivate_destructed_master() is called. |
| 68 | - inaugurate_master() is called. |
| 69 | |
| 70 | |
| 71 | Security hint: most of this functions are not useful to be |
| 72 | called directly from other objects and can be made private or |
| 73 | static. Unlike create(), these functions that are applied to |
| 74 | the master object are found by the interpreter even if not |
| 75 | publicly accessible. |
| 76 | |
| 77 | |
| 78 | |
| 79 | A short reference to all expected master functions... |
| 80 | ---------------------------------------------------------------- |
| 81 | Initialisation |
| 82 | |
| 83 | void create () // !compat |
| 84 | Initialize the object. Not very useful, though. |
| 85 | |
| 86 | void reset (int flag) // !native |
| 87 | void reset () // native |
| 88 | Initialize (compat only) or reset the object. |
| 89 | |
| 90 | void inaugurate_master () |
| 91 | Perform mudlib specific setup of the master. |
| 92 | |
| 93 | void flag (string arg) |
| 94 | Evaluate an argument given as option '-f' to the driver. |
| 95 | |
| 96 | string *define_include_dirs () |
| 97 | Define where the include files are searched. |
| 98 | |
| 99 | void epilog () // compat |
| 100 | string *epilog (int eflag) // !compat |
| 101 | Perform final actions before opening the system to users. |
| 102 | The semantics of this function differ for compat and !compat mode. |
| 103 | |
| 104 | void preload (string file) // !compat |
| 105 | Preload a given object. |
| 106 | |
| 107 | void external_master_reload () |
| 108 | Called after a reload of the master on external request. |
| 109 | |
| 110 | void reactivate_destructed_master (int removed) |
| 111 | Reactivate a formerly destructed master. |
| 112 | |
| 113 | string|string * get_simul_efun () |
| 114 | Load the simul_efun object and return one or more paths of it. |
| 115 | |
| 116 | ---------------------------------------------------------------- |
| 117 | Handling of user connections |
| 118 | |
| 119 | object connect () |
| 120 | Handle the request for a new connection. |
| 121 | |
| 122 | void disconnect (object obj) |
| 123 | Handle the loss of an IP connection. |
| 124 | |
| 125 | void remove_player (object user) |
| 126 | Remove a user object from the system. |
| 127 | |
| 128 | ----------------------------------------------------------------- |
| 129 | Runtime Support |
| 130 | |
| 131 | object compile_object (string filename) |
| 132 | Compile an virtual object. |
| 133 | |
| 134 | string get_wiz_name (string file) |
| 135 | Return the author of a file. |
| 136 | |
| 137 | string object_name (object obj) |
| 138 | Return a printable name for an object. |
| 139 | |
| 140 | mixed prepare_destruct (object obj) |
| 141 | Prepare the destruction of the given object. |
| 142 | |
| 143 | void quota_demon (void) |
| 144 | Handle quotas in times of memory shortage. |
| 145 | |
| 146 | void receive_udp (string host, string msg) |
| 147 | Handle a received IMP message. |
| 148 | |
| 149 | void slow_shut_down (int minutes) |
| 150 | Schedule a shutdown for the near future. |
| 151 | |
| 152 | void notify_shutdown () |
| 153 | Notify the master about an immediate shutdown. |
| 154 | |
| 155 | ----------------------------------------------------------------- |
| 156 | Error Handling |
| 157 | |
| 158 | void dangling_lfun_closure () |
| 159 | Handle a dangling lfun-closure. |
| 160 | |
| 161 | void log_error (string file, string err) |
| 162 | Announce a compiler-time error. |
| 163 | |
| 164 | mixed heart_beat_error (object culprit, string err, |
| 165 | string prg, string curobj, int line) |
| 166 | Announce an error in the heart_beat() function. |
| 167 | |
| 168 | void runtime_error (string err, string prg, string curobj, int line) |
| 169 | Announce a runtime error. |
| 170 | |
| 171 | ----------------------------------------------------------------- |
| 172 | Security and Permissions |
| 173 | |
| 174 | int privilege_violation (string op, mixed who, mixed arg3, mixed arg4) |
| 175 | Validate the execution of a privileged operation. |
| 176 | |
| 177 | int query_allow_shadow (object victim) |
| 178 | Validate a shadowing. |
| 179 | |
| 180 | int query_player_level (string what) |
| 181 | Check if the user is of high enough level for several things. |
| 182 | |
| 183 | int valid_exec (string name) |
| 184 | Validate the rebinding of an IP connection by usage of efun |
| 185 | exec(). |
| 186 | |
| 187 | int valid_query_snoop (object obj) |
| 188 | Validate if the snoopers of an object may be revealed by |
| 189 | usage of the efun query_snoop(). |
| 190 | |
| 191 | int valid_snoop (object snoopee, object snooper) |
| 192 | Validate the start/stop of a snoop. |
| 193 | |
| 194 | ------------------------------------------------------------------ |
| 195 | Userids and depending Security |
| 196 | |
| 197 | string creator_file (mixed obj) |
| 198 | Return the name of the creator of an object. |
| 199 | This is called in every mode! |
| 200 | |
| 201 | string get_root_uid () // !compat |
| 202 | Return the string to be used as root-uid. |
| 203 | |
| 204 | string get_bb_uid() // !compat |
| 205 | Return the string to be used as root-uid. |
| 206 | |
| 207 | int valid_seteuid (object obj, string neweuid) // !compat |
| 208 | Validate the change of an objects euid by efun seteuid(). |
| 209 | |
| 210 | int|string valid_read (string path, string euid, string fun, object caller) |
| 211 | int|string valid_write (string path, string euid, string fun, object caller) |
| 212 | Validate a reading/writing file operation. |
| 213 | |
| 214 | ----------------------------------------------------------------- |
| 215 | ed() Support |
| 216 | |
| 217 | string make_path_absolute (string str) |
| 218 | Absolutize a relative filename given to the editor. |
| 219 | |
| 220 | int save_ed_setup (object who, int code) |
| 221 | Save individual settings of ed for a wizard. |
| 222 | |
| 223 | int retrieve_ed_setup (object who) |
| 224 | Retrieve individual settings of ed for a wizard. |
| 225 | |
| 226 | string get_ed_buffer_save_object_name (string file) |
| 227 | Return a filename for the ed buffer to be saved into. |
| 228 | |
| 229 | ---------------------------------------------------------------- |
| 230 | parse_command() Support (!compat) |
| 231 | |
| 232 | string *parse_command_id_list () |
| 233 | Return generic singular ids. |
| 234 | |
| 235 | string *parse_command_plural_id_list () |
| 236 | Return generic plural ids. |
| 237 | |
| 238 | string *parse_command_adjectiv_id_list () |
| 239 | Return generic adjective ids. |
| 240 | |
| 241 | string *parse_command_prepos_list () |
| 242 | Return common prepositions. |
| 243 | |
| 244 | string parse_command_all_word() |
| 245 | Return the one(!) 'all' word. |
| 246 | |
| 247 | SEE ALSO |
| 248 | master(M), efun(E), applied(A), concepts(C), driver(D), lpc(LPC) |