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.16.27  xfs_path2DD                                            TOS

 Name:        »xfs_path2DD« - Return a directory descriptor (DD) to a 
              pathname.

 Parameters:

               mode =   0: The name is a file
               =        1: The name is itself a directory
               d0 =     int mode
               a0 =     DD *reldir current directory
               a1 =     char *pathname
               -> d0 =  DD *
               d1 =     char *restpfad
               oder
               -> d0 =  ELINK
               d1 =     Restpath without leading '\'
               a0 =     FD of the path in which the symbolic link 
                        lies; this is important for relative path 
                        specifications in the link
               a1 =     NULL, the path represents the parent of the 
                        root directory
               oder
               a1 =     Path of the symbolic link

 Description: The kernel differentiates between two different types of 
              descriptors, file descriptors (FD) and directory 
              descriptors (DD), which can have an identical structure 
              however. The xfs_path2DD function returns a descriptor 
              for a path.
              The reference counter of the DD must be incremented by 1 
              each time it is returned as a function value, as it is 
              referenced by the kernel. The xfs_path2DD function 
              corresponds to an 'opening' of the path; a kind of 'file 
              handle' is returned to the kernel, which the kernel has 
              to close again. The parsing of the path must always be 
              taken care of by the XFS.

              Input parameters:

               <mode>      Determines whether the last path element is 
                           itself a directory (mode == 1), or whether 
                           the path is to be obtained in which this 
                           file lies
               <reldir>    Directory from which the search is to start
               <pathname>  The pathname, without drive letter and 
                           without leading '\'

              Output parameters:

              1st case: An error has arisen

              d0 contains the error-code

              2nd case: A directory descriptor (DD) could not be 
              obtained

               <d0> Pointer to the DD; the XFS has incremented the 
                    reference counter of the DD by 1
               <d1> Pointer to the remaining filenames without leading 
                    '\' or '/'; if the end of the path was reached, 
                    this pointer points to the terminating NULL-byte

              3rd case: The XFS hit on a symbolic link during the 
              )path evaluation

               <d0>  Contains the internal MagiC error-code ELINK
               <d1>  Pointer to the remaining path without the leading 
                     '\' or '/'
               <a0>  Contains the DD of the path in which the symbolic 
                     link lies; the XFS has incremented the reference 
                     counter of the DD by 1
               <a1>  This is the pointer to the link itself; a link 
                     starts with a WORD (16 bits) 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 has to lie at an even 
              memory address.

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

              If a1 == NULL is passed, a signal is sent to the kernel 
              that the parent of the root directory was selected. If 
              the path resides, say, on U:\A, then the kernel can fall 
              back to U:\. The value of the return register a0 is 
              ignored by the kernel, so no reference counter may be 
              incremented.

 Group:       Make-up of an XFS

 See also:    MagiC's XFS-concept