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-File11.5.15.1.15  dfs_sfirst                                           TOS

 Name:        »dfs_sfirst«

 Parameters:

                          a0  =  FD * d 
                          a1  =  DIR *dir 
                          d0  =  long pos 
                          d1  =  DTA *dta 
                       -> d0  =  long errcode 
               If necessary: 
                          a0  =  LINK *l 

 Description: The DOS_XFS has already accessed the file. The DFS only 
              needs to initialize the reserved entries dta_usr1 and 
              dta_usr2 for the next Fsnext, so that this position can 
              be found again.

              File descriptors (FDs) cannot be used in dta_usrm as 
              releasing them during a 'garbage collection' cannot be 
              avoided. Simply blocking the FDs is not possible either 
              as one cannot predict the end of the Fsfirst/Fsnext 
              operation. An already failed search can be marked by 
              deleting dta_sname, for instance.

              pos already points to the next entry, i.e. 32 bytes 
              after dir. For symbolic links the DFS has to react 
              appropriately, pass ELINK in d0 and in a0 a pointer to 
              the link. A link starts with a WORD (16-bit) for the 
              length of the path, followed by the path itself.

              Warning: The length must include the terminating NULL- 
              byte and also be even. The link must lie at an even 
              memory address.

              The buffer for the link may be static or volatile as the 
              kernel immediately copies the data elsewhere, with no 
              possibility of a context change happening inbetween.

 Group:       Make-up of a DFS

 See also:    MagiC's DFS-concept