HomeGEMDOSSystem functionsCharacter input/output

5.15 Directory functions

Dchroot     Changes the root directory for the calling process.
Dclosedir   Closes a directory.
Dcntl       File-system-specific operation on file/directory.
Dcreate     Creates a directory.
Ddelete     Deletes a directory.
Dfree       Obtains free and total capacity of a drive.
Dgetcwd     Obtains directory of a process.
Dgetdrv     Obtains current drive.
Dgetpath    Obtains current directory.
Dlock       Locks or releases again a BIOS device.
Dopendir    Opens a directory for reading.
Dpathconf   Obtains information about a file-system.
Dreaddir    Reads directory information.
Dreadlabel  Reads file-system label.
Drewinddir  Rewinds opened directory pointer.
Dsetdrv     Sets current drive.
Dsetpath    Sets current directory.
Dwritelabel Sets file-system label.
Dxopendir   Opens directory for reading.
Dxreaddir   Reads directory information, obtains attributes.

See also: File functions   XBIOS drive functions

5.15.1 Dchroot

Name: »Dchroot« - Change the root directory for the calling process.
Opcode: 330 (0x014a)
Syntax: int32_t Dchroot( int8_t *path );
Description: The path parameter is a pathname of the folder that will be the new root directory for the calling process. Directories and files which are outside of the specified tree will no longer be accessible.

Dchroot does not automatically change the current directory to the newly specified root. Also, the call needs root privileges to operate properly. This function is used by e.g. ftpd to limit the user privileges in accessing file-systems.
Return value: Returns the E_OK on success, or a negative GEMDOS error-code otherwise.
Availability As of FreeMiNT version 1.15.4
Group: Directories functions
See also: Binding   Dopendir   Dreaddir   MagiC

5.15.1.1 Bindings for Dchroot

C: int32_t Dchroot( int8_t *path );
Assembler:
pea       path             ; Offset 2
move.w    #330,-(sp)       ; Offset 0
trap      #1               ; GEMDOS
addq.l    #6,sp            ; Correct stack

5.15.2 Dclosedir

Name: »Dclosedir« - Close a specified directory.
Opcode: 299
Syntax: int32_t Dclosedir ( int32_t dirhandle );
Description: The function Dclosedir closes the directory with the handle dirhandle.
Return value: The function returns the value 0 if the directory could be closed correctly. If dirhandle is invalid, then the value EIHNDL will be returned.
Availability: Available when a 'MiNT' cookie with a version of at least 0.90 exists, and MagiC as of Version 3.0.
Group: Directory functions
See also: Binding   Dopendir   Dreaddir   MagiC

5.15.2.1 Bindings for Dclosedir

C: int32_t Dclosedir ( int32_t dirhandle );
Assembler:
move.l    dirhandle,-(sp)  ; Offset 2
move.w    #299,-(sp)       ; Offset 0
trap      #1               ; GEMDOS
addq.l    #6,sp            ; Correct stack

5.15.3 Dcntl

Name: »Dcntl« - Execute a file-system-specific operation on a file or a directory.
Opcode: 304
Syntax: int32_t Dcntl ( int16_t cmd, int8_t *name, int32_t arg );
Description: The function Dcntl executes the command cmd on the file or the directory name. Details depend on the file-system to which name refers. The meaning of the parameter arg is in turn dependent on cmd.

Normally the Dcntl call is supported by the file-systems U:\\ and U:\DEV.

The unified file-system U:\ knows the following commands:
Command Description
FS_INSTALL (0xf001) Installs a new file-system
name: Must be U:\
arg: Pointer to fs_descr structure
FS_MOUNT (0xf002) Mounts an already existing file-system in the unified system U:\
name: Name under which one can access the file-system
arg: Pointer to fs_descr structure
FS_UNMOUNT (0xf003) Unmounts a file-system installed by FS_MOUNT
name: Name under which the file-system was mounted
arg: Pointer to fs_descr structure
FS_UNINSTALL (0xf004) Removes a file-system completely from the kernel. This command is only allowed if no further references to the file-system exist, so that any mounts have been revoked, for instance.
name: U:\\
arg: Pointer to fs_descr structure
FUTIME (0x4603) Is the complement to the Fcntl function of the same name. It is supported by MiNT as well as DOS-XFS in MagiC. A pointer to a mutimbuf structure is passed as a parameter.
KER_GETINFO (0x0100) Obtains a pointer to the kernel functions of MagiC. The parameters name and arg must have NULL-values. The return is a pointer to a MX_KERNEL structure. (*)

As of MagiC 6: MX_KER_GETINFO (0x6d00) (1)
KER_DOSLIMITS (0x0101) Invites the kernel of MagiC to obtain the limits for FAT file-systems. The parameter name and arg must be set to NULL. The return is a pointer to a pointer to a MX_DOSLIMITS structure; this can therefore be diverted to one's own structure if a new driver is installed. This opcode is normally used only by hard disk drivers (such as HDDRIVER). (*)

