Beschreibung des DOS-Kernels von Mag!X V3.00/V4.xx/V5.xx/V6.xx
##############################################################

Andreas Kromke
Hannover, den 13.10.96

Formatierung: Tabulatoren alle 5 Spalten


Vorwort zur Version 4.50:
-------------------------

In dieser Version wurden Threads und Signale implementiert. Threads werden
auf AES-Ebene behandelt und sind in THREADS.TXT beschrieben, dort sind
auch Anmerkungen zur Verwendung von Signalen in "multi threaded"-Programmen
enthalten. Zur generellen Beschreibung des Signalkonzepts von MagiC siehe
SIGNALE.TXT. Zur Verwendung von Pipes und Unterschieden zur MiNT-
Spezifikation siehe PIPES.TXT



I Konzepte
==========


Das GEMDOS war bisher der konservativste Teil des Betriebssystems Mag!X. Fr
Netzwerktreiber muten praktisch smtliche DOS- Aufrufe einschlielich
Pexec() nachgebildet werden, ohne auf einer tieferen Ebene eingreifen zu
knnen. In Mag!X 1.x (wie in TOS) war das DOS nicht einmal reentrant, da ein
statisch angelegter Stack verwendet wurde.

In MultiTOS/MiNT wird das Problem dermaen umgangen, da gewissermaen ber
das GEMDOS ein System gelegt wird, das alle hheren Verwaltungsaufgaben
erledigt, andere Dateisysteme einbinden kann und das GEMDOS nur noch als
"dummen" Dateisystemtreiber verwendet. Vorteil dieses Systems ist seine groe
Flexibilitt und Erweiterbarkeit, ein entscheidender Nachteil aber der
gewaltive Overhead bei der Verwendung von "normalen" DOS- Dateisystemen. Dies
sind aber gerade diejenigen, die mit Abstand am hufigsten eingesetzt werden.
Hinzu kommt, da das GEMDOS- Dateisystem mit dem Einsatz von MiNT nichts an
Funktionalitt, Komfort oder Geschwindigkeit gewinnen kann, da ja die alten
Routinen nur mit zustzlichem Overhead ablaufen. Die Dateisystemzugriffe
unter MiNT sind also i.a. nicht reentrant, d.h. jeder Diskettenzugriff legt
wie unter MS-Windows den gesamten Rechner lahm.

Eine weitere Eigenschaft von MiNT ist das Bemhen, die Funktionen, die alle
Dateisysteme gemeinsam haben, in den Kernel zu bernehmen. Dabei bleiben zwar
die Dateisystemtreiber (MiNT-XFSs) kompakt, aber durch den Inode-
orientierten Aufbau der Kernelfunktionen wird den Dateitreibern eine unter
Umstnden ungnstige Struktur aufgezwungen, auerdem sind i.a. viele Aufrufe
des Dateisystemtreibers fr einen DOS- Aufruf notwendig. Schlielich ist der
MiNT- Kernel selbst sehr lang, liegt aber zum groen Teil brach, solange
keine anderen Dateisysteme als DOS eingesetzt werden.

Unter Mag!X wurde ein anderer Ansatz gewhlt, der darin bestand, das gesamte
GEMDOS einschlielich der Lowlevel- Funktionen fr die Sektorpufferung von
Grund auf neu zu schreiben und in insgesamt drei, vier oder fnf Schichten zu
zerlegen, in die von auen (durch nachgeladene Treiber) eingegriffen werden
kann. Als "Nebenwirkung" (dummdeutsch: Nebeneffekt) kam eine Erweiterung der
Funktionalitt des DOS- Dateisystems und ein zustzliches Dateisystem auf
dem logischen Laufwerk U: heraus. Das gesamte Konzept einschlielich der
Zugriffe auf DOS- Dateisysteme ist reentrant und luft im Hintergrund ab. So
ist es mglich, auf Laufwerk A: Dateien zu bearbeiten, ohne den Rechner bei
den Diskettenzugriffen merklich zu bremsen. Dabei ist Mag!X bisher nur um
10k lnger geworden. Im Vergleich zu MiNT wurden aber mehr Funktionen in die
Dateisystemtreiber ausgelagert, was diese zwar lnger macht, aber ihnen die
Mglichkeit gibt, die Funktionen wesentlich effizienter auszufhren. Das
DOS- Dateisystem ist eher noch etwas schneller als langsamer geworden.

Obwohl vollstndig in Assembler realisiert, handelt es sich um ein
objektorientiertes System mit virtuellen Funktionen und mehrstufigen
Vererbungen. Ein Dateideskriptor, wie in der Kernel verwendet und das XFS zur
Verfgung stellt, ist ein Objekt mit speziellen Daten und Funktionen. Das XFS
realisiert aber ein abgeleitetes Objekt mit weiteren Datenfeldern und
Funktionen. Der DFS- Untertreiber des DOS_XFS schlielich mu wiederum
weitere Funktionen und Daten im FD unterbringen und leitet die Klasse weiter
ab. Genauso sieht es mit dem DMD (drive medium descriptor) aus. Der Kernel
bentigt nur wenige Angaben, die unteren Schichten jedoch wesentlich mehr,
aber immer wieder verschiedene.

Die Schichten im einzelnen:

1. Der DOS-Kernel. Die Funktionen werden in der Datei MGX_DOS.TXT
   beschrieben.
   Der Kernel liegt im Mag!X selbst und wird direkt von den Anwender-
   Programmen ber trap #1 aufgerufen. Er enthlt Module fr die
   Speicherverwaltung, fr die Prozeverwaltung und fr die Dateiverwaltung.
   Letztere hat die folgenden "Unterschichten".
2. Das Dateisystem (XFS = extended (?) file system). Sein Aufbau ist
   grundstzlich verschieden von einem MiNT- XFS, erfllt aber denselben
   Zweck.
   MagiC fr Atari enthlt nur ein einziges XFS, das sogenannte "DOS_XFS",
   andere knnen eingebunden werden. MagiC fr Macintosh enthlt zustzlich
   intern das Mac-XFS.
   Der Aufbau eines XFS ist in der Datei MGX_XFS.TXT beschrieben.
   Speziell dieses Dateisystem greift wieder auf Untertreiber zu:
2a Ein DOS- Dateisystem (DFS) wird vom DOS_XFS aufgerufen. Hier stehen nur
   die Dateifunktionen, whrend die Verzeichnisverwaltung im wesentlichen vom
   DOS_XFS bernommen wird.
   Mag!X direkt enthlt zwei DFSs. Eines fr Laufwerk U:, ein zweites fr
   FAT- Dateisysteme, die auf BIOS- Laufwerken liegen.
   Weitere DFSs knnen eingebunden werden. Der Aufwand fr ein DFS ist
   wesentlich geringer als fr ein XFS, da viele Funktionen vom DOS_XFS
   bereits ausgefhrt werden. Die wesentliche Voraussetzung ist eine DOS-
   konforme Verzeichnisstruktur (mit 32-Byte-Eintrgen und Dateinamen des
   Formats 8+3).
   Der Aufbau eines DFS ist in der Datei MGX_DFS.TXT beschrieben. Der Kernel
   selbst kommt mit dem DFS nicht in Berhrung, sondern steuert ihn
   transparent ber das DOS_XFS an.
3. Die Dateitreiber (MX_DEV), die im wesentlichen das Lesen und Schreiben
   einer Datei erledigen. Sie werden vom XFS angelegt und verwaltet, aber
   bei Funktionen wie Fread() und Fwrite() direkt vom Kernel aufgerufen,
   wodurch extrem wenig Overhead entsteht.
   Das DOS_XFS enthlt tatschlich nur einen Dateitreiber. Dieser erledigt
   z.B. bei Schreibzugriffen die Aktualisierung des Verzeichnisses und ruft
   wieder Untertreiber (MX_DDEV) auf.
3a Der Untertreiber MX_DDEV wird nur vom DOS-Dateitreiber des Dateisystems
   DOS_XFS aufgerufen.
   Der Benutzer kann eigene MX_DDEVs ber das Verzeichnis U:\DEV\ einbinden.
   Der Aufbau des U-Dateisystems ist in MGX_UDFS.TXT beschrieben, der Aufbau
   der Struktur MX_DDEV in MGX_DFS.TXT. Der Kernel kommt mit den Untertreibern
   nicht in Berhrung.



II Die Systemfunktionen
=======================


unsigned WORD Sversion( void )
------------------------------

Liefert die DOS- Versionsnummer im Intel-Format. Der Rckgabewert in 
Mag!X ist tatschlich "long", das Hiword ist 0.
Es wird die Version 0.19 gemeldet, die TOS 1.4 (?) entspricht. Eine 
sichere Aussage ber die Mag!X- Versionnummer erhlt man ber die 
Mag!X- spezifischen AES- Variablen. Auer der DOS- Versionsnummer 
gibt es noch die TOS-Versionnummer (ist immer 4.0 fr Falcon, 3.0 fr 
TT und 2.0 fr ST) und die AES- Versionsnummer (4.00).


LONG Sconfig( WORD subfn, LONG flags)
-------------------------------------

Manipuliert das Konfigurations-Langwort, das auch ber den  MagiC- 
Cookie zugnglich ist.

* fn == SC_GETCONF	(0): Statuslangwort holen
* fn == SC_SETCONF	(1): Statuswert setzen
* fn == SC_DOSVARS	(2): Zeiger auf Systemvariable holen
* fn == SC_MOWNER	(3): Mowner
* fn == SC_WBACK	(4): WB-Daemon konfigurieren
*					subfn == 0:	PD des WBDAEMON ermitteln
*					subfn == 1:	PD setzen
*					subfn == 2:	WB abschalten
* fn == SC_INTMAVAIL(5): Internen Speicher erfragen
* fn == SC_INTGARBC (6):	garbage collection fr internen Speicher

Die Variable <flags> hat folgende Bedeutung:

     Bit 0:    Pfadberprfung ein
     Bit 1:    Einfgemodus fr GEMDOS und Dialogboxen
     Bit 2:    reserviert
     Bit 3:    reserviert
     Bit 4:    Fastload fr Diskette aus
     Bit 5:    TOS- Kompatibilitt ein
     Bit 6:    "smart redraw" aus
     Bit 7:    Grow- und Shrinkboxen aus
     Bit 8:    kein Halt nach TOS- Programmen
     Bit 9:    reserviert
     Bit 10:   Pulldown- Mens
     Bit 11:	DMA-Parallelbetrieb der Floppy aus

Die restlichen Bits sind reserviert und drfen nicht verndert 
werden. Mit mode == 0 werden die Bits gelesen, mit mode == 1 
geschrieben (geht nur bei deaktivierter Kompatibilitt), mit
mode == 2 erhlt man einen Zeiger auf die DOSVARS Struktur, die in 
MAGX.H definiert ist:

typedef struct
   {
   long      res0;       	        /* 					   */
   int       *dos_time;               /* Adresse der DOS- Zeit      */
   int       *dos_date;               /* Adresse des DOS- Datums    */
   long      res1;                    /*                            */
   long      res2;                    /*                            */
   long      res3;                    /* ist 0L                     */
   void      *act_pd;                 /* Laufendes Programm         */
   long      res4;                    /*                            */
   int       res5;                    /*                            */
   void      res6;                    /*                            */
   void      res7;                    /* interne DOS- Speicherliste */
   void      (*resv_intmem)();        /* DOS- Speicher erweitern    */
   long      (*etv_critic)();         /* etv_critic des GEMDOS      */
   char *    ((*err_to_str)(char e)); /* Umrechnung Code->Klartext  */
   long      res8;                    /*                            */
   long      res9;                    /*                            */
   } DOSVARS;

Mit Hilfe der Funktion resv_intmem() lt sich hnlich wie mit 
FOLDRnnn Speicher fr die interne Speicherverwaltung reservieren. Im 
Gegensatz zu TOS wird diese jedoch deutlich weniger belastet, so da 
ein  Erweitern i.a. nicht notwendig ist. Mu der Speicher erweitert 
werden, was auch in ADDMEM geschieht, bergibt man der Funktion 
resv_intmem() in a0 die Adresse und in d0 die Lnge des zu 
reservierenden Speicherblocks.
Der Prototyp fr den Event-Critic-Handler lautet "long etv_critic(int 
errcode, int drvnr)". Man beachte, da die Funktion die Argumente auf 
dem Stapel erwartet und daher in PureC als "cdecl" deklariert werden 
mu.
err_to_str() erwartet in d0 einen TOS- Fehlercode und gibt in d0 und 
a0 einen Zeiger auf die beschreibende Zeichenkette zurck. Bei einem 
ungltigen Fehlercode erhlt man in d0 eine Null und in a0 einen 
Zeiger auf die Zeichenkette "TOS Fehler".


void Syield( void )
-------------------

Ruft in MagiC direkt appl_yield() auf. Im AUTO- Ordner wird dieser 
Befehl ignoriert.


void Ssync( void )
------------------

Opcode 0x150.
Synchronisiert alle "gemounteten" Dateisysteme.
Existiert ab MagiC 4.01.


LONG Sysconf( WORD n)
---------------------

Liefert unter MiNT globale Beschrnkungen und Fhigkeiten des Systems.
Wird z.Zt. von Mag!X nicht untersttzt.


void Salert( char *mesg )
-------------------------

Schickt unter MiNT eine Fehlermeldung in die Alert-Pipe 
u:\pipe\alert, von wo aus ein Programm etwa ein form_alert() machen 
kann. Was wohl bei einem berlauf der Pipe unter MiNT passiert ?
Wird z.Zt. von Mag!X nicht untersttzt.


LONG Srealloc( LONG len )
-------------------------

Alloziert fr den Bildschirmspeicher einen Bereich der Lnge <len>. 
Ist <len> == -1, wird die maximal mgliche Gre des 
Bildschirmspeichers zurckgegeben. Der Bildschirmspeicher ist ein 
Block des ST-RAM, dessen Eigner der Bootproze ist. Die Adresse des 
Bildschirmspeichers (logbase oder physbase) wird nicht beeinflut.


WORD Tgetdate( void )
---------------------

Die Funktion ist unter Mag!X tatschlich "unsigned long". Es wird die 
Uhrzeit der DOS- Interrupt- Uhr geliefert, die fr das Festlegen der 
Dateidaten verwendet wird.


WORD Tsetdate( WORD date )
--------------------------

Die Funktion ist unter Mag!X tatschlich "unsigned long". Es wird 
sowohl die Uhrzeit der DOS- Interruptuhr als auch die der Echtzeituhr 
verndert. D.h. im ST die IKBD- Uhr, im Mega die "Mega"- Uhr und im 
TT die TT- Uhr. Rckgabewert ERROR, falls das Datum ungltig ist, 
sonst E_OK. Im Gegensatz zu TOS werden Monat oder Tag 0 sowie 
ein Datum > 2099 als Fehler erkannt.


WORD Tgettime( void )
--------------------

Die Funktion ist unter Mag!X tatschlich "unsigned long". Es wird die 
Uhrzeit der DOS- Interrupt- Uhr geliefert, die fr das Festlegen der 
Dateidaten verwendet wird.


WORD Tsettime( WORD time )
--------------------------

