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.16.10  Dlock                                                     TOS

 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