As of MagiC 6: MX_KER_DOSLIMITS (0x6d01) (1)
KER_INTMAVAIL (0x102)  
KER_INTGARBC (0x103) These functions exist in versions of MagiC prior to Version 4.01, and are converted to Sconfig calls to avoid conflicts with drivers that have problems with unknown opcodes (*).
KER_DRVSTAT (0x0104) Obtains simple information about a drive. The following apply:
name: Is ignored
arg: Pointer to two int16_ts.


The first int16_t here must hold a NULL, into the second a drive number from 0..25 (A..Z) will be written. The possible return values for this opcode are:
EDRIVE : Invalid drive number
ELOCKED : Drived locked at present


A value of 0 or >0 indicates that the drive is at present mounted or not mounted respectively. This opcode is only available from the MagiC Version of 09.09.95 onwards (*).

As of MagiC 6: MX_KER_DRVSTAT (0x6d04) (1)
KER_XFSNAME (0x0105) Obtains the name of the driver that is responsible for a given directory.
name: Pathname (not filename!)
arg: Pointer to a buffer at least 9 characters long which has to lie at an even address.


A return value < 0 denotes no error; otherwise the name of the driver will be stored in the specified buffer; at present the following driver names are known:
(a) "DOS_XFS": Old DOS-XFS
(b) "VDOS_XFS": DOS-XFS with VFAT
(c) "MMAC_HFS": MagiCMac-HFS


This opcode is only available from the MagiC Version of 15.06.1996 onwards (*).

As of MagiC 6: MX_KER_XFSNAME (0x6d05) (1)
KER_INSTXFS (0x0200) Invites the kernel of MagiC to install an XFS (*)
name: NULL-pointer
arg: Driver to install


As of MagiC 6: MX_KER_INSTXFS (0x6d02) (1)
KER_SETWBACK (0x0300) Invites the kernel of MagiC to configure the WriteBack. As of MagiC Version 4.01, this opcode was converted to a Sconfig call, to prevent conflicts with drivers that have problems with unknown opcodes (*).
DFS_GETINFO (0x1100) Obtains a pointer to the DOS_XFS functions of MagiC. The parameters name and arg must have NULL-values. The return is a pointer to a ??? structure. (*)

As of MagiC 6: MX_DFS_GETINFO (0x6d40) (1)
DFS_INSTDFS (0x1200) Installs a DFS under MagiC (*).
name: NULL-pointer
arg: Driver to install
CDROMEJECT (0x4309) Takes charge of ejection of media.
name: Path of the medium to be ejected
arg: NULL


The ejection function is supported for all drives that are accessed via an XHDI-compatible driver, as well as for Macintosh volumes (under MagiCMac).

As of MagiC 6: MX_DFS_INSTDFS (0x6d41) (1)
VFAT_CNFDFLN (0x5600) Configures a VFAT file-system
name: U:\\
arg: Bit-vector that determines which drives permit long filenames


The setting only becomes active on mounting a file-system, so that already mounted file-systems can not be affected by it. This opcode is only available from the MagiC Version of 02.01.96 onwards. (*).
VFAT_CNFLN (0x5601) Serves for the configuration of a VFAT file-system. More exactly: Determines whether a mounted drive supports long filenames, or not. With this opcode therefore one can supplant the default value set by VFAT_CNFDFLN. So that the change becomes visible to the user, a SH_WDRAW message should be sent to the system shell. This opcode is only available as of the MagiC Version of 02.01.96 (*).
PROC_CREATE (0xcc00) This function is reserved in MagiC for future use (*). It is no longer used as of MagiC 6.


The file-system U:\DEV knows the following commands:
Command Description
   
DEV_INSTALL (0xde02) Installs a new driver for a device.
name: Complete pathname of the driver
arg: Pointer to dev_descr structure


The device installed in this way may only be accessed via GEMDOS operations.
DEV_M_INSTALL (0xcd00) Corresponds to DEV_INSTALL and has to be used in MagiC due to the incompatible driver format to MultiTOS. (*)
name: Complete pathname of the driver
arg: Pointer to MX_DDEV structure


As of MagiC 6: MX_DEV_INSTALL (0x6d20) (1)
DEV_NEWTTY (0xde00) Installs drivers for a new BIOS terminal
name: Name of the terminal (in the form 'U:\DEV\DEVNAME')
arg: BIOS device number of the terminal


The BIOS must have been informed about the device via Bconmap, else any attempt to access the device will be punished with EUNDEV.
DEV_NEWBIOS (0xde01) Installs a driver for a new BIOS non-terminal device (devices that must have their data transmitted raw, such as SCSI devices).
name: Complete name of the device
arg: Associated BIOS device number


