Update doc/efun/ aus Driversourcen.
Manpages der efuns aktualisiert, neue Manpages hinzugefuegt.
Change-Id: I7cc91684269ff56d1aef47d5c5e7c87f7fd531dc
diff --git a/doc/efun/shadow b/doc/efun/shadow
index 16ab11e..bf8d156 100644
--- a/doc/efun/shadow
+++ b/doc/efun/shadow
@@ -1,46 +1,44 @@
SYNOPSIS
- object shadow(object obj, int flag)
+ int shadow(object ob)
-BESCHREIBUNG
- Damit wird das aktuelle Objekt dem Objekt <obj> als Shadow
- uebergeworfen. Bei Erfolg liefert es 1, sonst 0 zurueck.
+DESCRIPTION
+ The current object will become a shadow of ob. This efun
+ returns 1 on success, 0 otherwise.
- Das aufrufende Objekt muss vom Master-Objekt die Erlaubnis haben,
- als Shadow zu wirken. Normalerweise kann einem Objekt, das
- query_prevent_shadow() == 1 zurueck liefert, kein Shadow
- uebergeworfen werden. In diesem Fall liefert shadow() 0 zurueck,
- sonst das Objekt, dem der Shadow uebergeworfen wurde.
+ The calling object must be permitted by the master object to
+ do the shadowing. In most installations, an object that
+ defines the function query_prevent_shadow() to return 1
+ can't be shadowed, and the shadow() function will return 0
+ instead of ob.
- shadow() schlaeft fehl, wenn:
- - der Shadow vesucht, eine "nomask" definierte Funktion zu
- ueberlagern,
- - wenn im Praeprozessor #pragma no_shadow gesetzt ist,
- - wenn das aufrufende Objekt bereits ein Shadow ist,
- - wenn das aufrufende Objekt selbst einen Shadow uebergeworfen hat,
- - wenn das aufrufende Objekt ueber ein Environment verfuegt,
- - wenn das Zielobjekt <obj> selbst ein Shadow ist.
+ shadow() also fails if the calling object tries to shadow
+ a function that was defined as ``nomask'', if the program was
+ compiled with the #pragma no_shadow, or if the calling
+ object is already shadowing, is being shadowed, or has an
+ environment. Also the target ob must not be shadowing
+ something else.
- Wenn ein Objekt A einem Objekt B als Shadow uebergeworfen wird,
- werden alle call_other() Aufrufe fuer B an A umgeleitet. Wenn A die
- Funktion, die von call_other() aufgerufen wird, nicht definiert hat,
- wird der Aufruf an B weitergeleitet. Es gibt also nur ein Objekt,
- welches call_other() Aufrufe fuer B machen kann: das Objekt A. Nicht
- einmal das Objekt B kann einen call_other() auf sich selbst machen.
- Hingegen werden alle normalen (internen) Funktionsaufrufe innerhalb
- von B werden wie gewohnt innerhalb von B bearbeitet.
+ If an object A shadows an object B then all call_other() to B
+ will be redirected to A. If object A has not defined the
+ function, then the call will be passed to B. There is only on
+ object that can call functions in B with call_other(), and
+ that is A. Not even object B can call_other() itself. All
+ normal (internal) function calls inside B will however remain
+ internal to B.
-BEISPIELE
- Mit drei Objekten a.c, b.c und c.c:
+EXAMPLES
+ With the three objects a.c, b.c and c.c
- --- a.c ---
- void fun() {
+ --- a.c ---
+ int fun() {
debug_message(sprintf("%O [a] fun()\n", this_object()));
}
+
void fun3() {
debug_message(sprintf("%O [a] fun3()\n", this_object()));
}
- --- b.c ---
+ --- b.c ---
int fun() {
debug_message(sprintf("%O [b] fun()\n", this_object()));
find_object("a")->fun();
@@ -53,7 +51,7 @@
void do_shadow(object target) { shadow(target, 1); }
- --- c.c ---
+ --- c.c ---
int fun() {
debug_message(sprintf("%O [c] fun()\n", this_object()));
find_object("a")->fun();
@@ -63,7 +61,7 @@
}
void do_shadow(object target) { shadow(target, 1); }
- Es wird nun folgender Code aufgerufen:
+ code like the following
object a, b, c;
@@ -81,39 +79,39 @@
debug_message("--- b->fun2() ---\n");
b->fun2();
- Das ergibt diesen Output:
+ produces this output:
- --- a->fun() ---
+ --- a->fun() ---
/c [c] fun()
/b [b] fun()
/a [a] fun()
- --- b->fun() ---
+ --- b->fun() ---
/c [c] fun()
/b [b] fun()
/a [a] fun()
- --- c->fun() ---
+ --- c->fun() ---
/c [c] fun()
/b [b] fun()
/a [a] fun()
- --- b->fun2() ---
+ --- b->fun2() ---
/b [b] fun2()
/a [a] fun3()
/c [c] fun3()
- Merke: der erste Aufruf in b::fun2() findet zuerst c::fun3()!
- Der Grund ist, dass fuer Aufrufe aus b fuer a der Treiber
- annimmt, dass alle Shadows vor c schon ihre Chance hatten. Der
- zweite Aufruf hingegen ergeht an b selbst, das der Treiber als
- vom Shadow c ueberlagert erkennt.
+ Note that the first call in b::fun2() find c::fun3()! Reason is that
+ for calls originating from b to a the driver assumes that all
+ shadows beyond c already had their chance. The second call however
+ was to b itself, which the gamedriver recognized as being shadowed
+ by c.
-GESCHICHTE
- Bis 3.2.1@46 fuehrte die Zerstoerung eines Objekts, dem ein Shadow
- uebergeworfen war, auch zur Zerstoerung aller seiner Shadows.
- Seit 3.2.1@47 ueberleben Shadows die Zerstoerung des Objektes, dem
- sie uebergeworfen sind (ausser, die wird von prepare_destruct()
- manuell erledigt).
- Seit LDMud 3.2.8 koenne sich Objekte dank #pragma no_shadow gezielt
- davor schuetzen, einen Shadow uebergeworfen zu bekommen.
+HISTORY
+ Up to 3.2.1@46, destructing a shadowed object also destructs
+ all shadows. Since 3.2.1@47, shadows may survive the
+ destruction of the shadowee (unless the prepare_destruct() in
+ the master object destructs them manually).
-SIEHE AUCH
+ Since LDMud 3.2.8, programs may protect themselves from being
+ shadowed with the #pragma no_shadow.
+
+SEE ALSO
query_shadowing(E), unshadow(E), query_allow_shadow(M)