Topic       : TOS - The Operating System
Author      : 
Version     : tos.hyp (December 19, 2008)
Subject     : Programmieren/Atari
Nodes       : 3010
Index Size  : 93790
HCP-Version : 5
Compiled on : Atari
@charset    : atarist
@lang       : 
@default    : Title
@help       : 
@options    : +g -i -s +x +zz -t4
@width      : 70
View Ref-File5.10.29  Fsfirst                                                   TOS

 Name:         »search first file« - Search for first file entry.

 Opcode:       78

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

 Description:  The GEMDOS routine Fsfirst can obtain information about 
               the first occurrence of a file or subdirectory. The 
               following apply:

                Parameter  Meaning

                filename   Pointer to the filename or subdirectory
                attr       Attributes that should be matched by the 
                           file searched for
                            Bit-0:  Include read-only files
                            Bit-1:  Include hidden files
                            Bit-2:  Include system files
                            Bit-3:  Include volume labels
                            Bit-4:  Include subdirectories
                            Bit-5:  Include files with archive-bit set

               The filename or path may also contain the jokers '*' 
               and '?'. When the function terminates, the directory 
               entry will fill the disk transfer area (DTA), whose 
               location can be obtained or set with Fgetdta and 
               Fsetdta respectively. The required information can then 
               be obtained from the DTA structure.

               The DTA must be initialised with Fsfirst!

               Note: If the program runs in the MiNT-domain, Fsfirst 
               will return lower case filenames. As file-systems exist 
               that are case sensitive, you should avoid making such 
               conversions manually. However, if you absolutely need 
               upper case filenames you should use Pdomain to make 
               your program run in the TOS-domain.

               Notes about MagiC: If bit 3 of attr is set, then the 
               kernel will call the XFS function xfs_rlabel. The 
               calling user program can unfortunately no longer get 
               the date and time of the disk name under MagiC with 
               this. The kernel sets all fields to 0 and the function 
               Fsnext may not be executed. As of MagiC 3, the function 
               Dreadlabel is used instead, which also manages long 
               filenames.

               If bit 3 of attr is not set, a search for files is made 
               as in TOS. If a file is a symbolic link, the DOS kernel 
               calls the function Fxattr to follow the link. The 
               values returned by Fxattr are then copied to the DTA.

               Warning: MagiC is not always able to evaluate correctly 
               relative symbolic links during Fsfirst/Fsnext. There 
               are three ways to overcome this:

                (a)  Best: use Dxreaddir
                (b)  Use only absolute symbolic links
                (c)  Alays make the search directory the current one

               Though MiNT handles this case correctly, it is at a 
               huge cost. The Fsfirst/next concept is basically 
               obsolete, ineffective and unsafe, and should be avoided 
               both in MiNT as well as in MagiC.

 Return value: The function returns the following results:

                E_OK :    No error has occurred
                EFILNF :  File not found
                ENMFIL :  No more files

 Availability: All GEMDOS versions.

 Group:        File functions

 See also:     Binding   Fgetdta   Fsetdta   Fsnext   DTA 
               Recursive search   XFS-concept