The BIOS must have been informed about the device via Bconmap, else any attempt to access the device will be punished with EUNDEV.


Note: The opcodes marked with (*) here are only available under MagiC, all others only under MiNT or MultiTOS. Exceptions: The opcodes FUTIME and CDROMEJECT are avaiable both under MiNT/MultiTOS as well as under MagiC.

(1): Unfortunately there were collisions between MagiC and the Minix-XFS for MiNT. Hence MagiC as of Version 6 contains new codes, though the old ones are still supported. The new codes have 0x6d in the upper WORD; this ID is reserved for MagiC.
Return value: The return value depends on the desired operation and the underlying file-system. With a value >= 0 everything was successful. An exception is the value for DEV_INSTALL, which either points to an information structure of the kernel, or else has the value 0.

For an invalid opcode, EINVFN will be returned.
Availability: Available when a 'MiNT' cookie with a version of at least 0.90 exists, and MagiC as of Version 3.0.
Group: Directory functions
See also: Binding   XFS-concept in MagiC   Bconmap   Fcntl   MagiC   Metaioctl

5.15.3.1 Bindings for Dcntl

C: int32_t Dcntl ( int16_t cmd, int8_t *name, int32_t arg );
Assembler:
move.l    arg,-(sp)    ; Offset 8
pea       name         ; Offset 4
move.w    cmd,-(sp)    ; Offset 2
move.w    #304,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
lea       $C(sp),sp    ; Correct stack

5.15.4 Dcreate

Name: »Create directory« - Create a directory.
Opcode: 57
Syntax: int32_t Dcreate ( CONST int8_t *path );
Description: The GEMDOS routine Dcreate creates a directory with the pathname path, which has to be terminated with the ASCII character 0, on the specified drive.

Note: Due to defective error-handling in GEMDOS Versions < 0.15, the file-system could be damaged in some circumstances. Furthermore, no check was made whether a file with the specified name already exists.

As of MagiC 3, the call is passed on by the kernel as xfs_dcreate with creation mode Fxattr %0100000111101101 (i.e. a 'directory file' with access permissions RWXRwXRwX). The XFS should not delete any files or subdirectories of the same name, but return the error-code EACCDN in this case. Invalid filenames "." or ".." must also be intercepted by the XFS.
Return value: The function can return the following results:
E_OK No error has arisen
EPTHNF Directory not found
EACCDN Access denied
Availability: All GEMDOS versions.
Group: Directory functions
See also: Binding   Ddelete   ASCII table

5.15.4.1 Bindings for Dcreate

C: int32_t Dcreate ( CONST int8_t *path );
Assembler:
pea       path         ; Offset 2
move.w    #57,-(sp)    ; Offset 0
trap      #1           ; GEMDOS
addq.l    #6,sp        ; Correct stack
GFA-Basic Fehler%=Gemdos(&H39,L:path%)

5.15.5 Ddelete

Name: »Delete directory« - Delete a directory.
Opcode: 58
Syntax: int32_t Ddelete ( CONST int8_t *path );
Description: The GEMDOS routine Ddelete deletes a directory with the pathname path, which may not contain any files or subdirectories. The string path must be terminated with the ASCII character 0.

Note: In GEMDOS Versions < 0.15 a call of Dcreate with an immediately following Ddelete did not work - only a further Ddelete achieved the desired result.

In MagiC the kernel first checks whether the directory is a current path and if appropriate returns an error-message. If possible, only empty directories should be deleted; this is however up to the XFS. As of MagiC Version 4.01, symbolic links too can be deleted with this function; older versions always deleted the directory to which the link pointed.
Return value: The function can return the following results:
E_OK No eror has arisen
EPTHNF Directory not found
EACCDN Access denied
EINTRN Internal error of the GEMDOS
Availability: All GEMDOS versions.
Group: Directory functions
See also: Binding   Dcreate   XFS-concept in MagiC

5.15.5.1 Bindings for Ddelete

C: int32_t Ddelete ( CONST int8_t *path );
Assembler:
pea       path         ; Offset 2
move.w    #58,-(sp)    ; Offset 0
trap      #1           ; GEMDOS
addq.l    #6,sp        ; Correct stack
GFA-Basic Fehler%=Gemdos(&H3A,L:path%)

5.15.6 Dfree

Name: »Free disk space« - Obtain free and total capacity of a drive.
Opcode: 54
Syntax: int16_t Dfree ( DISKINFO *buf, int16_t driveno );
Description: The GEMDOS routine Dfree obtains the capacity and current occupancy of a drive. The following apply:
Parameter Meaning
   
buf Address of the information buffer
driveno
0 = Current drive
1 = Drive A:
2 = Drive B: (etc.)


Note: In GEMDOS Versions < 0.15 this function is unbelievably slow when used on a hard drive.

