Automatisch erzeugte Manpages.
Damit nicht jeder sphinx auf dem Rechner haben muss,
behalten wir bis auf weiteres die aus den .rst
erzeugten Manpoages auch im Repo.
Change-Id: Id556c0d11cf5f79659d8350952ce1c014d81ea44
diff --git a/doc/sphinx/man/sefun/shadow b/doc/sphinx/man/sefun/shadow
new file mode 100644
index 0000000..2b7032c
--- /dev/null
+++ b/doc/sphinx/man/sefun/shadow
@@ -0,0 +1,162 @@
+
+shadow()
+********
+
+
+FUNKTION
+========
+
+ object shadow(object ob, int flag)
+
+
+ARGUMENTE
+=========
+
+ object ob - das vom shadow betroffene Objekt
+ int flag - 0 fuer eine Shadow-Existenzabfrage
+ 1 fuer Shadow durch previous_object()
+
+
+BESCHREIBUNG
+============
+
+ Wenn <flag> nicht 0 ist, wird das aktuelle Objekt dem Objekt obj
+ als Shadow uebergeworfen. Bei Erfolg wird das geshadowte Objekt
+ zurueckgegeben, sonst 0.
+ Wenn <flag> 0 ist, wird entweder 0 oder das geshadowte Objekt
+ zurueck gegeben.
+
+ Wenn ein Objekt A ein Objekt B beschattet, werden alle call_other() fuer
+ B auf A umgeleitet. Wenn die an B gerufene Funktion in A existiert, so
+ wird sie in A gerufen, bei Nichtexistenz in B.
+ A ist das einzige Objekt, welche die beschatteten Funktionen mit
+ call_other() in B aufrufen kann, selbst B kann nicht per call_other()
+ diese Funktion rufen.
+ Alle intern verwendeten Funktionen arbeiten jedoch weiterhin normal.
+
+ Das aufrufende Objekt muss vom Master-Objekt die Erlaubnis haben,
+ als Shadow zu wirken.
+
+ Es gibt folgende Kriterien fuer eine erfolgreiche Beschattung:
+ - das zu beschattende Objekt ob:
+ - ist weder ein access_rights-Objekt noch ein ROOT-Objekt
+ - gibt beim Aufruf von query_prevent_shadow(beschatter) eine 0
+ zurueck
+ - beschattet selbst niemanden
+ - hat kein '#pragma no_shadow' gesetzt
+ - der Beschatter:
+ - wird nicht selbst (direkt) beschattet
+ - beschattet noch niemanden (sonst folgt direkter Abbruch)
+ - hat kein environment()
+ - definiert/beschattet keine Methode, die im beschatteten Objekt ob
+ als nomask definiert ist
+
+ Beschattet man ein Objekt A mit einem Objekt B und dann das Objekt A
+ zusaetzlich mit einem Objekt C, so wird eine Beschattungshierarchie
+ erstellt:
+
+ B macht shadow(A, 1)
+ B->A
+ C macht shadow(A, 1)
+ C->B->A
+
+
+BEISPIELE
+=========
+
+ // wenn: B beschattet A, dann
+ shadow(find_object(A), 0) == B
+
+
+ // 3 Objekte beschatten in Hierarchie (liegt auch im Pfad)
+ --- aa.c ---
+ void fun() {
+ printf("%O [a] fun()\n", this_object());
+ }
+
+ void fun3() {
+ printf("%O [a] fun3()\n", this_object());
+ }
+
+ --- bb.c ---
+ int fun() {
+ printf("%O [b] fun()\n", this_object());
+ find_object("/doc/beispiele/shadow/aa")->fun();
+ }
+
+ void fun2() {
+ printf("%O [b] fun2()\n", this_object());
+ find_object("/doc/beispiele/shadow/aa")->fun3();
+ this_object()->fun3();
+ }
+
+ void do_shadow(object target) { shadow(target, 1); }
+
+ --- cc.c ---
+ int fun() {
+ printf("%O [c] fun()\n", this_object());
+ find_object("/doc/beispiele/shadow/aa")->fun();
+ }
+
+ void fun3() {
+ printf("%O [c] fun3()\n", this_object());
+ }
+
+ void do_shadow(object target) { shadow(target, 1); }
+
+ // darauf arbeitender Code
+
+ object a, b, c;
+
+ destruct("/doc/beispiele/shadow/aa");
+ a = load_object("/doc/beispiele/shadow/aa");
+ destruct("/doc/beispiele/shadow/bb");
+ b = load_object("/doc/beispiele/shadow/bb");
+ destruct("/doc/beispiele/shadow/cc");
+ c = load_object("/doc/beispiele/shadow/cc");
+
+ b->do_shadow(a);
+ c->do_shadow(a);
+ printf("--- a->fun() ---\n");
+ a->fun();
+ printf("--- b->fun() ---\n");
+ b->fun();
+ printf("--- c->fun() ---\n");
+ c->fun();
+ printf("--- b->fun2() ---\n");
+ b->fun2();
+
+ // ... und seine Ausgabe:
+
+ --- a->fun() ---
+ /doc/beispiele/shadow/cc [c] fun()
+ /doc/beispiele/shadow/bb [b] fun()
+ /doc/beispiele/shadow/aa [a] fun()
+ --- b->fun() ---
+ /doc/beispiele/shadow/cc [c] fun()
+ /doc/beispiele/shadow/bb [b] fun()
+ /doc/beispiele/shadow/aa [a] fun()
+ --- c->fun() ---
+ /doc/beispiele/shadow/cc [c] fun()
+ /doc/beispiele/shadow/bb [b] fun()
+ /doc/beispiele/shadow/aa [a] fun()
+ --- b->fun2() ---
+ /doc/beispiele/shadow/bb [b] fun2()
+ /doc/beispiele/shadow/aa [a] fun3()
+ /doc/beispiele/shadow/cc [c] fun3()
+
+ // Der erste Aufruf von b::fun2() in a findet sofort a::fun3()! Der
+ // Driver nimmt an, dass alle Shadows ab c bei Rufen von b nach a
+ // schon ihre Chance hatten.
+ // Der zweite Aufruf allerdings ist auf b und wird beim Durchgeben
+ // an a von c uebernommen.
+
+
+SIEHE AUCH
+==========
+
+ Generell: shadow(E)
+ Rechte: query_allow_shadow(M), query_prevent_shadow(L)
+ Informationen: query_shadowing(E)
+
+8.Aug 2007 Gloinson