Die Funktion ist unter Mag!X tatschlich "unsigned long". Es wird 
sowohl die Uhrzeit der DOS- Interruptuhr als auch die der Echtzeituhr 
verndert. D.h. im ST die IKBD- Uhr, im Mega die "Mega"- Uhr und im 
TT die TT- Uhr. Rckgabewert ERROR, falls die Zeit ungltig ist, 
sonst E_OK. Im Gegensatz zu TOS werden Stunden > 23 als Fehler 
erkannt.



III Die Speicherverwaltungsfunktionen
=====================================


LONG Maddalt( void *start, ULONG size )
---------------------------------------

Fgt den Block zur Mag!X- Speicherverwaltung hinzu. Der Block bleibt 
Eigentum von DOS und darf nicht zurckgefordert werden. Wenn 
hinzugefgte Blcke nicht hintereinander liegen, ist die Anzahl der 
hinzufgbaren Blcke auf ca. 12 beschrnkt.
Rckgabe: ENSMEM    Startadresse oder Blocklnge ungerade oder zuviele
                    isolierte Blcke angemeldet
          E_OK      Block ist angemeldet.


void *Mxalloc( ULONG size, WORD mode )
--------------------------------------

mode == 0: nur ST-RAM
        1: nur alternatives RAM
        2: lieber ST-RAM
        3: lieber alternatives RAM
   Bit 14: dontfree
   andere Bits werden ignoriert

Alternatives RAM heit "alles auer ST-RAM", d.h. TT-RAM oder per Maddalt()
angemeldetes RAM.
Ist size == 0L, wird ein Pointer ((void *) 1L) geliefert. Dies aus
Kompatibilitt mit alten Programmen. Neuere TOS- Versionen melden einen
Fehler, liefern also NULL.
Ist size == -1L, wird die Gre des grten freien Blocks zurckgegeben. Im
Fall mode == 2 oder mode == 3 die Lnge des greren Blocks.

Achtung:  Unter Mag!X ist wegen stndiger Kontextwechsel nicht 
		garantiert, da ein Aufruf Malloc(Malloc(-1L)) 
		funktioniert. Abgesehen davon, da man niemals den ganzen 
		Speicher allozieren sollte!

Unter Mag!X werden seit der Version 1.0 alle Speicherallozierungen 
mitprotokolliert. Wenn die mit LIMITMEM vorgegebene Beschrnkung 
berschritten wird, wird ein Nullzeiger zurckgegeben. Im Fall
size == -1 wird das Minimum von freiem Speicher und noch nicht 
ausgeschpfter LIMITMEM-Beschrnkung zurckgegeben. Ausnahmem sind 
Aufrufe des Bildschirm-Managers (SCRENMGR), der die Mens 
kontrolliert. Dadurch wird sichergestellt, da auch per LIMITMEM 
beschrnkte Programme keine Probleme mit dem Redraw bei Mens haben.


void *Malloc( ULONG size )
--------------------------

Dieser Aufruf wird auf Mxalloc() mit den Modi 0 bzw. 3 zurckgefhrt,
abhngig von den Konfigurationsbits im Programmdatei-Header. Die
Konfigurationsbits werden z.Zt. in der Basepage abgelegt.


long Mfree( void *memblock )
----------------------------

Wird ein (von Malloc(0) gelieferter) Zeiger 1L bergeben, wird E_OK 
geliefert. Bei ungerader Adresse oder ungltigem Bereich wird EIMBA 
geliefert. Ansonsten wird der Block als frei markiert und die 
Speicherbeschrnkungsgrenze (->LIMITMEM) wieder erhht.
Es findet z.Zt. keine berprfung statt, ob der freizugebende 
Speicherblock tatschlich dem aufrufenden Proze gehrt. Dies ist 
besonders fr Debugger notwendig, die Speicherblcke ihrer 
Kindprozesse manipulieren. Vielleicht wird aber auch irgendwann 
einmal eine berprfung eingebaut.

Achtung: Mag!X 1.x und 2.x reagieren bei ungerader Adresse mit Bomben.
         Mag!X 1.10, 1.11 und 2.00 knnen bei ungltigen Speicheradressen
         auerhalb des tatschlich vorhandenen Speichers ebenfalls bomben.


long Mshrink( char *memblock, ULONG size )
------------------------------------------

Dem per M(x)alloc() allozierten Speicherblock, der bei Adresse <size>
beginnt, wird eine neue Gre zugewiesen. Im Gegensatz zu TOS kann man auch
Speicherblcke vergrern, solange darber ein gengend groer freier Block
liegt (ansonsten wird EGSBF zurckgegeben). Voraussetzung ist, da die
TOS-Kompatibilitt deaktiviert wurde.
Wird -1L als Gre bergeben, wird die grtmgliche Gre des Speicherblocks
zurckgegeben.
Wird 0L als Gre bergeben, wird der Block freigegeben. TOS (zumindest bis
1.4) reagiert darauf, wie knnte es anders sein, mit einem totalen
Systemabsturz.
Die LIMITMEM-Speicherbegrenzung wird bercksichtigt. Es wird aus denselben
Grnden wie bei Mfree nicht berprft, ob ein Block dem Aufrufer berhaupt
gehrt.
Eine berprfung auf ungltige oder ungerade Adressen findet z.Zt. nicht
statt. Normalerweise wird dieser Aufruf auch nur ein einziges Mal, nmlich
nach dem Programmstart erledigt. Ich will aber nicht ausschlieen, noch
einmal eine berprfung einzubauen.



IV Die Prozesteuerung
======================


void Pterm0( void )
-------------------

Wird direkt als Pterm(0) ausgefhrt.


void Ptermres( ULONG size, UWORD exitcode )
-------------------------------------------

Zunchst wird mit Mshrink( act_pd, size ) der Speicher des laufenden 
Programms verkleinert, dann wird Pterm( exitcode ) ausgefhrt. Dabei 
wird das laufende Programm zwar komplett terminiert und verliert 
seinen Prozestatus, aber alle allozierten Speicherblcke 
(insbesondere Basepage und Environment) bleiben erhalten.


void Pterm( UWORD exitcode )
----------------------------

Das aufrufende Programm wird terminiert, die Kontrolle wird an den
Parentproze zurckgegeben, dessen Pexec()-Aufruf erhlt als Rckgabewert den
auf ULONG erweiterten <exitcode>, d.h. $ffffffff heit "Schwerer Fehler beim
Ausfhren des Pexec-Befehls, das Programm konnte nicht gestartet werden",
$0000ffff dagegen "Programm ist gelaufen und beendete sich mit Pterm(-1) oder
Ptermres(.., -1)". Siehe auch ->AES/form_xerr().

Nebenbei: Aus historischen Grnden enthlt der Code fr Pterm den vom
          Alcyon-Compiler favorisierten Assembler-Befehl "link a6,#0", weil
          dieser von einigen Debuggern vorausgesetzt wird.

Bevor irgendwelche Manahmen ergriffen werden, wird ber Setexc() der
etv_term-Vektor ermittelt und ber diesen gesprungen. Anschlieend wird der
Proze ordentlich abgerumt, einschlielich VDI-Workstations, Informierung
aller XFSs ber xfs_pterm, Schlieen aller geffneten Dateien und aktuellen
Pfade und Lschen der Prozedatei in u:\proc\.


long Pexec(UWORD mode, ...)
---------------------------

Erstellt, ldt oder startet Prozesse.
Ein Problem bei Pexec mute speziell umgangen werden. Durch die
Unterbrechbarkeit der Folge

	Malloc(-1);
	Malloc();
	Pexec();
	Mshrink();

konnten, etwa beim Laden der Autostart- Applikationen und Accessories, keine
Programme gleichzeitig geladen werden. Daher wird der Taskwechsel fr eine
bestimmte Zeit nach dem Start des Programms verhindert, bis der Mshrink()-
Aufruf erfolgt ist.

In neueren Versionen von MagiC wird beim Laden eines Programms kein Fsfirst()
mehr gemacht, damit Programme auch lange Namen haben knnen.
Das DOS-XFS wertet z.Zt. noch Wildcards bei Fopen() aus, d.h. Aufrufe
wie Pexec("nvdi.pr?") sind mglich (sollten aber vermieden werden!!).
Nicht mglich sind '?' beim Mac-XFS sowie bei allen zuknftigen XFSs.
Fr U:\PROC wird der Name in 8+3 und Groschrift gewandelt. Enthlt der
Name ein '?', kann er nicht angezeigt werden.
Die _PNAM Environmentvariable enthlt jetzt den Dateinamenteil, der bei
Pexec() angegeben wurde, d.h. den reinen Namen ohne Pfad.
Der Applikationsname wird ggf. durch Krzen aus dem Dateinamen ermittelt.

Modus 0 (EXE_LDEX):
     long Pexec(EXE_LDEX, char *name, char *cmdline, char *env)

     Dieser Modus ist kompatibel zu TOS.
     Die Programmdatei mit dem Pfad <name> wird geladen und gestartet. Es
     wird die Kommandozeile <cmdline> und das Environment <env> bergeben.
     Ist env == NULL, wird das Environment des Parent vererbt.
     Ist env == -1L, wird kein Environment angelegt, in der Basepage steht
     dann ein Nullzeiger.
     Rckgabe 0x0000yyyyL, wenn das Programm geladen und gestartet wurde und
     sich mit Pterm(0xyyyy) beendet hat. Konnte das Programm nicht geladen
     oder nicht gestartet werden, wird ein negatives Langwort geliefert.

Modus 3 (EXE_LD):
     PD *Pexec(EXE_LD, char *name, char *cmdline, char *env)

     Dieser Modus ist kompatibel zu TOS.
     Die Programmdatei mit dem Pfad <name> wird geladen. Es
     wird die Kommandozeile <cmdline> und das Environment <env> bergeben.
     Ist env == NULL, wird das Environment des Parent vererbt.
     Ist env == -1L, wird kein Environment angelegt, in der Basepage steht
     dann ein Nullzeiger.
     Rckgabe: Zeiger auf die Basepage des neuen Prozesses oder negativer
     Fehlercode.

Modus 4 (EXE_EX):
     long Pexec(EXE_EX, void *dummy, PD *basepage)

     Dieser Modus ist kompatibel zu TOS.
     Das Programm, dessen Basepage bergeben wird, wird gestartet.
     Rckgabe 0x0000yyyyL, wenn das Programm gestartet wurde und sich mit
     Pterm(0xyyyy) beendet hat. Konnte das Programm nicht gestartet werden,
     wird ein negatives Langwort geliefert.

Modus 5 (EXE_BASE):
     PD *Pexec(EXE_BASE, void *dummy, char *cmdline, char *env)

     Dieser Modus ist kompatibel zu TOS.
     Ein Proze wird erzeugt. Es wird die Kommandozeile <cmdline> und das
     Environment <env> bergeben.
     Ist env == NULL, wird das Environment des Parent vererbt.
     Ist env == -1L, wird kein Environment angelegt, in der Basepage steht
     dann ein Nullzeiger.
     Rckgabe: Zeiger auf die Basepage des neuen Prozesses oder negativer
     Fehlercode.

Modus 6 (EXE_EXFR):
     long Pexec(EXE_EX, void *dummy, PD *basepage)

     Dieser Modus ist kompatibel zu TOS 1.4.
     Wie Modus 4, aber Basepage und Environment gehren dem neuen Proze.

Modus 7 (EXE_XBASE):
     PD *Pexec(EXE_BASE, ULONG prgflags, char *cmdline, char *env)

     Dieser Modus ist kompatibel zu TOS > 3.0 (?).
     Wie Modus 5, aber per <prgflags> knnen die Programmflags festgelegt
     werden, die festlegen, ob das Programm im TT-RAM luft bzw. TT-RAM
     per Malloc() alloziert usw.

Modus 102 (XEXE_TERM):
     long Pexec(EXE_TERM, void *dummy, PD *basepage)

     Der Proze wird gelscht.

Modus 101 (XEXE_INIT):
     long Pexec(EXE_TERM, void *dummy, PD *child, PD *parent)

     Vererbt Pfad- und Dateihandles

Modus 107 (XEXE_XBASE):
     PD *Pexec(EXE_BASE, ULONG prgflags, char *name, char *env)

     wie Modus 7, aber statt einer Kommandozeile wird der Prozename
     bergeben.

Modus 106 (XEXE_EXFR):
     wird ab Mag!X 2.00 nicht mehr untersttzt.

Modus 108 (XEXE_EXACC):
     wird intern zum Starten eines ACC verwendet.

Pexec und das ARGV-Verfahren:

MultiTOS implementiert das Verfahren im AES. Man mu den Parameter iscr,
der in MagiC anderweitig belegt ist und "isover" heit, auf 1 setzen, dann
erstellt MultiTOS das ARGV im Environment.

MagiC implementiert ARGV auf einem tieferen Level. Das ARGV- Verfahren wird
auf drei Arten bereits von Pexec untersttzt:

     1. Ist das Lngenbyte der Kommandozeile $7f, geht Pexec davon aus, da
        das aufrufende Programm ARGV untersttzt und das Environment
        entsprechend manipuliert ist.
        Pexec ndert daher nicht das Environment.
     2. Ist das Lngenbyte $fe, erwartet MagiC direkt dahinter die
        Zeichenkette "ARGV=", gefolgt von einem Nullbyte und von einer durch
        zwei Nullbytes abgeschlossenen Liste von Parametern. Durch bergaben
        von "ARGV=NULL..." usw. kann man auch das erweiterte ARGV-Verfahren
        verwenden, das die bergabe von leeren Parametern ermglicht.
        Pexec lscht ein evntl. vorhandenes ARGV und trgt das neue ins
        Environment ein. Die Kommandozeile besteht nur aus $7f als Indikator,
        da die Parameter im Environment liegen.
        Das Verfahren ist geeignet, wenn das aufgerufene Programm mit
        Sicherheit das ARGV-Verfahren beherrscht.
     3. Ist das Lngenbyte $ff, erwartet MagiC direkt dahinter eine durch
        Leerstellen getrennte und durch ein Nullbyte abgeschlossene Liste von
        Parametern (wie i.a. als Kommandozeile bergeben wird).
        Pexec lscht ein evntl. vorhandenes ARGV, erstellt aus der
        Kommandozeile eine Argumentliste und trgt diese als ARGV ins
        Environment ein. Als argv[0] wird der Programmdatei-Pfad genommen,
        der Pexec bergeben wurde. Ist dieser Pfad ungltig, gibt es Mll,
        deshalb sollte man auch bei Modus 5 (Basepage erstellen) einen
        sinnvollen Programmnamen bergeben. Bei Modus 7 heit argv[0] dann
        einfach "NONAME", weil hier kein Name bergeben wird.
        Die Kommandozeile hat als Lngenbyte $7f als Indikator fr das
        Vorhandensein von ARGV. Ist die Lnge der Kommandozeile < 127, wird
        diese auerdem in die Basepage kopiert, ansonsten besteht die
        Kommandozeile nur aus $7f.
        Das Verfahren ist geeignet, wenn das aufrufende Programm nicht sicher
        ist, da das aufgerufene Programm ARGV versteht.


WORD Pvfork( void )
-------------------

Erzeugt unter MiNT einen neuen Proze, der mit dem alten identisch ist. Der
alte wird angehalten, bis der neue ein anderes Programm ldt oder sich
beendet.
Wird z.Zt. von Mag!X nicht untersttzt.