Applied to the directory U:\PROC, from MagiC 3 onwards this function returns the minimum, actual block length (as sectors per cluster). Presently the memory is allocated word-wise, i.e. the 'sector size' is 1 int8_t and the cluster size comprises 2 sectors (i.e. 2 int8_ts).
Return value: The function returns a 0 for a correct execution, or a negative number if an error arose.
Availability: All GEMDOS versions.
Group: Directory functions
See also: Binding   Fdelete

5.15.6.1 Bindings for Dfree

C: int16_t Dfree ( DISKINFO *buf, int16_t driveno );
Assembler:
move.w    driveno,-(sp)  ; Offset 6
pea       buf            ; Offset 2
move.w    #54,-(sp)      ; Offset 0
trap      #1             ; GEMDOS
addq.l    #8,sp          ; Correct stack
GFA-Basic Fehler%=Gemdos(&H36,L:buf%,W:driveno%)

5.15.7 Dgetcwd

Name: »Dgetcwd« - Obtain the current directory of a process.
Opcode: 315
Syntax: int32_t Dgetcwd ( int8_t *path, int16_t drv, int16_t size );
Description: The current working directory of the active process in drive drv is returned. The parameter size gives the size of the buffer for accommodating the name.
Return value: path: Directory of the current process.

The return value of the function is either 0 (all OK), ERANGE (the size of the buffer is insufficient to hold the exact description of the directory), or EDRIVE (invalid GEMDOS ignore} drive).
Availability: Available when a 'MiNT' cookie with a version of at least 0.96 exists, and MagiC as of Version 3.0.
Group: Directory functions
See also: Binding   Dgetpath

5.15.7.1 Bindings for Dgetcwd

C: int32_t Dgetcwd ( int8_t *path, int16_t drv, int16_t size );
Assembler:
move.w    size,-(sp)   ; Offset 8
move.w    drv,-(sp)    ; Offset 6
pea       path         ; Offset 2
move.w    #315,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
lea       $A(sp),sp    ; Correct stack

5.15.8 Dgetdrv

Name: »Disk get drive« - Obtain the current drive.
Opcode: 25
Syntax: int16_t Dgetdrv ( VOID );
Description: The GEMDOS routine Dgetdrv obtains the current drive.
Return value: The function returns a number, which is coded as follows:
Value Meaning
   
0 Drive A:
1 Drive B:
2 Drive C:
3 Drive D: (etc.)


Note: As of MagiC 3, drives from A: to Z:, i.e. values from 0 to 25, are permissible.
Availability: All GEMDOS versions.
Group: Directory functions
See also: Binding   Dsetdrv   _drvbits

5.15.8.1 Bindings for Dgetdrv

C: int16_t Dgetdrv ( VOID );
Assembler:
move.w    #25,-(sp)    ; Offset 0
trap      #1           ; GEMDOS
addq.l    #2,sp        ; Correct stack
GFA-Basic Fehler%=Gemdos(&H19)

5.15.9 Dgetpath

Name: »Get path« - Obtain current path specification.
Opcode: 71
Syntax: int16_t Dgetpath ( int8_t *path, int16_t driveno );
Description: The GEMDOS routine Dgetpath obtains the current directory on the drive driveno. The designation of the drives are coded in the parameter driveno as follows:
driveno Meaning
   
0 Current drive
1 Drive A:
2 Drive B:
3 Drive C: (etc.)


The path is stored in buffer path as a string. As the maximum path length is not restricted in GEMDOS, and can be obtained only with the existence of the function Dpathconf, the receiving buffer should offer sufficient space (256 bytes ought to be enough).
Return value: The function can return the following results:

E_OK : No eror has arisen
EDRIVE : Invalid drive number
Availability: All GEMDOS versions.
Group: Directory functions
See also: Binding   Dsetpath

5.15.9.1 Bindings for Dgetpath

C: int16_t Dgetpath ( int8_t *path, int16_t driveno );
Assembler:
move.w    driveno,-(sp)  ; Offset 6
pea       path           ; Offset 2
move.w    #71,-(sp)      ; Offset 0
trap      #1             ; GEMDOS
addq.l    #8,sp          ; Correct stack
GFA-Basic Fehler%=Gemdos(&H47,L;path%,W:driveno%)

5.15.10 Dlock

Name: »Dlock« - Lock a BIOS device or releases it again.
Opcode: 309
Syntax: int32_t Dlock ( int16_t mode, int16_t drv );
Description: The function Dlock permits the locking of the BIOS device drv, or releasing it again. On a locked drive no GEMDOS file operations are permitted; Rwabs is only allowed for the locking process.

The purpose of the function is to allow low-level programs (such as those for formatting) to perform (X)BIOS functions, while the device remains locked for normal file accesses.

Bit 0 of mode = 1: Lock device
= 0: Release device


If a process is terminated that still holds a lock on a device, then this lock will be lifted.

