blob: b55a9319855b343a288f19fc7b499ba616cb4dea [file] [log] [blame]
MG Mud User88f12472016-06-24 23:31:02 +02001NAME
2 master for LPMud 3.2
3
4DESCRIPTION
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
247SEE ALSO
248 master(M), efun(E), applied(A), concepts(C), driver(D), lpc(LPC)