LONG Pwait( void )
------------------

Ermittelt unter MiNT angehaltene oder beendete Kind-Prozesse.
Wird von MagiC ab Version 5.04 untersttzt und ist als

	Pwaitpid(-1, 2, NULL);

implementiert.


LONG Pwaitpid( WORD pid, WORD nohang, LONG *rusage )
----------------------------------------------------

Wartet auf Terminierung oder Anhalten von Kindprozessen und ermittelt
deren CPU-Auslastung und Exit-Code. Die Parameter haben folgende Bedeutung:

	pid	-1	Bercksichtige alle Kindprozesse
	     >0	Bestimmter Kindproze
	     0	Bercksichtige alle Kindprozesse mit derselben Prozegruppe
	     	wie der Elterproze (= Aufrufer)
	     <0	Bercksichtige alle Kindprozesse mit Prozegruppe (-pid).

	nohang
	 Bit 0=0	Warte, bis ein Ereignis (Terminierung oder Anhalten eines
	 		Kindprozesses) eintrifft.
	      =1	Gib 0 zurck, falls kein Ereignis eingetroffen war.
	 Bit 1=0	Bercksichtige nur diejenigen Kinder, die terminiert sind
	 		 oder per TRACE angehalten wurden.
	 	 =1	Bercksichtige alle angehaltenen oder terminierten Kinder

	rusage	Wenn != NULL, wird in rusage[0,1] die User/Systemzeit des
			Kindes zurckgegeben.

Der Rckgabewert hat die Process-ID im Hiword und den Rckgabewert 
des Kindes im Loword. EFILNF wird geliefert, wenn keine Kinder 
existieren.
Wird von MagiC seit der Version 5.04 untersttzt, jedoch ohne 
Bercksichtigung von angehaltenen Kindern (d.h. nur Terminierung von 
Kindern wird erkannt). Weiterhin werden in <rusage> immer Nullen 
zurckgegeben. Prozegruppen werden von MagiC 5.04 noch nicht richtig 
untersttzt, da der Aufruf Psetpgrp() fehlt.


WORD Pnice( WORD delta )
------------------------

ndert unter MiNT die Prioritt des laufenden Prozesses.
Wird z.Zt. von Mag!X nicht untersttzt.


LONG Pusrval( LONG val )
------------------------

Setzt und ermittelt (val == -1) unter MiNT den "user value", ein 
Langwort, das Prozesse an ihre Kinder vererben und das vom Kernel 
nicht verwendet wird.
Wird von MagiC ab der Version 5.04 untersttzt.


WORD Pdomain( WORD dom )
------------------------

Mit diesem Aufruf kann ein Proze das Verhalten einiger Systemaufrufe
beeinflussen. Wird <dom>=1 bergeben, wird der MiNT-Modus aktiviert,
ansonsten ist (per Default) <dom>=0, dies entspricht dem TOS-Modus.
In jedem Fall wird der vorherige Wert zurckgegeben, wenn man ihn nicht
ndern will, mu man <dom>=-1 bergeben.
Andere Werte als 0 oder 1 fhren unter MagiC zu ERANGE. MagiC untersttzt
Pdomain() seit der Version vom 5.11.95.
Der Wechsel der "Domain" nach MiNT (dom=1) hat folgende Auswirkungen:

In MiNT ergeben sich Unterschiede bei Fread() und Fwrite() auf Terminals,
das Verhalten wird mit speziellen Fcntl()- Aufrufen festgelegt. Weiterhin
knnen Fsfirst()/Fsnext() auch Dateinamen zurckgeben, die nicht der
Form 8+3 in Groschrift entsprechen.

In MagiC liefern Fsfirst()/Fsnext() immer Dateinamen im Format 8+3. Eine
andere Vorgehensweise ist auch sinnlos, weil "moderne" Programme statt
dieser berholten Funktionen immer D(x)readdir() verwenden; ansonsten
lieen sich auch keine Dateinamen mit mehr als 12 Zeichen verwenden.

Die entsprechenden Terminal-Funktionen sind in MagiC nicht enthalten, so
da sich hier auch keine Unterschiede zur TOS-Domain ergeben.

Der Aufruf ist aber dennoch wichtig, weil er das Verhalten des 
Dateiauswahldialogs beeinflut, wenn er mit der TOS-
Kompatibilittsfunktion fsel(ex)input() aufgerufen wird. Als maximal 
mgliche Dateinamenlnge wird in der MiNT-Domain 32 angenommen (inkl. 
EOS). In der TOS-Domain ist die Lnge auf 13 beschrnkt, und die 
Verzeichnisse werden im TOS-Kompatibilittsmodus mit 8+3-Dateinamen 
gelesen (->Dopendir(DOPEN_COMPAT)). Genauer: Wird der Aufruf 
fsel(ex)input() von einem Programm ausgefhrt, das sich in der TOS-
Domain befindet, wird xfsl_do() mit dem Modus DOSMODE+SHOW8P3 
aufgerufen, ansonsten mit SHOW8P3.

Auf die "modernen" Dateiauswahlfunktionen (xfsl_xx()) hat die Domain
keinen Einflu, weil hier das Verhalten und die Limits der Dateiauswahl
explizit festgelegt werden knnen.


WORD Pfork( void )
------------------

Soll eigentlich eine Kopie des aktuellen Prozesses anlegen (d.h. 
nicht denselben Kontext, sondern den gleichen, also eine Kopie), was 
aber in MiNT noch nicht so funktioniert. Stattdessen funktioniert 
Pfork z.Zt. wie Pvfork().
Wird z.Zt. von Mag!X nicht untersttzt.


LONG Pwait3(WORD flag, LONG *rusage)
------------------------------------

Ermittelt unter MiNT den Exit- Status und die CPU- Belastung
eines terminierten oder beendeten Kind- Prozesses.
Wird von MagiC ab Version 5.04 untersttzt und ist als

	Pwaitpid(-1, flag, rusage);

implementiert.


void Prusage(LONG *r)
---------------------

Ermittelt unter MiNT Informationen ber CPU- und Speicherbelastung 
des aktuellen Prozesses.
Wird z.Zt. von Mag!X nicht untersttzt, zumindest der belegte 
Speicher unter r[4] sollte aber in Krze eingebaut werden, vielleicht 
kann man die anderen Werte auf 0 setzen.


LONG Psetlimit( WORD lim, LONG value )
--------------------------------------

Setzt oder ermittelt unter MiNT das Limit fr Speicher und CPU- 
Belastung fr den aktuellen Proze. Unter MiNT stehen folgende 
Unterfunktionen zur Verfgung:

lim = 1:	Limitiert die Prozessorzeit. Diese Funktion ist in MagiC nicht
		implementiert.

lim = 2:	Limitiert den Gesamtspeicherbedarf eines Prozesses inklusive
		Programmcode. Ist in MagiC nicht implementiert, da die
		Funktion 3 sinnvoller ist.

lim = 3:	Unter MagiC seit dem 17.9.95 implementiert.
		Mit dieser Funktion wird fr den aktuellen Proze das Limit 
		fr allozierten Speicher festgelegt. Rckgabewert ist immer 
		die vorherige Einstellung.
		bergibt man als <value> z.B. den Wert 8000, so kann der 	
		Proze auer Basepage+Textsegment+Datensegment+BSS-Segment 
		noch 8000 zustzliche Bytes allozieren.
		Ist <value> == 0L, wird das Limit auf "unbegrenzt" festgelegt.
		Ist <value> == -1L, wird nur der aktuelle Wert zurckgegeben.

		Bei Pexec() wird dieses Limit vererbt. Das gestartete 
		Programm selbst (d.h. der Programmcode) kann dabei beliebig 
		gro sein, begrenzt wird nur der Heap, d.h. beim Laden der 
		Speicherblock hinter dem BSS-Segment, spter die Malloc-
		Aufrufe.
		Ist ein Programm mit dem MagiC-Dienstprogramm LIMITMEM 
		modifiziert worden, hat diese Einstellung Vorrang vor dem 
		Speicherlimit des aufrufenden Prozesses.
		Psetlimit wird vom erweiterten shel_write()-Modus 
		untersttzt, damit knnen speicherbeschrnkte Applikationen 
		auch parallel gestartet werden.

Ungltige Funktionsnummern und solche, die von MagiC nicht 
untersttzt werden, liefern EINVFN.


LONG Pmsg( WORD mode, LONG mboxid, struct msg *msgptr )
-------------------------------------------------------

Sendet oder empfngt unter MiNT Nachrichten. Der Mechanismus ist 
unabhngig von den AES-Funktionen appl_read/write.
Wird z.Zt. von Mag!X nicht untersttzt.


LONG Prenice( WORD pid, WORD delta )
------------------------------------

ndert unter MiNT die Prioritt eines laufenden Prozesses.
Wird z.Zt. von Mag!X nicht untersttzt.


LONG Pumask( WORD mask )
------------------------