Bit 1 of mode indicates which return values are desired. If this bit is set, and the corresponding device is already locked by another process (or if another process has opened files on this device), then this process' ID will be returned. This permits more meaningful error-messages to the user, as one can now disclose which process is using the device if the locking should go wrong.

All other bits of mode are reserved and must be set to 0.

Locking of a device with immediately following release of the same is very similar to a media change. One should merely note that it is not possible to lock if files are still open on the specified device.

Note for MagiC: Before locking of the drive, provided a file-system exists for the drive, the caches will be written back via the vector xfs_sync. Then the kernel inquires via xfs_drv_close whether the drive may be locked. If so, the XFS releases its structures and then signals the kernel that it too can release its structures for the drive, and perform the lock.
Return value: The function can return the following values:
E_OK : No error has arisen
EACCDN : Device could not be locked, as open files or directories exist on it
EDRIVE : drv is not a valid BIOS device
ELOCKED : Device is already locked by another process
ENSLOCK : Device has been released already
Availability: Available when a 'MiNT' cookie with a version of at least 0.93 exists, and MagiC as of Version 3.0.
Group: Directory functions
See also: Binding   Fxattr   XFS-concept in MagiC

5.15.10.1 Bindings for Dlock

C: int32_t Dlock ( int16_t mode, int16_t drv );
Assembler:
move.w    drv,-(sp)    ; Offset 4
move.w    mode,-(sp)   ; Offset 2
move.w    #309,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #6,sp        ; Correct stack

5.15.11 Dopendir

Name: »Dopendir« - Open a specified directory for reading.
Opcode: 296
Syntax: int32_t Dopendir ( int8_t *name, int16_t flag );
Description: The function Dopendir opens the directory name for reading. name should be NULL-terminated and should not contain a trailing backslash. The parameter flag describes the manner in which the directory is to be opened:
flag Meaning
   
