Topic       : TOS - das Betriebssystem
Author      : 
Version     : tos.hyp (5. März 2013)
Subject     : Programmieren/Atari
Nodes       : 3001
Index Size  : 93602
HCP-Version : 5
Compiled on : Atari
@charset    : atarist
@lang       : 
@default    : Titel
@help       : 
@options    : +g -i -s +x +zz -t4
@width      : 70
View Ref-File5.9.29  Fsfirst                                                    TOS

 Name:         »search first file« - ersten Dateieintrag suchen.

 Gemdosnummer: 78

 Deklaration:  int32_t Fsfirst ( const int8_t *filename, int16_t attr 
               );

 Beschreibung: Die GEMDOS-Routine Fsfirst erlaubt es, Informationen 
               über Dateien oder Verzeichnisse zu ermitteln. Es gilt:

                Parameter  Bedeutung

                filename   Zeiger auf den Dateinamen
                attr       Attribute, die auf den gesuchten Dateityp 
                           passen sollen.
                            Bit-0: Datei ist schreibgeschützt
                            Bit-1: Datei ist versteckt
                            Bit-2: Systemdatei
                            Bit-3: Diskettenname
                            Bit-4: Verzeichnis
                            Bit-5: Archiv-Bit

               Der Pfadname kann auch die Joker '*' und '?' enthalten. 
               Nach Abschluß der Funktion steht der Verzeichniseintrag 
               unter der Diskettenübertragungsadresse DTA, die mit 
               Fgetdta und Fsetdta ermittelt bzw. festgelegt werden 
               kann. Die Informationen können dann der Struktur DTA 
               entnommen werden.

               Die DTA muss durch Fsfirst() initialisiert werden!

               Hinweis: Falls das Programm in der MiNT-Domain läuft, 
               liefert Fsfirst 'lower case' Filenamen. Da es 
               Filesysteme gibt die case sensitiv arbeiten, sollten 
               Sie diese Umwandlung auf keinen Fall manuell 
               durchführen. Wenn Sie hingegen unbedingt 'upper case' 
               Filenamen benötigen, sollten Sie Ihr Programm per 
               Pdomain in der TOS-Domain laufen lassen.

               Anmerkung zu MagiC: Ist Bit-3 von attr gesetzt, so ruft 
               der Kernel die XFS-Funktion xfs_rlabel auf. Das 
               aufrufende Anwenderprogramm kann damit leider unter 
               MagiC nicht mehr Datum und Uhrzeit des Disknamens 
               ermitteln. Der Kernel setzt alle Felder auf 0, und die 
               Funktion Fsnext darf dann nicht ausgeführt werden. Ab 
               MagiC 3 wird stattdessen die Funktion Dreadlabel 
               benutzt, die auch mit langen Dateinamen zurechtkommt.

               Ist Bit-3 von attr nicht gesetzt, wird wie in TOS nach 
               Dateien gesucht. Ist eine Datei ein symbolischer Link, 
               ruft der DOS-Kernel die Funktion Fxattr auf, um den 
               Link zu verfolgen. Die von Fxattr gelieferten Werte 
               werden dann in die DTA kopiert.

               Achtung: MagiC ist nicht immer in der Lage, relative 
               symbolische Links während eines Fsfirst/Fsnext korrekt 
               auszuwerten. Es bieten sich 3 Auswege an:

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

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

 Ergebnis:     Die Funktion liefert folgende Resultate:

                E_OK :    kein Fehler aufgetreten
                EFILNF :  Datei nicht gefunden
                ENMFIL :  keine weiteren Dateien

 Verfügbar:    Alle GEMDOS Versionen.

 Gruppe:       Dateifunktionen

 Querverweis:  Binding   Fgetdta   Fsetdta   Fsnext   DTA 
               rekursive Suche   XFS-Konzept