ndert unter MiNT den Modus (d.h. die Dateirechte), in dem Fcreate() und
Dcreate() Dateien erstellen. Dabei bestimmen die Bits von <mask>, welche
Rechte die Datei _NICHT_ haben soll. Da es keine Mglichkeit gibt, die
Maske nur abzufragen, ohne sie zu verndern, mu man offenbar
Schweinereien machen wie

	Pumask((mode = (int)Pumask(0));

Die Dateimaske wird an Kindprozesse vererbt und ist von MagiC beim Booten
auf Null gesetzt. Die Maske wird von keinem der internen XFS von MagiC
ausgewertet und hat ihren Sinn ausschlielich auf UNIX-hnlichen
Dateisystemen.
Wird in MagiC seit der Version 5.04 untersttzt. Fr ein XFS ist die
Maske ber Offset 0x64 der Basepage erreichbar (->MGX_XFS.INC).


LONG Psemaphore( WORD mode, LONG id, LONG timeout )
---------------------------------------------------

Setzt und erstellt Semaphoren (->MiNT). Der Parameter <timeout> wird nur fr
Modus 2 verwendet und gibt die Timeout-Zeit in ms an, ein Wert von -1
bedeutet, da beliebig lang gewartet wird.
Semaphoren werden bei Terminierung des besitzenden Prozesses automatisch
freigegeben, nicht jedoch gelscht.

Modus PSEM_CRGET   (0):
     Eine neue Semaphore mit der <id> wird erstellt und dem Proze
     zugeordnet. Hierzu mu interner Speicher angefordert werden, deshalb
     sollte der Aufruf sparsam verwendet werden.
     Die Semaphore wird bei Terminierung des Prozesses zwar freigegeben (wie
     mit PSEM_RELEASE), jedoch nicht entfernt (also kein PSEM_DESTROY).
     Der Parameter <timeout> wird ignoriert.
     Fehlercode EACCDN: Semaphore existiert bereits

Modus PSEM_DESTROY (1):
     Die Semaphore <id> wird gelscht und der reservierte interne Speicher
     wieder freigegeben. Plausibilittsberprfungen stellen sicher, da
     keine System-Semaphoren entfernt werden knnen.
     Das funktioniert nur, wenn vorher ein PSEM_GET bzw. PSEM_CRGET gemacht
     wurde.
     Fehlercode ERANGE: Semaphore existiert nicht
                EACCDN: Semaphore gehrt mir nicht

Modus PSEM_GET     (2):
     Die Semaphore <id> wird gesetzt, d.h. fr den Proze reserviert.
     Fehlercode ERANGE: Semaphore existiert nicht (mehr)
                ERROR:  Semaphore gehrt mir schon
                EACCDN: Timeout

Modus PSEM_RELEASE (3):
     Die Semaphore <id> wird freigegeben.
     Fehlercode ERANGE: Semaphore existiert nicht
                EACCDN: Semaphore gehrt mir nicht.



V Funktionen fr die Proze-ID
==============================


WORD Pgetpid( void )
--------------------

Gibt die Proze-ID des aktuellen Prozesses zurck. Es gibt keinen Fehlerfall,
die Proze-ID ist immer gltig. Die Proze-ID ist der Dateityp, unter dem der
aktuelle Proze in u:\proc gefhrt wird. D.h. hat der aktuelle Proze die ID
5, entspricht die zugehrige Datei dem Muster "u:\proc\*.005".
Wie in MiNT schon immer, werden ab MagiC 4.50 die Proze-IDs aufsteigend
vergeben, es werden keine IDs wiederverwendet, wenn ein Proze beendet wird,
bevor nicht alle IDs bis 999 benutzt waren.


LONG Pgetppid( void )
---------------------

Gibt die Proze-ID des Parent des aktuellen Prozesses zurck. Im Gegensatz zu
MiNT kann der Fehler auftreten, da der Proze keinen Parent hat, dann wird
-1L zurckgegeben.


WORD Pgetpgrp( void )
---------------------

Gibt unter MiNT die aktuelle Prozegruppennummer zurck.
Wird z.Zt. von Mag!X nicht untersttzt.


LONG Psetpgrp( WORD pid, WORD newgrp )
--------------------------------------

Setzt unter MiNT die Prozegruppennummer des Prozesses <pid>.
Wird z.Zt. von Mag!X nicht untersttzt.


WORD Pgetuid( void )
--------------------

Ermittelt unter MiNT die User-ID des aktuellen Prozesses.
Wird z.Zt. von Mag!X nicht untersttzt.


WORD Psetuid( WORD uid)
-----------------------

ndert unter MiNT die User-ID des aktuellen Prozesses.
Wird z.Zt. von Mag!X nicht untersttzt.


WORD Pgetgid( void )
--------------------

Ermittelt unter MiNT die Group-ID des aktuellen Prozesses.
Wird z.Zt. von Mag!X nicht untersttzt.


WORD Psetgid( WORD uid)
-----------------------

ndert unter MiNT die Group-ID des aktuellen Prozesses.
Wird z.Zt. von Mag!X nicht untersttzt.


WORD Pgeteuid( void )
--------------------

Ermittelt unter MiNT die effektive User-ID des aktuellen Prozesses.
Wird z.Zt. von Mag!X nicht untersttzt.


WORD Pgetegid( void )
--------------------

Ermittelt unter MiNT die effektive Group-ID des aktuellen Prozesses.
Wird z.Zt. von Mag!X nicht untersttzt.



VI Signal-Funktionen
====================


WORD Pkill(WORD pid, WORD sig)
------------------------------

Die Funktion sendet das Signal sig an einen oder mehrere Prozesse.
Der Parameter <pid> bedeutet:

	> 0	Proze mit der angegebenen pid
	= 0  alle Prozesse der Prozegruppe des Aufrufers (inkl.)
	< 0	an alle Prozesse mit der Gruppennummer (-pid).

Das Signal SIGNULL kann dazu verwendet werden, die Gltigkeit des Parameters
<pid> zu testen; es ist nicht tatschlich ein Signal.

Rckgabewerte:

	EFILNF: falls pid > 0 und der angegebene Proze nicht mehr
             existiert bzw. falls pid < 0 und die angegebene
             Prozegruppe keine Mitglieder mehr besitzt.

	EACCDN: falls pid > 0, und der sendende Proze keine euid
             von 0 besitzt und auerdem die UID des empfangenden
             von der des sendenden Prozesses abweicht.

	ERANGE: sig ist kein gltiges Signal (z.B. < 0 oder > 30).

In MagiC 4.5 existiert wegen der einfacheren Prozesteuerung nur die erste
Version von Pkill, d.h. es kann nur eine pid > 0 angegeben werden. EACCDN
kann bisher nicht geliefert werden, da Prozesse bisher keine UserID kennen.


LONG Psignal(WORD sig, LONG handler)
------------------------------------

Wird unter MagiC zurckgefhrt auf

	Psigaction(sig, {handler,0L,0}, &oact);
	return(oact.handler);

D.h. im Gegensatz zu Psigaction() werden Extramaske und Flags einfach 
auf Null gesetzt.
Wird von MagiC ab V4.50 untersttzt.


LONG Psigblock( LONG mask )
---------------------------

<mask> gibt als Bitmaske an, welche Signale zustzlich blockiert 
werden (d.h. neumask = altmask OR mask); der alte Wert wird 
zurckgegeben. Die nicht maskierbaren Signale SIGKILL, SIGSTOP und 
SIGCONT werden automatisch aus der Signalmaske ausgefiltert.
Wird von MagiC ab V4.50 untersttzt.


LONG Psigsetmask( LONG mask )
-----------------------------

<mask> gibt als Bitmaske an, welche Signale blockiert werden (d.h. 
neumask = mask); der alte Wert wird zurckgegeben. Die nicht 
maskierbaren Signale SIGKILL, SIGSTOP und SIGCONT werden automatisch 
aus der Signalmaske ausgefiltert.
Wird von MagiC ab V4.50 untersttzt.


LONG Psigreturn( void )
-----------------------

Siehe ->SIGNALE.TXT.
Wird innerhalb einer Signalbehandlung benutzt, um diese 
abzuschlieen, um per "longjump" in das Hauptprogramm zurckzukehren.
Fhrt bei MiNT zum Systemabsturz, zumindest wenn in Verbindung mit 
AES verwendet.
In MagiC wird der Thread der aktiven Signalbehandlung zum Main-Thread 
des Prozesses und wird anschlieend entfernt. Alle anderen 
Signalbehandlungen werden ebenfalls entfernt (bei Verschachtelung). 
Die gesperrten Semaphoren des Main-Thread werden freigegeben. Der 
Supervisor-Stack des Main-Thread wird auf den Wert bei Prozestart 
zurckgesetzt.
In MiNT ist diese Funktion "void". In MagiC wird EACCDN geliefert, 
falls der Aufrufer keine Signalbehandlungsroutine ist, sonst E_OK.
Wird von MagiC ab V4.50 untersttzt.


LONG Talarm( LONG time )
------------------------

Initiiert in MiNT einen Alarm, der den aktuellen Proze in <time> Sekunden
terminiert, wenn das Signal SIGALRM nicht abgefangen wird.
Wird z.Zt. von Mag!X noch nicht untersttzt.


void Pause( void )
------------------

Wie Psigpause(), aber die Signalmaske wird nicht verndert. Damit ist 
diese Funktion im Gegensatz zu Psigpause() MT-safe.
Wird von MagiC ab V4.50 untersttzt.


LONG Psigpending( void )
------------------------

Ermittelt die Bitmaske der anliegenden (blockierten) Signale.
Wird von MagiC ab V4.50 untersttzt.


void Psigpause( LONG mask )
---------------------------

Der Proze (bzw. in MagiC der Thread) ndert die Signalmaske in 
<mask> und legt sich bis zum nchsten Signal schlafen. Nach 
Abarbeitung des Signalhandlers wird der Proze (in MagiC: alle 
wartenden Threads) wieder aufgeweckt und die Signalmaske restauriert.
Wenn mehrere Threads gleichzeitig Psigpause() machen, kann es 
Probleme geben, weil die Signalmaske prozeglobal ist (->SIGNALE.TXT).
Wird von MagiC ab V4.50 untersttzt.


LONG Psigaction( WORD sig, struct sigaction *sigact, struct sigaction *oact)
----------------------------------------------------------------------------

Siehe auch ->SIGNALE.TXT.
Die Funktion ndert das Signalverhalten fr Signal <sig> (wenn 
<sigact> != NULL) und fragt optional das alte Verhalten ab (wenn 
<oact> != NULL).
Eine <sigaction>-Struktur hat folgenden Aufbau:

		typedef struct
		{
		        void    cdecl (*sa_handler)( LONG sig );
		        LONG    sa_mask;
		        WORD    sa_flags;
		} SIGACTION;

<sa_handler> ist entweder 0 (Default-Signal-Behandlung durch das System) oder
1 (Signal ignorieren), sonst die Adresse einer Signalbehandlungsroutine. Diese
wird im User-Modus ausgefhrt, bekommt auf dem Stack als LONG die 
Signalnummer. Der Signalhandler wird normalerweise mit dem Ende der 
Prozedur (mit rts) beendet, alternativ kann er mit Psigreturn() und 
anschlieendem longjmp beendet werden. Im letzten Fall werden ALLE 
laufenden Signalbehandlungen abgebrochen und das Hauptprogramm nicht 
wieder aufgenommen, sondern der Signalhandler wird zum Hauptprogramm.

<sa_mask> enthlt die zustzlich (zu dem gerade bearbeiteten 
Signal) whrend der Signalbehandlung zu maskierenden Signale (d.h. 
dann gilt mask = oldmask+(1<<sig)+sa_mask).

<sa_flags> beeinflut das Verhalten des Signals:

	SA_NOCLDSTOP (1)
		legt in MiNT fest, da SIGCHLD nur beim Terminieren, nicht beim
		Anhalten eines Kindprozesses ausgelst wird.


Ein Aufruf von Psigaction hat die Nebenwirkung, das Signal zu 
demaskieren (d.h. freizugeben). Daher kann ein Proze beim 
Abarbeiten eines Signals dieses zurcksetzen und es sich erneut 
senden.

Rckgabewerte:

	EACCDN: Signal kann vom Benutzer nicht abgefangen werden.
			(SIGKILL oder SIGSTOP)
	ERANGE: sig ist kein gltiges Signal (< 0 oder > 30).

Wird von MagiC ab V4.50 untersttzt.



V Diskverwaltung
================


LONG Dsetdrv( WORD drv )
------------------------

Setzt <drv> als aktuelles Laufwerk des aktuellen Prozesses. Unter MagiC 3
sind Werte zwischen 0 und 25 zulssig, unter TOS nur zwischen 0 und 15. Es
wird keinerlei berprfung vorgenommen, ob das Laufwerk berhaupt existiert.
Zurckgegeben wird der Rckgabewert des BIOS- Aufrufs Drvmap().


LONG Dgetdrv( void )
--------------------

Liefert das aktuelle Laufwerk des aktuellen Prozesses. MagiC 3 verwaltet
bis zu 26 Laufwerke (A: bis Z:), whrend ltere Versionen sowie alle TOS-
Versionen 16 Laufwerke (A: bis P:) verwalten knnen.


LONG Dfree( DISKINFO *d, WORD drivecode )
-----------------------------------------

Wenn <drivecode> Null ist, wird der freie Platz des Laufwerks geliefert, auf
dem der aktuelle Pfad des aktuellen Laufwerks liegt. Andernfalls der freie
Platz von Laufwerk <drivecode - 1>.
Beispiel: Ist U: das aktuelle Laufwerk und \A\ der aktuelle Pfad auf U:, wird
im Fall <drivecode>==0 der freie Platz von Laufwerk A: berechnet.
<d> soll normalerweise folgende Daten liefern:

     die Anzahl freier Cluster
     die Gesamtzahl von Clustern
     die Gre eines Sektors in Bytes
     die Anzahl der Sektoren pro Cluster


LONG Dlock( WORD mode, WORD drv )
---------------------------------

Sperrt ein BIOS-Laufwerk. Der Zugriff auf dieses Laufwerk ber GEMDOS wird
vollstndig verhindert, der BIOS- Aufruf Rwabs() ist nur fr den sperrenden
Proze erlaubt. Dlock() wird z.B. beim Formatieren oder Kopieren ganzer
Disketten verwendet. Nach der Freigabe des Laufwerks sind alle Caches
ungltig gemacht, als wenn ein Diskwechsel stattgefunden htte. <mode> hat
folgende Bedeutung:

     (mode & 1) == 1:    Laufwerk sperren. Existieren geffnete Dateien auf
                         dem Laufwerk, wird eine Fehlermeldung EACCDN
                         geliefert.
                         Ist das Laufwerk von einem anderen Proze ebenfalls
                         per Dlock() gesperrt, wird ELOCKED geliefert. Es sei
                         denn (mode & 2) == 1. In diesem Fall wir die
                         Proze-ID des sperrenden Prozesses geliefert.
     (mode & 1) == 0:    Laufwerk wieder freigeben. Ist das Laufwerk nicht
                         oder von einem anderen Proze gesperrt, wird eine
                         Fehlermeldung ENSLOCK geliefert. Beim Terminieren des
                         sperrenden Prozesses wird das Laufwerk automatisch
                         wieder freigegeben.
     (mode & 2) == 1:    Liefere ggf. Proze-ID, wenn Laufwerk gesperrt.
     (mode & 2) == 0:    Liefere ELOCKED.

Eigentlich existieren also nur die Modi 0 (freigeben), 1 (sperren,
liefere ggf. ELOCKED), 3 (sperren, liefere ggf. sperrende Proze-ID).
Ein Sperren und anschlieendes Freigeben eines Laufwerks simuliert quasi
einen Diskwechsel (es sei denn, das Laufwerk ist in Benutzung).

Vor Sperren des Laufwerks werden, falls ein Dateisystem fr das Laufwerk
existiert, die Caches ber den Vektor xfs_sync zurckgeschrieben. Dann stellt
der Kernel ber xfs_drv_close eine Anfrage, ob das Laufwerk gesperrt werden
kann. Wenn ja, gibt das XFS seine Strukten frei und signalisiert dann dem
Kernel, da auch er seine Strukturen fr das Laufwerk freigeben und die
Sperrung durchfhren kann.


LONG Dreadlabel( char *dirpath, char *name, UWORD buflen )
----------------------------------------------------------

Ist seit MiNT 1.12 vorhanden und ist in MagiC 3 implementiert.


LONG Dwritelabel( char *dirpath, char *name)
--------------------------------------------

Ist seit MiNT 1.12 vorhanden und ist in MagiC 3 implementiert.



VI Verzeichnisverwaltung
========================


LONG Dcreate(char *path)
------------------------

Erstellt ein Unterverzeichnis. Der Aufruf wird vom Kernel 
weitergegeben als xfs_dcreate mit Erstellmodus (-> Fxattr()) 
%0100000111101101 (d.h. "directory file" mit Zugriffsberechtigung 
RWXRwXRwX). Mit Fchmod() kann der Modus nachtrglich gendert werden.
Das XFS sollte keine gleichnamigen Dateien oder Unterverzeichnisse 
lschen, sondern in diesem Fall einen Fehlercode EACCDN liefern. 
Ungltige Dateinamen wie "." oder ".." mssen auch vom XFS abgefangen 
werden.


LONG Ddelete(char *path)
------------------------

Lscht ein Unterverzeichnis.
Ab MagiC 4.01 knnen damit auch Symlinks gelscht werden. In lteren
MagiC-Versioen wurde immer das Verzeichnis gelscht, auf das der Symlink
zeigte, was Probleme mit lteren Programmen hervorrufen konnte.
Der Kernel von MagiC 4.01 macht die Standardpfade, die eventuell auf dem
gelschten Verzeichnis lagen, automatisch ungltig, weitere Zugriffe auf
diese Standardpfade fhren zu EPTHNF, bis durch Dsetpath() ein neuer Pfad
gesetzt wird.
Alte MagiC-Versionen testeten vorher, ob das Verzeichnis ein Standardpfad
ist, und gaben ggf. EACCDN zurck.


LONG Frename(char *oldpath, char *newpath)
------------------------------------------

Eine Datei (oder Verzeichnis oder Link oder Gert usw.) wird auf 
demselben Laufwerk umbenannt oder in der Verzeichnisstruktur 
verschoben. Da dies hnlich wie das Erstellen eines Hardlinks ist, 
wird beim Aufruf des XFS dieselbe Funktion wie bei Flink benutzt. Es 
ist Sache des XFS, zu entscheiden, ob Verzeichnisse umbenannt oder 
verschoben werden drfen.
Das integrierte DOS-XFS erlaubt erst seit MagiC 5 ein Verschieben von 
Verzeichnissen. Unter TOS/MiNT usw. ist dies nicht mglich.


LONG Dsetpath( const char *path )
---------------------------------

Im Gegensatz zu UNIX verwaltet GEMDOS fr jedes Laufwerk einen 
eigenen aktuellen Pfad. Dsetpath() setzt den aktuellen Pfad fr 
dasjenige Laufwerk, auf dem sich der durch <path> angegebene Pfad 
befindet. Dies mu nicht zwangslufig derjenige sein, dessen 
Laufwerkbuchstabe im Pfad angegeben ist, weil der Pfad ber einen 
Symlink auch auf ein anderes Laufwerk zeigen kann. Bei einem "cross 
drive link" wird daher, auer fr Laufwerk U:, das aktuelle Laufwerk 
umgesetzt, wenn sich der Aufruf von Dsetpath() darauf bezog. Ein 
Beispiel:

- Sei f:\cbin ein Symlink auf c:\bin. Das aktuelle Laufwerk sei c:. Der
  Aufruf von Dsetpath("f:\cbin") fhrt dazu, da der aktuelle Pfad von c: in
  "\bin\" gendert wird. Ist dagegen das aktuelle Laufwerk f:, wird
  zustzlich noch das aktuelle Laufwerk auf c: gewechselt.
- Ist dagegen das aktuelle Laufwerk u:, ist diese Aktion nicht notwendig,
  weil der aktuelle Pfad einfach von "\f\" in "\c\bin\" gendert werden kann.


LONG Dgetpath( char *pathbuf, int drivecode )
---------------------------------------------

Wird unter MagiC 3 als Dgetcwd( pathbuf, drivecode, 128 ) ausgefhrt.


LONG Dpathconf( char *path, int mode )
--------------------------------------

Liefert Informationen ber Beschrnkungen des Dateisystems, das zum
angegebenen <path> gehrt. Die Funktion sollte in MagiC ggf. nach Dopendir()
aufgerufen werden, da Dpathconf() keine Diskwechsel erkennt (wenn der Pfad
noch im Cache ist, wird kein Diskzugriff durchgefhrt, und daher kein
Diskwechsel erkannt).
Wenn einer der Werte unbeschrnkt ist, wird 0x7fffffffL zurckgegeben.
<mode> kann folgende Werte annehmen:

 mode =
	DP_MAXREQ (-1):
		Maximal zulssiger Wert fr <mode> (liefert momentan "8")

	DP_IOPEN (0):
		Maximale Anzahl gleichzeitig geffneter Dateien

	DP_MAXLINKS (1):
		Maximale Anzahl Links pro Datei

	DP_PATHMAX (2):
		Maximale Lnge eines kompletten Pfadnamens

	DP_NAMEMAX (3):
		Maximale Lnge eines Dateinamens

	DP_ATOMIC (4):
		Anzahl Bytes, die in einem Rutsch geschrieben werden knnen.

	DP_TRUNC (5):
		Informationen ber Dateinamen-Verkrzung (auf 8+3) =>

		DP_NOTRUNC (0):	Lange Dateinamen fhren zu ERANGE.
		DP_AUTOTRUNC (1):	Lange Dateinamen werden automatisch gekrzt.
		DP_DOSTRUNC (2):	Regeln wie bei DOS (8+3).

	DP_CASE (6):
		Informationen ber Gro-/Kleinschrift in Dateinamen =>

		DP_CASESENS (0):	case-sensitiv
		DP_CASECONV (1):	nicht case-sensitiv, immer in Groschrift
		DP_CASEINSENS (2):	nicht case-sensitiv, aber unbeeinflut

	DP_MODEATTR (7):
		Information ber untersttzte Attribute und Modi =>

		DP_ATTRBITS	0x000000ffL	/* gltige TOS attribute */
		DP_MODEBITS	0x000fff00L	/* gltige Unix attribute */
		DP_FILETYPS	0xfff00000L	/* mask for valid file types */
		DP_FT_DIR		0x00100000L	/* Verzeichnisse */
		DP_FT_CHR		0x00200000L	/* "character special files" */
		DP_FT_BLK		0x00400000L	/* "block special files" */
		DP_FT_REG		0x00800000L	/* "regular files" */
		DP_FT_LNK		0x01000000L	/* "symbolic links" */
		DP_FT_SOCK	0x02000000L	/* "sockets" */
		DP_FT_FIFO	0x04000000L	/* "pipes" */
		DP_FT_MEM		0x08000000L	/* "shared memory or proc files" */

	DP_XATTRFIELDS (8):
		Information ber gltige Felder in XATTR =>

		DP_INDEX		0x0001
		DP_DEV		0x0002
		DP_RDEV		0x0004
		DP_NLINK		0x0008
		DP_UID		0x0010
		DP_GID		0x0020
		DP_BLKSIZE	0x0040
		DP_SIZE		0x0080
		DP_NBLOCKS	0x0100
		DP_ATIME		0x0200
		DP_CTIME		0x0400
		DP_MTIME		0x0800


LONG Dopendir( char *name, WORD flag )
--------------------------------------

ffnet ein Verzeichnis zum sequentiellen Lesen (Durchsuchen) mit 
D(x)readdir(). Bei allen neuen Programmen sollte diese Funktion 
anstatt Fsfirst/-next() verwendet werden, da sie Aliase korrekt 
auswertet, lange Dateinamen zult usw. In <flag> sind folgende Modi 
mglich:

	#define DOPEN_COMPAT     1
	#define DOPEN_NORMAL     0

Bei DOPEN_NORMAL liefern die folgenden D(x)readdir()-Aufrufe lange 
Dateinamen, auerdem davor 4 Bytes fr den Datei-Index (entspricht 
dem UNIX-Inode). Diese Einstellung ist fr moderne Programme sinnvoll.

MiNT bildet die alten Funktionen Fsfirst/next auf Dopendir()/ 
Dreaddir() ab. Nur aus diesem Grund gibt es bei Dopendir() noch den 
Kompatibilittsmodus DOPEN_COMPAT. In diesem Modus liefert 
D(x)readdir() keinen Index und nur Namen im Format 8+3.

Dopendir() liefert einen (negativen) Fehlercode oder ein Verzeichnis-
Handle. Dieses Handle wird an folgende D(x)readdir()-Aufrufe 
bergeben. Auf keinen Fall darf man vergessen, ein Verzeichnis nach 
Ende des Durchsuchens wieder mit Dclosedir() zu schlieen.

MagiC schtzt alle Dateien, die per Dopendir() geffnet sind, vor 
Schreibzugriffen. Die Zahl der gleichzeitig zu ffnenden 
Verzeichnisse ist durch den internen DOS-Speicher begrenzt. Bei 
zuvielen Verzeichnissen ist ggf. ADDMEM zu benutzen.


LONG Dreaddir( WORD len, LONG dirhandle, char *buf )
----------------------------------------------------

Liest den nchsten Verzeichniseintrag eines durch Dopendir() 
geffneten Verzeichnisses, dessen Handle in <dirhandle> bergeben 
wird. Je nach <flag> bei Dopendir() werden dabei 4 Bytes Index, 
gefolgt vom Namen, oder aber nur ein Name im Format 8+3 geliefert.

In <len> gibt man die Lnge des Puffers an, auf den <buf> zeigt. 
Bercksichtigt man 4 Bytes fr den Index und 1 Byte fr das 
Zeichenketten-Ende-Zeichen, so kann der lngste Dateiname (len-5) 
Zeichen lang sein.

Der "index" soll eigentlich dem "Inode" in einem UNIX hnlichen 
Dateisystem ensprechen (auch HFS arbeitet so). Zumindest mu 
"index" eindeutig sein, d.h. keine zwei Dateien oder Verzeichnisse 
drfen denselben Index haben. Nheres -> Fxattr().


LONG Dxreaddir( WORD ln, LONG dirh, char *buf, XATTR *xattr, LONG *xr)
----------------------------------------------------------------------

Diese Funktion arbeitet zunchst wie Dreaddir(), ruft jedoch bei 
erfolgreich gelesenem Verzeichnis-Eintrag intern noch Fxattr() 
mit Modus 1 und Rckgabestruktur <xattr> auf. D.h. symbolische Links 
werden nicht automatisch dereferenziert. Das ist auch sinnvoll, denn 
so werden symbolische Links erkannt und knnen dann manuell mit 
Freadlink() und Fxattr() mit Modus 0 dereferenziert werden. Der 
Rckgabewert von Fxattr() wird in <xr> geliefert.

Aus Geschwindigkeitsgrnden wird im MagiC-XFS dieser Aufruf nicht 
durch viele einzelne XFS-Aufrufe abgebildet, sondern durch einen 
einzigen. Die XFS-Funktion xfs_readdir bernimmt sowohl Dreaddir als 
auch Dxreaddir, im ersten Fall ist ein Zeiger NULL.

Diese Funktion wurde auf meinen Wunsch zur Einfhrung von MagiC 3 
definiert und ab MiNT 1.12 eingebaut, da mir die Einzelaufrufe 
Dreaddir/Fxattr, die fr jeden einzelnen Verzeichniseintrag immer 
wieder durchzufhren sind, zu umstndlich und langsam waren (jedesmal 
wieder die komplette Pfad-Auswertung usw.). Interessant ist auch, da 
keine fnf Jahre spter die Firma Sun zu derselben Schlufolgerung 
kam und im NFS-Protokoll der Version 3 einen hnlichen Aufruf vorsah.


LONG Drewinddir( LONG handle )
------------------------------

Setzt den Lesezeiger eines geffneten Verzeichnisses wieder auf den 
Verzeichnisanfang.


LONG Dclosedir ( LONG dirhandle )
---------------------------------

Schliet ein durch Dopendir() geffnetes Verzeichnis. Weitere 
Zugriffe auf das <dirhandle> sind verboten.


LONG Dgetcwd( char *pathbuf, int drivecode, int buflen )
--------------------------------------------------------

Gibt in <pathbuf> den aktuellen Pfad (ohne Laufwerkbuchstabe) fr das
angegebene Laufwerk <drivecode> zurck. Ist <drivecode> == 0, wird das
aktuelle Laufwerk verwendet, 1 entspricht Laufwerk A:, 2 Laufwerk B: usw.
<buflen> ist die Lnge des Pfadpuffers, ist der aktuelle Pfad zu lang, wird
ERANGE zurckgegeben.



VII Dateinamen-Funktionen
=========================


void Fsetdta ( DTA *buf )
-------------------------

Setzt den fr Fsfirst/-next() verwendeten Puffer ("DTA"). Jeder 
Proze hat genau einen aktiven DTA-Puffer, der bei Start des 
Prozesses auf Offset 128 der Basepage (d.h. auf die Kommandozeile) 
gelegt wird.
Es mu unbedingt sichergestellt werden, da Fsfirst-/next() nur dann 
aufgerufen werden, wenn die DTA auf einen gltigen Speicherbereich 
zeigt. Ansonsten kommt es zu Abstrzen.
In neueren Programmen sollten die Funktionen Fsetdta(), Fgetdta(), 
Fsfirst() und Fsnext() nicht mehr verwendet werden, da sie z.B. keine 
langen Dateinamen verarbeiten und das gerade durchsuchte Verzeichnis 
nicht fr andere Prozesse schreibschtzen knnen.


DTA *Fgetdta ( void )
---------------------

Ermittelt die aktuelle DTA des Prozesses.


LONG Fcreate(char *path, int attr)
----------------------------------

Diese Funktion dereferenziert symbolische Links, d.h. wenn die Datei bereits
als symbolischer Link existiert, wird die davon referenzierte Datei auf die
Lnge Null gebracht.

Diese Funktion hat 2 Unterfunktionen:

1.   Ist Bit 3 von <mode> gesetzt, wird ein Diskname erstellt. Dabei wird die
     XFS-Funktion xfs_wlabel aufgerufen. Wird diese Funktion ohne Fehler
     ausgefhrt, wird als Rckgabewert 0x0000fffc zurckgegeben. Dies
     entspricht einem Handle fr die Datei NUL: bzw. u:\dev\null. Das
     Anwenderprogramm kann dieses Handle schlieen oder auch nicht.

     Achtung: Diese Unterfunktion wurde in MagiC 3 und MiNT 1.12 durch die
              leistungsfhigere Funktion Dwritelabel() ersetzt und ist nur
              noch aus Kompatibilittsgrnden vorhanden.

2.   Eine Datei mit DOS-Attribut <attr> wird erstellt. Dabei sind die Bits

          FA_RDONLY      (Bit 0)
          FA_HIDDEN      (Bit 1)
          FA_SYSTEM      (Bit 2)
          FA_ARCHIVE     (Bit 5)

     zulssig. Die Bits 6 und 7 werden aus Kompatibilittsgrnden unter
     MagiC 3 ignoriert. Ein gesetztes Bit 4 (FA_SUBDIR) fhrt zu Fehlercode
     EBADRQ.
     Wird eine Datei mit FA_RDONLY erstellt, ist sie zwar geffnet, kann aber
     nicht beschrieben werden.

	Ein Sonderfall ist das Erstellen einer Datei in U:\PIPE, hier werden
	Pipes erstellt. Das Attribut <attr> hat dann in MiNT folgende Bedeutung,
	siehe PIPES.TXT.

     Anmerkung: Fcreate() sollte eigentlich in MiNT und MagiC 3 durch
                Fopen() im Modus O_CREAT+O_TRUNC ersetzt werden. Bei dieser
                Funktion wird jedoch immer das Attributbyte 0 angenommen,
                FA_RDONLY mu daher ggf. durch anschlieenden Aufruf von
                Fchmod() gesetzt werden.
                Die Attribute existieren nur auf DOS-Dateisystemen und werden
                von anderen Dateisystemen ignoriert oder simuliert. Auf dem
                Macintosh-Dateisystem wird nur FA_RDONLY bercksichtigt.
                FA_ARCHIVE ist berflssig, wenn man eine korrekt gehende
                Systemuhr besitzt und das Datum des letzten Backup bekannt
                ist.


LONG Fopen(char *path, WORD omode)
----------------------------------

Diese Funktion dereferenziert symbolische Links, d.h. wenn die Datei bereits
als symbolischer Link existiert, wird die davon referenzierte Datei geffnet
bzw., wenn O_TRUNC angegeben wurde, auf die Lnge Null gebracht.

<omode> der Dateiffnungsmodus. Unter TOS sind hier nur die Werte 0 bis 2
erlaubt, unter MiNT und MagiC existieren folgende Modi:

	O_RDONLY	(0x00)	Will nur lesen
	O_WRONLY	(0x01)	Will nur schreiben
	O_RDWR	(0x02)	Will lesen und schreiben

Wenn keine weiteren "sharing mode" Flags benutzt werden, entspricht das dem
Kompatibilitts-Modus, d.h. O_COMPAT (0x00). Dabei erlaubt MagiC das
mehrfache ffnen zum Lesen, jedoch nur das einfache ffnen zum Schreiben.
MiNT unterscheidet dagegen zwischen eigenen und fremden Dateien; ein Proze
darf hier eine Datei mehrmals ffnen, die fr andere Prozesse jedoch dann
gesperrt ist. Die "sharing modes" sind:

	O_COMPAT	(0x00)	TOS-Kompatibilitt
	O_DENYRW	(0x10)	vor Lesen und Schreiben schtzen
	O_DENYW	(0x20)	vor Schreiben schtzen
	O_DENYR	(0x30)	vor Lesen schtzen
	O_DENYNONE(0x40)	nicht schtzen

MiNT "kennt" noch (oder auch nicht):

	O_NOINHERIT(0x80)	/* this is currently ignored by MiNT */
	O_NDELAY	(0x100)	/* don't block for i/o on this file */

MagiC und MiNT untersttzen noch:

	O_CREAT	(0x200)	Datei erstellen, wenn sie nicht existiert
	O_TRUNC	(0x400)	Existierende Datei auf Null-Lnge setzen
	O_EXCL	(0x800)	Existierende Datei nicht ffnen


LONG Fdelete( char *path )
--------------------------

Die Datei wird gelscht. Dabei werden keine symbolischen Links dereferenziert,
d.h. es wird der Link gelscht, nicht die Datei oder der Ordner, auf die der
Link zeigt.
Falls das jeweilige Dateisystem diese Attribute untersttzt, lscht Fdelete()
auch Dateien mit Attribut HIDDEN oder SYSTEM.


LONG Fattrib( char *path, int setflag, int new_attrib )
-------------------------------------------------------

Hiermit knnen die DOS-Zugriffsberechtigungen auf Dateien ermittelt und
verndert werden. Fr neuere Anwendungen sind Fxattr() zum Ermitteln der
Attribute und Fchmod() zum Verndern der Berechtigungen leistungsfhiger,
werden jedoch nicht von allen Dateisystemen untersttzt. So untersttzt das
DOS-XFS zur Zeit nur Fxattr(), nicht Fchmod().
Ist <setflag> == 0, wird das Attribut der Datei oder des Ordners <path>
ermittelt. Dabei werden keine Disknamen (volume labels) gefunden.
Ist <setflag> == 1, wird das Attribut der Datei <path> gem dem neuen
Attribut <new_attrib> modifiziert. Jeder Versuch, damit einen Ordner zu
modifizieren, fhrt zu EACCDN.
Modifiziert werden drfen die Attribute FA_READONLY (0x01), FA_HIDDEN (0x02),
FA_SYSTEM (0x04) und FA_ARCHIVE (0x20). Enthlt <new_attrib> weitere Flags,
fhrt dies zum Fehlercode EACCDN.
Achtung:  ltere Betriebssysteme finden hier keine Ordner, d.h. Zugriff auf
          einen Ordner fhrt immer zu EFILNF.


LONG Fsfirst( char *path, int sattr )
-------------------------------------

Diese Funktion erfllt zwei unterschiedliche Aufgaben:

1.   Ist Bit 3 von <sattr> gesetzt, ruft der MagiX-Kernel die      
	XFS-Funktion xfs_rlabel auf. Das aufrufende Anwenderprogramm 
	kann damit leider unter MagiC 3 nicht mehr Datum und Uhrzeit des 
	Disknamens ermitteln. Der Kernel setzt alle Felder auf 0. Ein 
	Fsnext() darf dann nicht ausgefhrt werden.

     Achtung: Die Funktion wurde in MagiC 3 und MiNT 1.12 durch Dreadlabel()
              ersetzt, mit der auf lngere Dateinamen gelesen werden knnen.

2.   Sonst wird wie in TOS nach Dateien gesucht. Ist eine Datei ein Symlink,
     ruft der DOS-Kernel die Funktion Fxattr() auf, um den Symlink zu
     verfolgen. Die von Fxattr() gelieferten Werte werden dann in die DTA
     kopiert.
     Achtung: MagiC 3 ist nicht in der Lage, relative Symlinks whrend des
              Fsfirst/Fsnext - Mechanismus immer korrekt auszuwerten. Es
              bieten sich 3 Auswege an:

              a) Am besten: Dxreaddir() verwenden.
              b) Nur absolute Symlinks verwenden
              c) Das Suchverzeichnis jeweils zum aktuellen machen.

              MiNT behandelt diesen Fall korrekt, jedoch auf Kosten eines
              gewaltigen Aufwands. Das Konzept Fsfirst/next ist grundstzlich
              veraltet, ineffektiv und unsicher und sollte sowohl in MiNT als
              auch in MagiC 3 vermieden werden.