0 Normal mode
In this mode an attempt is made not to restrict the length of the filename. Also, Dreaddir in this mode return an index number (similar to the UNIX inode's) in the first 4 bytes of the filename.
1 Compatibility mode
In this mode file-systems behave as if Fsfirst or Fsnext calls were being used. In particular, filenames will be truncated according to the DOS-convention to 8+3 characters, if that is possible.


Newer programs should always use the normal mode if possible, in order to exploit the full functionaity.
Return value: The function returns a 32-bit directory handle if successful; this may also be negative, but in no case may contain the value 0xff in the higher byte, through which it can be differentiated from errors.

In case of error, the following returns are possible:
EPTHNF : name is not a valid directory
EACCDN : The directory is not addressable by this program
ENSMEM : The kernel cannot allocate memory for this operation
Availability: Available when a 'MiNT' cookie with a version of at least 0.90 exists, and in MagiC as of Version 3.0.
Group: Directory functions
See also: Binding   Dclosedir   Dreaddir   Drewinddir   Pdomain

5.15.11.1 Bindings for Dopendir

C: int32_t Dopendir ( int8_t *name, int16_t flag );
Assembler:
move.w    flag,-(sp)   ; Offset 6
pea       name         ; Offset 2
move.w    #296,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #8,sp        ; Correct stack

5.15.12 Dpathconf

Name: »Dpathconf« - Obtain information about a file-system.
Opcode: 292
Syntax: int32_t Dpathconf ( BYTE *name, int16_t mode );
Description: The function Dpathconf makes it possible to obtain information about the file-system that contains the file name.

The parameter mode specifies which possibilities or restrictions of the file-systems are to be inquired. Possible values here are:
mode Meaning
   
-1: Maximum permissible value for Dpathconf itself
DP_IOPEN (0): Maximum number of opened files
DP_MAXLINKS (1): Maximum number of references (links) to a file
DP_PATHMAX (2): Maximum length of the full pathname
DP_NAMEMAX (3): Maximum length of a filename
DP_ATOMIC (4): Number of bytes that may be written at a time per write operation
DP_TRUNC (5): Information about truncation of filenames:
0 = Filenames are not trunctated; if the maximum filename length is exceeded at a system call, the value ERANGE will be returned
1 = Filenames are truncated automatically to the maximum possible length
2 = Filenames are truncated according to the DOS convention (i.e. 8 characters for the name, 3 characters for the extension)
DP_CASE (6): Information about case sensitivity:
0 = Differentiation between capitals and lower case (file-system is case-sensitive)
1 = No differentiation between capitals and lower case (all characters are converted to either capitals or lower case - file-system is not case-sensitive)
2 = No differentiation between capitals and lower case; however the file-system saves the path and filenames with the original values
Example: The displayed file 'HelloWorld' can also be accessed with 'HELLOWorld' or 'HeLLoWORLD'
DP_MODEATTR (7): Information about mode-bits of a file:

This mode returns information about the validity of the values defined in the mode and attr fields of the XATTR structure. The bits 0..5 describe which flags of the component attr are valid. The following apply:
FA_RDONLY (0x01): Is set only if the read permission is controlled via this bit, and not when it is emulated via the meaning of the mode-bits
FA_HIDDEN (0x02):  
FA_SYSTEM (0x04): Is set if the file-system supports these specific attributes (normally only the case for DOS file-systems)
FA_LABEL (0x08): Is set if the file-system label can be obtained with Fsfirst/Fsnext
FA_DIR (0x10): Reserved; to decide whether one is dealing with a folder on the file-system, one should fall back to the filetype bits (see below)
FA_CHANGED (0x20): Is set if the file-system knows the concept of archive bits, and the attr field is used for this purpose


The bits 6 and 7 are reserved. The bits 8..19 store information about whether the lower 12 bits of the mode component are valid. The bits 20..27 describe which filetypes are supported by the file-system. The following applies:
DP_FT_DIR (0x00100000L): Folder
DP_FT_CHR (0x00200000L): Special character-files
DP_FT_BLK (0x00400000L): Special block-files (unused at present)
DP_FT_REG (0x00800000L): Regular files
DP_FT_LNK (0x01000000L): Symbolic links
DP_FT_SOCK (0x02000000L): Sockets (unused at present)
DP_FT_FIFO (0x04000000L): Pipes
DP_FT_MEM (0x08000000L): Shared memory or process files


The bits 28..31 are reserved.
DP_XATTRFIELDS (8): Information about extended attributes:

In this mode a bit-mask of the supported fields (specified in the XATTR structure) is returned. The following apply:
DP_INDEX (0x0001): Unambiguous index field for each file on the file-system
DP_DEV (0x0002): Device number
DP_RDEV (0x0004): rdev field valid, and not identical to the dev field
DP_NLINK (0x0008): Number of links
DP_UID (0x0010): User number
DP_GID (0x0020): Group number
DP_BLKSIZE (0x0040): Block size
DP_SIZE (0x0080): File length
DP_NBLOCKS (0x0100): Number of blocks
DP_ATIME (0x0200): Time of last access
DP_CTIME (0x0400): Time of file creation
DP_MTIME (0x0800): Time of last change


All other bits are reserved for future purposes.
DP_VOLNAMEMAX (9): Maximum length of a volume name (0 if volume names not supported)


A return value of 0x7fffffff (2^31 -1) means that there is no limit for the component inquired about.

Note: In MagiC the function can also be applied to files. However the filename is ignored in this case, i.e. only the path will be evaluated. The function should be called in MagiC after Dopendir if necessary, as Dpathconf does not recognise disk changes (reason: if the path is still in the cache, no disk access is performed and hence no disk change is recognised).
Return value: The function returns the properties/limitations of the file-system paying regard to the parameter mode (see above).
Availability: As of the first in MultiTOS integrated MiNT version 1.04, and in MagiC as of Version 3.0.
Group: Directory functions
See also: Binding   Sysconf   XFS-concept in MagiC   Test for pipes

5.15.12.1 Bindings for Dpathconf

C: int32_t Dpathconf ( BYTE *name, int16_t mode );
Assembler:
move.w    mode,-(sp)   ; Offset 6
pea       name         ; Offset 2
move.w    #292,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #8,sp        ; Correct stack

5.15.13 Dreaddir

Name: »Dreaddir« - Read directory information.
Opcode: 297
Syntax: int32_t Dreaddir ( int16_t len, int32_t dirhandle, int8_t *buf );
Description: The function Dreaddir returns the next file in the directory dirhandle. The filename and an optional 4-byte index for the file are written to buf.

The file index is omitted if the directory was opened im compatibility mode, otherwise it appears as the first in buf followed by a (NULL-terminated) filename.

(Possibly different) names with the same index belong to the same file. (Possibly same) names with different indexes belong to different files.

Note about MagiC: For FAT file-systems the function returns the following index data:
  • Directories: Start cluster in Motorola format
  • Other files:
    High word = Start cluster of the directory
    Low word = Position within the directory >> 5


This procedure is similar to that used by Linux and Solaris. The drawback is that files alter their index during a move.

In len the size of the receiving buffers has to be specified.
Return value: The function can return the following results:
E_OK : No error has arisen
ENMFIL : No further files present
ERANGE : The buffer length is insufficient
Availability: Available when a 'MiNT' cookie with a version of at least 0.90 exists, and in MagiC as of Version 3.0.
Group: Directory functions
See also: Binding   Dclosedir   Dopendir   Drewinddir   Dxreaddir

5.15.13.1 Bindings for Dreaddir

C: int32_t Dreaddir ( int16_t len, int32_t dirhandle, int8_t *buf );
Assembler:
pea       buf          ; Offset 8
move.l    dirhandle    ; Offset 4
move.w    len          ; Offset 2
move.w    #297,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
lea       $C(sp),sp    ; Correct stack

5.15.14 Dreadlabel

Name: »Dreadlabel« - Read file-system label.
Opcode: 338 (0x0152)
Syntax: int32_t Dreadlabel ( CONST int8_t *path, int8_t *label, int16_t length );
Description: The function Dreadlabel returns in label the name of the file-system lying in path. The parameter length specifies the size of the receiving buffer for label.
Return value: The function can return the following results:
E_OK : No eror has arisen
ENAMETOOLONG : The name of the file-system is longer than the size of the receiving buffer
Availability: In MagiC as of Version 3.0, from MiNT 1.12 onwards.
Group: Directory functions
See also: Binding   Dwritelabel   XFS-concept in MagiC

5.15.14.1 Bindings for Dreadlabel

C: int32_t Dreadlabel ( CONST int8_t *path, int8_t *label, int16_t length );
Assembler:
move.w    length,-(sp)  ; Offset 10
pea       label         ; Offset  6
pea       path          ; Offset  2
move.w    #338,-(sp)    ; Offset  0
trap      #1            ; GEMDOS
lea       $C(sp),sp     ; Correct stack

5.15.15 Drewinddir

Name: »Drewinddir« - Rewind the pointer for the specified directory to the first file.
Opcode: 298
Syntax: int32_t Drewinddir ( int32_t handle );
Description: The function Drewinddir resets the directory handle to the start, so that the next call of Dreaddir reads the first entry in the directory once more.
Return value: The function can return the following results:
E_OK : No error has arisen
EINVFN : Directory cannot be rewound
EIHNDL : The directory handle is not open
Availability: Available when a 'MiNT' cookie with a version of at least 0.90 exists, and in MagiC as of Version 3.0.
Group: Directory functions
See also: Binding   Dopendir   Dreaddir

5.15.15.1 Bindings for Drewinddir

C: int32_t Drewinddir ( int32_t handle );
Assembler:
move.l    handle,-(sp)  ; Offset 2
move.w    #298,-(sp)    ; Offset 0
trap      #1            ; GEMDOS
addq.l    #6,sp         ; Correct stack

5.15.16 Dsetdrv

Name: »Disk set drive« - Set the current drive and returns a bit-map of mounted drives.
Opcode: 14
Syntax: int32_t Dsetdrv ( int16_t drv );
Description: The GEMDOS routine Dsetdrv makes the drive drv the current default drive. The following apply:
drv Meaning
   
0 Drive A:
1 Drive B:
2 Drive C: (etc.)


Note: An incorrect drive number can lead to serious damage in GEMDOS-internal structures. The drives supported by GEMDOS are best interrogated as follows:
Dsetdrv (Dgetdrv ());


As of MagiC 3, drives from A to Z, i.e. values from 0 to 25 are permissible. No check is made whether the specified drive even exists.

GEMDOS0.30 (TOS 4.00-4.04) returns erroneous EDRIVEs for drives above P:!
Return value: Return value: The function returns a bit-table with all mounted drives. Each mounted drive is shown as one set bit.
Availability: All GEMDOS versions.
Group: Directory functions
See also: Binding   Dgetdrv   _drvbits

5.15.16.1 Bindings for Dsetdrv

C: int32_t Dsetdrv ( int16_t drv );
Assembler:
move.w    drv,-(sp)    ; Offset 2
move.w    #14,-(sp)    ; Offset 0
trap      #1           ; GEMDOS
addq.l    #4,sp        ; Correct stack
GFA-Basic Fehler%=Gemdos(&H0E,W:drv%)

5.15.17 Dsetpath

Name: »Set path« - Set the current directory.
Opcode: 59
Syntax: int16_t Dsetpath ( CONST int8_t *path );
Description: The GEMDOS routine Dsetpath sets a new access path for the current drive. The parameter path contains the new current access path for the drive.

Note: For each drive, GEMDOS will remember the current directory. However, the function Dsetpath should be used only for the current drive. For other drives the following method should be applied instead:
  • Establish current drive
  • Set desired drive
  • Set path for this drive
  • Make the old (remembered) drive the current one again


On some (older) versions of GEMDOS, a too frequent setting of non-existing paths can lead to disturbance in the internal structures.
Return value: The function can return the following results:
E_OK No eror has arisen
EPTHNF Directory not found
Availability: All GEMDOS versions.
Group: Directory functions
See also: Binding   Dgetpath

5.15.17.1 Bindings for Dsetpath

C: int16_t Dsetpath ( CONST int8_t *path );
Assembler:
pea       path         ; Offset 2
move.w    #59,-(sp)    ; Offset 0
trap      #1           ; GEMDOS
addq.l    #6,sp        ; Correct stack
GFA-Basic Fehler%=Gemdos(&H3B,L:path%)

5.15.18 Dwritelabel

Name: »Dwritelabel« - Set file-system label.
Opcode: 339 (0x0153)
Syntax: int32_t Dwritelabel ( CONST int8_t *path, CONST int8_t *label );
Description: The function Dwritelabel writes the name specified in label to the file-system specified in path.

Prior to MiNT version 1.14.5 this call contained a bug that allowed the label to be changed by all users.
Return value: E_OK if successful, else a negative GEMDOS error-code.
Availability: MagiC as of Version 3.0, MiNT 1.12
Group: Directory functions
See also: Binding   Dreadlabel   XFS-concept in MagiC

5.15.18.1 Bindings for Dwritelabel

C: int32_t Dwritelabel ( CONST int8_t *path, CONST int8_t *label );
Assembler:
pea       label        ; Offset 6
pea       path         ; Offset 2
move.w    #339,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
lea       $A(sp),sp    ; Correct stack

5.15.19 Dxopendir

Name: »Dxopendir« - Open directory for reading.
Opcode: 1296
Syntax: int32_t Dxopendir ( int8_t *name, int16_t flag );
Description: Dxopendir calls the normal Dopendir, but then saves the returned handle and flag in a chained list, so that Dreaddir and Dxreaddir know what they have to convert for this directory. Dcloseddir deletes the handle again from the list.

Dreaddirand Dxreaddir convert the returned name to lower case.

The function opens the directory name for reading. The parameter flag describes the manner how the directory is to be opened:
flag Meaning
   
0 Normal mode
In this mode an attempt is made not to restrict the length of the filename. Also, Dreaddir in this mode return an index number (similar to the UNIX inode's) in the first 4 bytes of the filename.
1 Compatibility mode
In this mode file-systems behave as if Fsfirst or Fsnext calls were being used. In particular, filenames will be truncated according to the DOS-convention to 8+3 characters, if that is possible.


Newer programs should always use the normal mode if possible, in order to exploit the full functionaity.
Return value: The function returns a 32-bit directory handle if successful; this may also be negative, but in no case may contain the value 0xff in the higher byte, through which it can be differentiated from errors.

In case of error, the following returns are possible:
EPTHNF : name is not a valid directory
EACCDN : The directory is not addressable by this program
ENSMEM : The kernel cannot allocate memory for this operation
Availability: When the system extension Dir_Lwr (supplied with Égale 4.2) is installed. Creates the cookie 'DYDL'.
Group: Directory functions
See also: Binding   Dclosedir   Dreaddir   Drewinddir   Pdomain

5.15.19.1 Bindings for Dxopendir

C: int32_t Dxopendir ( int8_t *name, int16_t flag );
Assembler:
move.w    flag,-(sp)   ; Offset 6
pea       name         ; Offset 2
move.w    #1296,-(sp)  ; Offset 0
trap      #1           ; GEMDOS
addq.l    #8,sp        ; Correct stack

5.15.20 Dxreaddir

Name: »Dxreaddir« - Read directory information, obtain attributes.
Opcode: 322, (0x142)
Syntax: int32_t Dxreaddir ( int16_t ln, int32_t dirh, int8_t *buf, XATTR *xattr, int32_t *xr );
Description: The function Dxreaddir returns the next file from the directory with the handle dirh. The filename and the optional 4 byte long file index are stored in the buffer specified in buf.

The file index is omitted if the compatibility mode was specified for Dopendir. If two filenames have the same index, they represent the same file.

MagiCreturns for FAT file-systems the following index data:
  • Directories: Start cluster in Motorola format
  • Other files:
    High word = Start cluster of the directory
    Low word = Position within the directory >> 5


This procedure is similar to that used by Linux and Solaris. The drawback is that files alter their index during a move.

The parameter ln specifies the length of the receiving buffer buf. The extended file attributes are stored similarly to Fxattr in the xattr structure, where symbolic links are not dissolved.

Note: This part of the call may fail even though the filename was readable. In that case a separate return code will be stored in the LONG value to which the parameter xr points.
Return value: The function can return the following results:
E_OK : No error has arisen
ENMFIL : No further files found
ERANGE : The receiving buffer is not large enoough
Availability: MagiC as of Version 3.0, MiNT 1.11 onwards.
Group: Directory functions
See also: Binding   Dreaddir   Dopendir   Dclosedir   Drewinddir

5.15.20.1 Bindings for Dxreaddir

C: int32_t Dxreaddir ( int16_t ln, int32_t dirh, int8_t *buf, XATTR *xattr, int32_t *xr );
Assembler:
pea       xr           ; Offset 16
pea       xattr        ; Offset 12
pea       buf          ; Offset  8
move.l    dirh         ; Offset  4
move.w    ln           ; Offset  2
move.w    #322,-(sp)   ; Offset  0
trap      #1           ; GEMDOS
lea       $14(sp),sp   ; Correct stack

HomeGEMDOSSystem functionsCharacter input/output