LONG Fsnext( void )
-------------------

Ermittelt anhand der vom System gespeicherten Daten in der aktuellen 
DTA die nchste zum Suchmuster und Suchattribut passende Datei und 
legt ihre Daten in der DTA ab. Existiert im durchsuchten Verzeichnis 
keine weitere Datei, wird ENMFIL zurckgegeben.
In Bezug auf die Auswertung der Symlinks -> Fsfirst().


LONG Frename( const char *oldpath, const char *newpath )
--------------------------------------------------------

Bennennt eine Datei um und/oder verschiebt sie. In MagiC knnen auch 
Ordner verschoben werden.


LONG Fxattr( WORD mode, const char *path, XATTR *xa )
-----------------------------------------------------

Ermittelt eine Reihe von Daten fr eine Datei oder einen Ordner, dessen Name
bekannt ist. Das Pendant Fcntl mit Modus FSTAT arbeitet quivalent mit einer
geffneten Datei und erwartet statt des Pfads ein DOS-Dateihandle.
Mit <mode> == 0 werden Symlinks verfolgt, mit <mode> == 1 wird die XATTR-
Struktur des Symlinks selbst ermittelt.
Fxattr() kann nicht auf einen Volume-Namen angewendet werden (=>EFILNF).
Die XATTR-Struktur im einzelnen:

typedef struct xattr {
     unsigned short mode;

		Enthlt den Dateityp und die (UNIX-) Zugriffsrechte. Bei DOS-
		und Mac- Partitionen werden die UNIX-Zugriffsrechte 
		halbwegs sinnvoll simuliert: Dateien haben RWXRWXRWX bzw., 
		wenn sie schreibgeschtzt sind, RwXRwXRwX.
		Nheres steht in der MiNT-Doku.

     long index;

		Enthlt ein Langwort zur eindeutigen Identifizierung einer Datei
		bzw. eines Ordners. Der Index mu innerhalb eines Dateisystems
		eindeutig sein, zusammen mit dem folgenden Feld (dev) ist damit
		eine Datei oder ein Ordner systemglobal vollstndig festgelegt.

		Unter UNIX-hnlichen Dateisystemen ist <index> die Nummer des
		Inode.

		Auf Mac-Partitionen wird die "hard file ID" bzw. die "hard 
		dir ID" verwendet, die vom MacOS zur Verfgung gestellt 
		wird. Das MacOS verwendet als Standard-Deskriptoren aber 
		das "FSSpec". Fr Verzeichnisse, d.h. fr "Directory IDs", 
		gibt es Funktionen des MacOS, um einen FSSpec zu berechnen. 
		Leider lassen sich die "hard file IDs" fr normale Dateien 
		(d.h. nicht Unterverzeichnisse) nicht weiter verwenden, da 
		sie von keiner Funktion des MacOS verarbeitet werden.

		Auf DOS-Dateisystemen wird im Fall eines Ordners der 
		Startcluster im Motorola-Format verwendet, ansonsten im 
		Hiword der Startcluster des Verzeichnisses und im Loword 
		die Position des zugehrigen Verzeichniseintrags, dividiert 
		durch 32.
		Der Startcluster lt sich leider bei normalen Dateien 
		nicht verwenden, weil leere Dateien den Startcluster 0 
		haben und so alle leeren Dateien einen identischen Index 
		htten. Weiterhin htte sich bei Beschreiben einer leeren 
		Datei der Startcluster und damit der Index gendert.
		Das Verfahren ist hnlich wie das, das Linux und Solaris verwenden.
 		Nachteil ist, da Dateien beim Verschieben ihren Index ndern.

     unsigned short dev;

		Legt das Dateisystem fest. Auf dem Atari sind 0..25 die 
		BIOS-Laufwerke A: bis Z:, Laufwerk U: oder andere 
		Dateisysteme verwenden hhere Nummern.
		Auf dem Mac wird die "volume ID" eingesetzt, die vom MacOS 
		vergeben wird.

     unsigned short reserved1;

		hier ist Platz fr Eric Smiths Lebenslauf.

     unsigned short nlink;

		Anzahl der "hard links", die auf diese Datei verweisen. Dies ist
		nur bei UNIX-Dateisystemen interessant, bei DOS-Dateisystemen und
		Mac-Partitionen steht hier immer eine "1".

     unsigned short uid;

		Die "user ID" der Datei, d.h. der Eigner. Ist nur fr Multiuser-
		Systeme interessant, d.h. fr UNIX-Partitionen. Mac- und DOS-
		Partitionen haben hier immer eine "0".

     unsigned short gid;

		Die "group ID" der Datei. Ebenfalls nur fr Multiuser-
		Systeme interessant, d.h. fr UNIX-Partitionen. Mac- und DOS-
		Partitionen haben hier immer eine "0".

     long size;

		Die (logische) Dateilnge, d.h. die Anzahl der Bytes, die man
		mit Fread() lesen kann.

		Auf DOS-Partitionen wird fr Ordner als Lnge 0 geliefert. Die
		tatschliche Lnge kann leider aufgrund der Einschrnkungen von
		MSDOS nicht ermittelt werden. Die Lnge des Wurzelverzeichnisses
		kann allerdings ermittelt werden.

		Auf Mac-Partitionen haben Ordner immer die Lnge 0, die 
		tatschliche Lnge lt sich (zumindest unter System 7 und 	
		8) nicht ermitteln.

     long blksize;

		Die Lnge eines physikalischen Blocks der Datei. Auf DOS-
		Partitionen die Clustergre.

	long nblocks;

		Die Anzahl der durch die Datei belegten Blcke.
		(blksize * nblocks) ist damit die physikalische Dateilnge.
		Es gelten dieselben Einschrnkungen fr Ordner wie bei <size>.

     short     mtime, mdate;

		Modifikationsdatum der Datei.

     short     atime, adate;

		Datum des letzten Zugriffs. Ist auf DOS- und Mac- Partitionen
		mit dem Modifikationsdatum identisch.

     short     ctime, cdate;

		Erstelldatum der Datei. Ist auf DOS- Partitionen mit dem
		Modifikationsdatum identisch.

     short     attr;

		Das von Fattrib() gelieferte Byte, d.h. DOS-Zugriffsrechte
		(ReadOnly oder ReadWrite) und DOS-Flags (Hidden,System,Archive,
		Subdir)

     short     reserved2;
     long reserved3[2];

		hier ist Platz fr Eric Smiths Lieblingsgedicht.

} XATTR;


LONG Flink( char *oldname, char *newname )
------------------------------------------

Erstellt auf einem Dateisystem, das ("echte") Links (auch 
"Hardlinks") untersttzt, zu der Datei <oldname> einen neuen 
Verzeichniseintrag <newname> auf demselben Laufwerk. Die Funktion 
arbeitet also hnlich wie Frename(), aber der alte Name wird nicht 
gelscht, sondern beibehalten.

Diese Funktion wird nur von wenigen (UNIX-) Dateisystemen untersttzt.


LONG Fsymlink( char *oldname, char *newname )
---------------------------------------------

Die Syntax ist wie bei Flink(), jedoch wird ein "symbolischer Link" 
(oder "Alias") erstellt. <newname> kann auf einem beliebigen 
Dateisystem liegen, welches symbolische Links untersttzt (Achtung: 
TOS und natrlich auch MiNT untersttzen keine symbolischen Links 
auf FAT-Laufwerken).

Es wird eine neue, spezielle Datei angelegt, die einen Verweis auf 
<oldname> enthlt. Dabei braucht <oldname> nicht einmal zu 
existieren, denn es wird lediglich der Pfad als solcher gespeichert.

Im Gegensatz zu den verkorksten Konzepten in MacOS und Windows 95/NT 
wird die Dereferenzierung des symbolischen Links vllig dem System 
berlassen, symbolische Links sind also fr Applikationen transparent.

Der Pfad <oldname> kann relativ zu <newname> sein, z.B. kann mit:

	oldname=C:\gemsys\hp850.sys newname=C:\gemsys\hp870.sys

ein absoluter und mit

	oldname=hp850.sys newname=C:\gemsys\hp870.sys

ein relativer symbolischer Link erzeugt werden (hp870 ist jetzt eine 
Art Zeiger auf die im selben Verzeichnis liegende Datei hp850).

Bei relativen symbolischen Links gibt es einige Einschrnkungen: 
Sie funktionieren in MagiC nicht korrekt bei Fsfirst()/next(), und 
das Mac-XFS fr MagiCMac untersttzt leider berhaupt keine relativen 
symbolischen Links.


LONG Freadlink ( WORD bufsiz, char *buf, char *name )
-----------------------------------------------------

Liest einen symbolischen Link (d.h. ermittelt den tatschlichen 
Pfad, auf den der Link verweist).


LONG Fchown ( char *name, WORD uid, WORD gid )
----------------------------------------------

Eigner (uid) und Gruppe (gid) der Datei <name> ndern. Wird nur von 
UNIX-hnlichen Dateisystemen untersttzt (Minix-XFS).


LONG Fchmod ( char *name, WORD mode )
-------------------------------------

Dateiberechtigungen der Datei <name> ndern. Wird nur von UNIX-
hnlichen Dateisystemen untersttzt (Minix-XFS). Auf FAT-
Dateisystemen ist nur Fattrib() mglich.


LONG Dcntl( WORD function, char *path, void *param )
----------------------------------------------------

Mit dieser Funktion werden blicherweise Spezialfunktionen ausgefhrt, 
die abhngig vom bergebenen Pfad sind. Je nach Dateisystem, das fr 
den bergebenen Pfad zustndig ist, sind unterschiedliche 
Unterfunktionsnummern mglich, die direkt vom Dateisystemtreiber 
ausgefhrt werden.
Weiterhin gibt es eine Reihe von Unterfunktionen, die vom Kernel selbst 
ausgefhrt werden, wobei der Pfad ignoriert wird. Hier unterscheiden 
sich MiNT und MagiC deutlich. Leider gab es bei der Belegung der 
Dcntl-Opcodes einige Kollisionen zwischen MagiC und dem Minix-XFS fr 
MiNT. Daher enthlt MagiC ab der Version 6 neue Codes, die alten 
werden aber noch untersttzt. Die neuen Codes haben ein 0x6d im 
oberen Byte, diese Kennung ist fr MagiC reserviert.
Ungltige <function>-Opcodes liefern EINVFN.

Folgende Unterfunktionsnummern sind definiert:

KER_GETINFO (0x0100)
MX_KER_GETINFO (0x6d00) ab MagiC 6

	Diese Funktion existiert nur unter MagiC. <path> und <param> 
	mssen auf NULL gesetzt werden. Es wird ein Zeiger auf die MagiC- 
	Kernelstruktur zurckgegeben. Sie ist als MX_KERNEL definiert 
	(->MGX_XFS.TXT und MGX_XFS.H) und wird von Dateisystemtreibern 
	oder Gertetreibern verwendet.

KER_DOSLIMITS (0x0101)
MX_KER_DOSLIMITS (0x6d01) ab MagiC 6

	Diese Funktion existiert nur unter MagiC. <path> und <param> 
	mssen auf NULL gesetzt werden. Es werden Informationen ber den 
	installierten FAT-Dateisystemtreiber (d.h. den Treiber fr das 
	bliche TOS- oder MSDOS-Dateisystem) geliefert. Dcntl() liefert 
	einen Zeiger auf einen Zeiger auf die Struktur MX_DOSLIMITS 
	(->MGX_XFS.H). Der Zeiger selbst kann daher auf eine eigene 
	Struktur umgebogen werden, falls ein neuer Treiber installiert 
	wird.
	Seit der Umstellung auf 32-Bit-Sektornummern sind (ab MagiC 4.50)
	maximal 4193216 statt bisher 65536 Sektoren fr eine Partition
	zulssig.	Die Zahl ergibt sich aus maximal 65519 Clustern mit
	maximal je 32768 Bytes und mindestens 512 Bytes pro Sektor.

	Diese Unterfunktion wird normalerweise nur von Festplattentreibern 
	(z.B. HDDRIVER) verwendet.

KER_INTMAVAIL (0x0102)
KER_INTGARBC (0x0103)
KER_SETWBACK (0x0300)

	Diese Funktionen existierten vor der Version 4.01 unter MagiC, aber
	wurden auf Sconfig-Aufrufe umgesetzt, um Konflikte mit Treibern zu
	vermeiden, die Probleme mit unbekannten Dcntl-Codes haben.

KER_DRVSTAT (0x0104)
MX_KER_DRVSTAT (0x6d04) ab MagiC 6

	Diese Funktion existiert nur unter MagiC (ab 9.9.95). <path> 
	wird ignoriert. Vom Kernel werden einfache Informationen ber ein 
	Laufwerk ermittelt.
	Dazu bergibt man in <param> einen Zeiger auf zwei WORDs. Das 
	erste mu eine Null enthalten, in das zweite wird eine 
	Laufwerknummer von 0 (fr A:) bis 25 (fr Z:) geschrieben.
	Dcntl() liefert folgende Rckgabewerte:

		EDRIVE	Laufwerknummer ungltig (nicht 0..25)
		ELOCKED	Laufwerk z.Zt. gesperrt
		<0		anderer Fehler
		0		Laufwerk z.Zt. nicht gemountet (nicht aktiv)
		>0		Laufwerk gemountet (aktiv)

	Ist auf ein Laufwerk noch nicht zugegriffen worden oder ist ein 
	Laufwerk durch Dlock(), Diskwechsel oder Auswurf eines Mediums 
	freigegeben werden, ist es "unmounted", d.h. ist (nicht mehr) 
	aktiv. Beim ersten Zugriff auf das Laufwerk wird es automatisch 
	wieder "gemountet", z.B. beim ffnen eines Laufwerkicons in der 
	Shell.

KER_XFSNAME (0x0105)
MX_KER_XFSNAME (0x6d05) ab MagiC 6

	Diese Funktion existiert nur unter MagiC (ab 15.6.96). <path>
	ist ein Pfad (keine Datei!). Vom Kernel wird der Name des XFS-
	Treibers ermittelt, der fr diesen Pfad zustndig ist.
	Dazu bergibt man in <param> einen Zeiger auf einen Puffer
	mit Platz fr mindestens 9 Bytes (char buf[9]), der Zeiger
	mu auf eine gerade Adresse zeigen.
	Dcntl() liefert einen Fehlercode < 0, wenn das Verzeichnis ungltig
	oder ein anderer Fehler aufgetreten ist, ansonsten wird ein
	Wert > 0 (!) oder = 0 zurckgegeben, und der Name des Treibers ist
	in buf[] kopiert worden. Z.Zt. gibt es an Namen:

		"DOS_XFS "		Altes DOS-XFS
		"VDOS_XFS"		Neues DOS-XFS (mit VFAT-Untersttzung)
		"MMAC_HFS"		MagicMac-HFS

KER_INSTXFS (0x0200)
MX_KER_INSTXFS (0x6d02) ab MagiC 6

	Diese Funktion existiert nur unter MagiC. Durch den Aufruf
		kernel = Dcntl(KER_INSTXFS, NULL, &myxfs);
	wird ein XFS installiert (->MGX_XFS.TXT).

CDROMEJECT (0x4309)

	Diese Funktion existiert unter MagiC und mit Einschrnkung 
	auch in MiNT. Sie dient zum Auswurf eines Mediums. <param> mu 
	NULL sein. Unter MiNT wird sie nur vom CDROM-Treiber verwendet 
	und kann nicht auf andere Wechselmedien (Syquest) angewandt 
	werden. Unter MagiC wird sie komplett vom Kernel untersttzt.

	In <path> bergibt man einen Pfad, dessen zugehriges 
	Speichermedium ausgeworfen werden soll.

	MagiC ermittelt dazu zunchst alle Laufwerke, die auf demselben 
	Medium liegen (dafr werden die Felder d_driver und d_devcode im 
	DMD verwendet, siehe MGX_XFS.TXT und MGX_XFS.H). Wichtig ist dies 
	fr Wechselmedien (z.B. Syquest) mit mehreren Partitionen oder fr 
	Macintosh-Volumes mit mehreren MagiC-Laufwerken.

	Alle diese Laufwerke werden freigegeben ("unmounted"). Gibt es 
	dabei einen Fehler, weil z.B. auf einem der Laufwerke noch 
	geffnete Dateien sind oder weil eines der Laufwerke per Dlock() 
	gesperrt wurde, wird der Auswurf verweigert und EACCDN bzw. 
	ELOCKED zurckgegeben.

	Schlielich wird der Gertetreiber (Eintrag d_driver im DMD) 
	aufgerufen, um das Medium auszuwerfen. Untersttzt wird die 
	Auswurffunktion fr Mac-Volumes (auch Disketten) sowie fr 
	Laufwerke, die mit einem XHDI-Treiber angesprochen werden (z.B. 
	HDDRIVER). Manche Gerte (Festplatten) lassen sich nicht 
	auswerfen, sie werden vom XHDI-Treiber nur ausgeschaltet (geparkt).
	Disketten lassen sich auf dem Atari nicht auswerfen.

DFS_GETINFO (0x1100)
MX_DFS_GETINFO (0x6d40) ab MagiC 6
DFS_INSTDFS (0x1200)
MX_DFS_INSTDFS (0x6d41) ab MagiC 6

	Diese Funktionen existieren nur in MagiC und dienen zur 
	Installation eines DFS (->MGX_DFS.TXT). Sie werden vom internen 
	DOS-XFS verarbeitet.

PROC_CREATE (0xcc00)

	Diese Funktion ist in MagiC bis zur Version 5.20 reserviert. Sie 
	wird ab MagiC 6 nicht mehr verwendet.

DEV_M_INSTALL (0xcd00)
MX_DEV_INSTALL (0x6d20) ab MagiC 6

	Diese Funktion existiert nur in MagiC. Mit
		Dcntl(DEV_M_INSTALL, "u:\\dev\\mydev", &mydriver);
	wird ein Gertetreiber installiert (->MGX_UDFS.TXT, MGX_DFS.TXT, 
	MGX_DFS.H).

FUTIME (0x4603)

	Diese Funktion wird vom jeweiligen XFS ausgefhrt und ist das 
	Pendant zur gleichnamigen Fcntl()- Funktion. Sie wird von MiNT 
	sowie vom DOS-XFS von MagiC untersttzt. Fr Macintosh-Volumes 
	wird sie z.Zt. nicht untersttzt.
	Als <param> wird ein Zeiger auf folgende Struktur bergeben:

		struct mutimbuf
		     {
		     unsigned int actime;          /* Zugriffszeit */
		     unsigned int acdate;
		     unsigned int modtime;         /* letzte nderung */
		     unsigned int moddate;
		     };

	Die Struktur ist in MAGX.H definiert.

VFAT_CNFDFLN (0x5600)

	Diese Funktion existiert nur unter MagiC (ab 2.1.96).
	Zur Konfiguration des VFAT-XFS.
	Als Pfad mu "u:\" bergeben werden. Der Parameter ist ein 
	Bitvektor, der die Laufwerke festlegt, bei denen lange 
	Dateinamen zugelassen werden. Die Einstellung wird erst beim 
	Mounten eines Dateisystems aktiv, daher knnen bereits 
	gemountete Dateisysteme mit diesem Befehl nicht beeinflut 
	werden.
	Exakt bedeutet das: Beim Mounten eines Dateisystems bestimmt das 
	VFAT-XFS aus dem mit VFAT_CNFDFLN (bzw. mit "drives=" im 
	Abschnitt [vfat] der MAGX.INF) festgelegten Bitvektor, ob ein 
	Dateisystem im "alten" DOS-Modus (mit 8+3-Dateinamen) oder im 
	"neuen" Windows95-Modus (mit langen Dateinamen) betrieben wird.
	Der Bitvektor wird beim Booten mit 0L initialisiert, d.h. das 
	Bootlaufwerk wird immer zunchst im 8+3-Modus geffnet. Dann 
	wird die MAGX.INF geladen und der Abschnitt [vfat] ausgewertet. 
	Ggf. wird das Bootlaufwerk anschlieend neu mit langen Namen 
	gemountet.

VFAT_CNFLN (0x5601)

	Diese Funktion existiert nur unter MagiC (ab 2.1.96).
	Zur Konfiguration eines VFAT-Dateisystems.
	Legt fr ein gemountetes Laufwerk fest, ob es lange Dateinamen 
	untersttzt oder nicht. Damit kann man den mit VFAT_CNFDFLN 
	festgelegten Defaultwert berladen. Damit die Umstellung 
	sichtbar wird, sollte eine SH_WDRAW-Nachricht an die Shell 
	geschickt werden.

DEV_NEWTTY (0xde00)
DEV_NEWBIOS (0xde01)
DEV_INSTALL (0xde02)
FS_INSTALL (0xf001)
FS_MOUNT (0xf002)
FS_UNMOUNT (0xf003)
FS_UNINSTALL (0xf004)

	Diese Funktionen werden nur von MiNT untersttzt und dienen zum 
	Installieren/Deinstallieren von Dateisystemen und -treibern. Wegen 
	der unterschiedlichen Treiberstrukturen verwendet MagiC andere 
	Funktionen (s.o.)



VIII Dateihandle-Funktionen
===========================


LONG Fclose( WORD handle )
--------------------------

Schliet eine Datei. Das <handle> wurde ber Fopen() bzw. Fcreate() 
oder Fdup() ermittelt, oder es handelt sich um ein Standard-Handle 
(0..5) oder ein Gerte-Handle (-1,-2,-3,-4). -4 ist nur in MagiC 
vorhanden (fr NUL:).
Nach dem Fclose() darf auf das Handle nicht mehr zugegriffen werden, 
da es quasi an das System zurckgegeben wurde. Eine Ausnahme sind die 
(negativen) Gerte-Handles. Bei diesen wird nur der Treiber 
informiert, da ein eventueller Puffer zurckgeschrieben werden 
sollte ("flush buffer").


LONG Fread( WORD handle, LONG count, void *buf )
-----------------------------------------------

Liest <count> Bytes aus der Datei <handle> und schreibt sie an 
Speicheradresse <buf>.
Der Rckgabewert kann negativ sein (Lesefehler, Datei gesperrt,...), 
positiv und kleiner als <count> (Datei-Ende erreicht, es konnten 
nicht alle Bytes gelesen werden) oder ist gleich <count> (alle Bytes 
gelesen).
In alten TOS-Versionen knnen von den Gerten nur maximal 65536 Bytes 
gelesen werden, da TOS die oberen 16 Bit von <count> ignoriert.


LONG Fwrite(WORD handle, LONG count, void *buf)
-----------------------------------------------

Schreibt <count> Bytes ab Adresse <buf> in die Datei <handle>.
Der Rckgabewert kann negativ sein (Schreibfehler, Medium 
schreibgeschtzt, Datei gesperrt,...), positiv und kleiner als 
<count> (Medium ist voll, es konnten nicht alle Bytes gelesen werden) 
oder ist gleich <count> (alle Bytes geschrieben).

In alten TOS-Versionen knnen auf die Gerte nur maximal 65536 Bytes 
geschrieben werden, da TOS die oberen 16 Bit von <count> ignoriert.

KAOS und MagiC untersttzen das Abschneiden von Dateien auf die Lnge 
der aktuellen Dateizeiger-Position ber:

	Fwrite(handle, 0L, (void *) -1);

ab MagiC 3 sollte wegen der Kompatibilitt zu MiNT besser auf Fcntl() 
mit dem Opcode FTRUNCATE zurckgegriffen werden.


LONG Fseek( LONG offset, WORD handle, WORD seekmode )
-----------------------------------------------------

Setzt den Dateizeiger der Datei <handle> auf die Position <offset>, 
und zwar gerechnet ab Dateianfang (seekmode = 0), ab aktueller 
Position des Dateizeigers (seekmode = 1) oder ab Dateiende 
(seekmode = 2). Im letzten Fall sollte <offset> kleiner oder gleich 
Null sein.
Rckgabewert ist bei Erfolg die aktuelle Dateiposition (absolut, d.h. 
ab Dateianfang).
Fseek liefert den Fehler ERANGE, wenn <offset> auerhalb der Datei 
liegt.
Fseek auf Pipes liefert in MagiC und MiNT EACCDN, damit Programme 
z.B. Gerte und Pipes unterscheiden knnen.
Fseek auf Gerte wird ignoriert, Rckgabewert ist immer Null.


LONG Fdup( WORD handle )
------------------------

Dupliziert ein Standard-Handle (0..5). Man erhlt ein neues Handle, 
das auf dieselbe Datei zeigt wie das bergebene Handle.

KAOS und MagiC bis einschlielich Version 2.0 liefern bei Fdup() eine 
negative Kennung, wenn das Standardhandle eine Gertedatei ist. Z.B. 
liefert Fdup(1) meist 0x0000ffff, da -1 das Gertehandle fr CON ist 
(Bildschirm und Tastatur). Neuere MagiC-Versionen liefern aus 
Kompatibilttsgrnden stets ein Handle >= 6.

Ab MagiC 4 kann man auch Gertedateien (-1,-2,-3,-4) duplizieren.


LONG Fforce( WORD stdhdl, WORD nstdhdl )
----------------------------------------

Lenkt die Standard-Datei <stdhdl> (mu zwischen 0..5 liegen) auf die 
Nicht-Standard-Datei <nstdhdl> um (kann auch ein negatives Gerte-
Handle sein). Anschlieend zeigen <stdhdl> und <nstdhdl> auf dieselbe 
Datei.
Wozu das ganze? Der folgende Vorgang rettet die Einstellung fr 
Handle 1 (STDOUT), erstellt eine neue Datei und lenkt STDOUT auf 
diese neue Datei. Per Pexec wird ein Programm mit dem umgelenkten 
STDOUT aufgerufen. Anschlieend wird STDOUT restauriert.

	saveHandle = Fdup(STDOUT)
	newStdout = Fcreate(...)
	Fforce(STDOUT, newStdout)
	Fclose(newStdout)
	Pexec(...)
	Fforce(STDOUT, saveHandle)
	Fclose(saveHandle)

Am MagiC 4 kann Fforce() auch mit Gertedateien (-1,-2,-3) als 
<stdhdl> aufgerufen werden. Dabei wird systemglobal (!) die 
Gertedatei -1,-2,-3 umgelenkt. Die Datei -4 (NUL:) kann nicht 
umgelenkt werden.

TOS hat hier eine ganze Reihe Fehler. Z.B. gert das System 
durcheinander, wenn Fforce() auf eine Standarddatei angewandt wird, 
die bereits auf eine echte Datei zeigt. Das passiert z.B. schnell, 
wenn im obigen Beispiel das aufgerufene Programm wieder ein Fforce 
macht.


LONG Fdatime( WORD buffer[2], WORD handle, WORD setflag)
--------------------------------------------------------

Setzt (setflag = 1) oder liest (setflag = 0) Datum und Uhrzeit der 
geffneten Datei <handle>. buffer[] enthlt Datum und Uhrzeit zum 
Setzen bzw. den gelesenen Wert.

TOS gibt keinen vernnftigen Rckgabewert und ndert in einigen 
TOS-Versionen alle Dateien im selben Verzeichnis, die geffnet sind 
und Lnge Null haben. Weiterhin haben einige TOS-Versionen Probleme, 
wenn mit der Datei mehr gemacht wird als nur Fopen(),Fdatime(), 
Fclose().


LONG Flock(WORD handle, WORD mode, LONG start, LONG len)
--------------------------------------------------------

Setzt (mode = 1) oder hebt auf (mode = 0) eine (Schreib-) Blockierung 
fr die Datei <handle>, beginnend bei Position <start> mit der Lnge 
<len>. Siehe auch Fcntl(F_SETLK).

Die Funktion liefert die speziellen Fehlercodes ELOCKED (Blockierung 
schon vorhanden) bzw. ENSLOCK (Blockierung kann nicht aufgehoben 
werden, da nicht vorhanden).

Wird von MagiC insofern untersttzt, als der Aufruf vom DOS-Kernel 
auf den Fcntl()-Aufruf F_SETLK umgesetzt wird. Dabei wird eine 
Schreib-Blockierung erstellt (G_WRLCK). Bei ungltigem <mode> liefert 
der Kernel bereits EINVFN, ohne den Dateitreiber aufzurufen.

Die MagiC Dateitreiber fr (V)FAT und Mac-HFS untersttzen den 
zugehrigen Fcntl-Code F_SETLK leider noch nicht. Das wre auch nur 
sinnvoll fr Netzwerk-XFS-Systeme (z.B. NFS oder SMB).


LONG Fpipe( WORD handles[2] )
-----------------------------

Erstellt eine unidirektionale Pipe (Attribut 0x01), dazu wird ein 
eindeutiger Name des Typs U:\PIPE\SYS$PIPE.nnn" generiert. Bei Erfolg 
(Rckgabe E_OK) enthlt handles[0] die zum Lesen, handles[1] die zum 
Schreiben geffnete Pipe.
Der Aufruf kann durch Fcreate() und Fopen() nachgebildet werden. Er 
ist praktisch fr Shells zur Umlenkung von STDIN/STDOUT.


LONG Fcntl( WORD handle, LONG arg, WORD cmd )
---------------------------------------------

Fhrt verschiedene Operationen auf einer geffneten Datei durch. Je 
nach Dateityp werden verschiedene Werte fr <cmd> akzeptiert. Einige 
Funktionen sind jedoch allgemein und sollten von jedem Dateityp 
untersttzt werden, dies ist jedoch nicht gewhrleistet. Bei 
ungltigen Kommandos liefert der Dateitreiber EINVFN.
Folgende Opcodes werden von internen Dateitreibern von MagiC untersttzt:

- FSTAT ($4600)
- FIONREAD ($4601)
  <arg> ist vom Typ (LONG *) und enthlt nach dem Aufruf die Anzahl 
  der Bytes, die von der Datei gelesen werden knnen, ohne da das 
  Programm durch das Lesen in den Wartezustand versetzt werden mu. 
  D.h. wenn eine Pipe 1000 Zeichen enthlt, kann man 1000 Zeichen 
  direkt lesen, ohne da man darauf warten mu, da neue Daten in die 
  Pipe geschrieben werden.
  Bei FAT- Dateien wird die tatschliche Lnge minus der aktuellen   
  Dateizeiger-Position geliefert. Ebenso bei "shared memory". 
  Gertedateien (devices) liefern eine 1, wenn ein Zeichen anliegt, 
  hierfr wird Bconstat() verwendet. Bei Gerten, die einen 
  Einlesepuffer haben, sollte die Zahl der im Puffer vorhandenen 
  Zeichen angegeben werden.
  FIONREAD wird von Finstat() verwendet.
- FIONWRITE ($4602)
  <arg> ist vom Typ (LONG *) und enthlt nach dem Aufruf die Anzahl 
  der Bytes, die auf die Datei geschrieben werden knnen, ohne da 
  das Programm durch das Schreiben in den Wartezustand versetzt 
  werden mu. D.h. wenn eine Pipe 1000 Zeichen enthlt, kann man noch 
  1048 Zeichen direkt schreiben, ohne da man darauf warten mu, da 
  wieder Daten von der Pipe gelesen werden.
  Bei FAT- Dateien wird 1 geliefert. Bei Dateien mit fester Lnge, 
  z.B. "shared memory", wird die Lnge minus der Dateizeigerposition 
  geliefert.
  Gertedateien (devices) liefern eine 1, wenn Bcostat() ein "OK" 
  liefert.
  Bei Gerten, die einen Schreibpuffer haben, sollte die Zahl der im 
  Puffer noch freien Zeichen angegeben werden.
  FIONWRITE wird von Foutstat() verwendet.
- FUTIME ($4603)
- FTRUNCATE ($4604)
  <arg> ist vom Typ (LONG *) und zeigt auf die neue Lnge der zu 
  verkrzenden Datei.
  Wird in MagiC 3 z.Zt. nur vom FAT-DFS untersttzt.
- PBASEADDR ($5002)
- SHMGETBLK ($4d00)
  Wird nur bei "shared memory"- Dateien untersttzt, das sind die Dateien,
  die in u:\shm liegen.
- SHMSETBLK ($4d01)
  Wird nur bei "shared memory"- Dateien untersttzt, das sind die 
  Dateien, die in u:\shm liegen. <arg> ist ein Zeiger auf einen per 
  M(x)alloc() reservierten Speicherblock, der das "shared memory" 
  darstellt. Der Block wird derart markiert, da er nicht beim 
  Beenden des Prozesses freigegeben wird. Die Lnge wird ermittelt 
  und sowohl fr die geffnete Datei verwendet wie in das Verzeichnis 
  eingetragen. Ungltige Blockadressen fhren zu Fehlercode EIMBA 
  oder zu einem Bus- oder Adrefehler.
  Die Implementation sollte MiNT entsprechen.
(...)


LONG Finstat( WORD handle)
--------------------------

Liefert fr eine zum Lesen geffnete Datei <handle> die Anzahl der Zeichen,
die mindestens ohne Warten gelesen werden knnen. Kann diese Anzahl nicht
exakt angegeben werden, wird 1L geliefert.

Der Kernel versucht zunchst, den Aufruf auf Fcntl(FIONREAD) zurckzufhren.
Wenn diese Subfunktion von dev_ioctl nicht existiert (d.h. der Dateitreiber
liefert EINVFN), wird dev_stat aufgerufen. In diesem Fall kann nur
die Aussage getroffen werden "Zeichen liegt an" (Rckgabe == 1) bzw. "kein
Zeichen liegt an" (Rckgabe == 0).
FAT-Dateien und Shared Memory liefern die tatschliche Dateilnge minus der
aktuellen Position.
Pipes liefern die Anzahl der vorhandenen Bytes im Block.


LONG Foutstat( WORD handle )
----------------------------

Liefert fr eine zum Schreiben geffnete Datei die Anzahl der Zeichen, die
mindestens ohne Warten geschrieben werden knnen. Kann diese Anzahl nicht
exakt angegeben werden, wird 1L geliefert.

Der Kernel versucht zunchst, den Aufruf auf Fcntl(FIONWRITE)
zurckzufhren. Wenn diese Subfunktion von dev_ioctl nicht existiert (d.h.
der Dateitreiber liefert EINVFN), wird dev_stat aufgerufen. In diesem Fall
kann nur die Aussage getroffen werden "Zeichen liegt an" (Rckgabe == 1)
bzw. "kein Zeichen liegt an" (Rckgabe == 0).
FAT-Dateien liefern 1.
Shared Memory liefert die tatschliche Dateilnge minus der aktuellen
Position.
Pipes liefern die Anzahl der noch freien Bytes im Block.


LONG Fgetchar( WORD	handle, WORD mode )
---------------------------------------

Liest ein einziges Zeichen aus der geffneten Datei <handle>. Rckgabewert
ist ein LONG, dessen obere 24 Bit aber i.a. Null sind (bei einer normalen
Datei). Bei einem Terminal sind auch die oberen Bits belegt (mit Scancode
usw.). Ein spezieller Rckgabewert ist 0xff1a fr EOF (END-OF-FILE).
Nur fr Terminals o.. hat der Modus <mode> folgende Bedeutung:

	CMODE_COOKED (1)	Sonderzeichen Ctrl-C,Ctrl-S,Ctrl-Q werden
					ausgewertet (liefern die entsprechenden Signale
					an den Aufrufer) und gelangen nicht als Tastencodes
					an den Aufrufer.
	CMODE_RAW (0)		keine Auswertung der Sonderzeichen.
	CMODE_ECHO (2)		Gibt die eingegebenen Zeichen sofort auf dem
					Bildschirm aus.

Die Modi werden wie blich ver-oder-t, d.h. CMODE_ECHO+CMODE_COOKED ist
erlaubt.


LONG Fputchar( WORD	handle, ULONG value, WORD mode )
----------------------------------------------------

Schreibt ein einziges Zeichen in die geffnete Datei <handle>. Rckgabewert
ist ein negativer Fehlercode oder die Anzahl der geschriebenen Bytes:

	1L	Ein Byte (die untersten 8 Bit von <value>) wurde in die
		Datei geschrieben.
	4L	Das gesamte Zeichen <value> wurde auf die Terminaldatei
		geschrieben
	0L	Schreibfehler (Disk voll o..)

Nur fr Terminals o.. hat der Modus <mode> folgende Bedeutung:

	CMODE_COOKED (1)	Sonderzeichen Ctrl-C,Ctrl-S,Ctrl-Q werden
					ausgewertet (liefern die entsprechenden Signale
					an den Aufrufer) und werden nicht ans Terminal
					weitergereicht.
	CMODE_RAW (0)		keine Auswertung der Sonderzeichen.


LONG Fselect( WORD timeout, LONG *instat, LONG *outstat, LONG dummy )
---------------------------------------------------------------------

Wartet eine angegebene Zeit (timeout in ms, bzw. Null fr "kein Timeout"),
ob auf den als Bitvektor angegebenen Eingabe (instat) und/oder Ausgabe-
Dateien (outstat) Zeichen verfgbar sind. Dabei heit "Bit n gesetzt", da
auf die Datei mit Handle <n> zu warten ist. Eine leere Menge kann als
Zeiger auf 0L oder als NULL-Zeiger bergeben werden.
Bei der Rckgabe werden aus *instat und *outstat alle Bits gelscht, deren
zugehrige Dateien _KEINE_ Zeichen bereitstellen.
<dummy> ist immer Null.
Rckgabewert ist die Anzahl der gesetzten Bits von <*instat> plus der von
<*outstat> oder ein Fehlercode. Demzufolge erhlt man 0L beim Timeout.


LONG Fmidipipe ( WORD pid, WORD in, WORD out )
----------------------------------------------

Lenkt in MiNT die MIDI-Handles eines Prozesses <pid>, d.h. die Handles
-4 und -5 auf <in> bzw. out um und ist damit quivalent zu den betreffenden
Fforce()-Aufrufen.
Ist in MagiC nicht implementiert.



IX Zeichenorientierte Funktionen
================================


LONG Cconin( void )
-------------------

Ist implementiert als

	Fgetchar( STDIN, CMODE_COOKED+CMODE_ECHO )


LONG Cconout( WORD c )
----------------------

Ist implementiert als

	Fputchar( STDOUT, (ULONG) val, CMODE_COOKED )

Folgende Rckgabewerte sind damit mglich:

	MiNT und MagiC >= 3.00:

		1L	erfolgreiche Ausgabe auf Datei
		4L	erfolgreiche Ausgabe auf Terminal
		0L	Disk voll
		< 0	Fehler

	KAOS und MagiC < 3.00:

		1L	erfolgreiche Ausgabe auf Datei oder Terminal
		0L	Disk voll
		< 0	Fehler

	TOS

		( kein sinnvoller Rckgabewert )


LONG Cauxin( void )
-------------------

Ist implementiert als

	Fgetchar( STDAUX, CMODE_RAW )


LONG Cauxout( WORD c )
----------------------

Ist implementiert als

	Fputchar( STAUX, (ULONG) val, CMODE_RAW )

hier gilt dasselbe wie bei Cconout().


LONG Cprnout( WORD c )
----------------------

Ist implementiert als

	Fputchar( STPRN, (ULONG) val, CMODE_RAW )

hier gilt dasselbe wie bei Cconout().


LONG Crawio( WORD c )
---------------------

Ist implementiert als

	if	(c != 0x00ff)
		return(Fputchar( STDOUT, (ULONG) c, CMODE_RAW ));
	else	{
		if	(Cconis())
			return(Crawcin());
		else	return(0L);
		}


LONG Crawcin( void )
--------------------

Ist implementiert als

	Fgetchar( STDIN, CMODE_RAW )


LONG Cnecin( void )
-------------------

Ist implementiert als

	Fgetchar( STDIN, CMODE_COOKED )


LONG Cconws( char *s )
----------------------

Ist in KAOS, MagiC und MiNT implementiert als

	Fwrite( STDOUT, strlen(s), s )

und ist damit "cooked" (d.h. wertet Ctrl-C usw. aus), falls STDOUT ein
Terminal ist.
TOS 1.4 liefert als Rckgabewert 0L fr "OK" und -1L fr "Fehler".
Unter anderen Betriebssystemen ist die Funktion offenbar void, liefert also
berhaupt keinen brauchbaren Rckgabewert.


LONG Cconrs( char *buf )
------------------------

Liest eine Zeichenkette im "cooked" Modus (d.h. Ctrl-C wird ausgewertet)
mit Echo (d.h. die Eingabe ist auf dem Bildschirm sichtbar) von STDIN.
Die Pufferlnge - 1 wird in buf[0] bergeben, wobei der Puffer ab
buf+2 beginnt.
Die Eingabe wird durch [Return] abgeschlossen und ab buf+2[] abgelegt.
Wenn von der Tastatur gelesen wird, sind in MagiC Editierkommandos wie
Cursortasten, Backspace und Delete mglich. TOS behandelt nur Backspace und
Ctrl-X, TOS-Versionen vor 1.4 versagen bei ASCII-Codes > 127.
Hier die Tastencodes von MagiC:

     Cursor hoch/runter      letzte Eingaben zurckholen
     Cursor links/rechts     Cursor ein Zeichen bewegen
     dto. mit Shift          Cursor an Zeilenanfang/-ende
     Home                    Cursor an Zeilenanfang
     Insert                  Einfgemodus
     Shift-Insert            berschreibmodus
     Shift-Clear             Eingabe lschen
     Tabulator               wechselseitig Zeilenanfang/ende
     Undo                    letzte Eingabe 
     Delete/Backspace        Zeichen unter/vor Cursor lschen
     F1..F10                 Environmentvariablen F1..F10 abrufen

Bei normalen Dateien wird in MagiC bis zum ersten LF gelesen, wobei 
CR berlesen wird. Unter TOS liefert die Funktion bei umgelenkter 
Standard-Eingabe unbekannte Resultate, insbesondere wird teilweise 
die Eingabe auf dem Bildschirm oder auf STDOUT ge-echo-t. In MiNT 
(zumindest Version 1.12) ist die Funktion falsch implementiert.
Die tatschlich gelesene Anzahl Zeichen wird in buf[1] zurckgegeben, 
wobei CR oder/und LF nicht mitzhlen.
Rckgabewert ist E_OK oder ein Fehlercode.


LONG Cconis( void )
-------------------

Fragt Eingabestatus von STDIN ab. Rckgabewerte sind 0 fr "nicht
lesebereit" und -1L fr "lesebereit".

Dabei bedeutet "lesebereit" fr Terminals, da Zeichen im Eingabepuffer
vorliegen. Whrend TOS, KAOS und MagiC < 3.00 die Funktion als "cooked"
bearbeiten, d.h. ggf. Ctrl-C usw. auswerten, bearbeitet MagiC >= 3.00
diese Funktion wegen der Kompatibilitt zu MiNT als "raw".

Fr normale Dateien sind die Betriebssysteme unterschiedlicher Meinung:

- TOS liefert immer -1 fr "OK", die Funktion ist daher unbrauchbar.
- MiNT fragt zwar den Gertetreiber, aber der ist bei FAT-Dateisystemen
  ohnmchtig und liefert dort ebenfalls immer -1.
  Geniales Konzept.
- MagiC liefert nur dann -1, wenn die Datei zum Lesen geffnet ist und
  der Gertetreiber ber fd->dev_stat() sein OK gibt. Der DFS-FAT Treiber
  liefert "OK" nur dann, wenn der Lesezeiger der Datei nicht am Dateiende
  ist.

Die Rckgabe von Fehlercodes ist nicht mglich. Bei Fehlern wird 0 fr
"nicht bereit" geliefert.


LONG Cconos( void )
-------------------

Fragt Ausgabestatus von STDOUT ab. Rckgabewerte sind 0 fr "nicht
lesebereit" und -1L fr "schreibbereit".
Die Rckgabe von Fehlercodes ist nicht mglich. Bei Fehlern wird 0 fr
"nicht bereit" geliefert.


LONG Cprnos( void )
-------------------

Wie Cconos(), aber fr STDPRN.


LONG Cauxis( void )
-------------------

Wie Cconis(), aber fr STDAUX.


LONG Cauxos( void )
-------------------

Wie Cconos(), aber fr STDAUX
