Info

Returns information about the disk

Info() can be used to find information about any disk in use. 'lock' refers to the disk, or any file on the disk. The parameter block is returned with information about the size of the disk, number of free blocks and any soft errors.

lock

BCPL pointer to a Lock

infodata

pointer to an InfoData structure which must be longword aligned, i.e. its address must be divisible by 4

success

boolean; FALSE indicates failure, use IoErr() to find out why Info() failed.

Info() makes use of the InfoData structure, as defined in the <dos/dos.h> header file. It looks as follows:

The structure members serve the following purposes:

id_NumSoftErrors (LONG)

File systems which use physical storage media may encounter read errors, or will find that the storage medium was ejected during a read/write operation. The mass storage device driver will report such errors, and the file system will, if necessary, prompt the user to change or put the medium back. The number of errors reported by the device driver are counted and their total number is provided as the id_NumSoftErrors value. The Amiga ROM file system accumulates the number of errors and does not reset the counter when the storage medium is changed. This makes the counter value unhelpful in detecting defects on removable storage media.

id_UnitNumber (LONG)

The unit number comes directly from the file system mount information, indicating which device driver and which device unit was to be used. Not all Amiga file systems are using a specific mass storage device, so this information may not be valid. The unit number is prominently used when displaying error requesters or asking the user to replace a removable storage medium in the indicated drive. This information was relevant when the Amiga only had floppy disk drives attached, unit 0 being understood as referring to the internal DF0 device.

id_DiskState (LONG)

The state of the storage medium used by the file system can be one of the following:

ID_WRITE_PROTECTED

The mass storage medium has a physical write-protection applied. This property can be tested at the device driver level and is commonly associated with floppy disks. Hard disk partitions which share a common drive are rarely write-protected.

The "Info" CLI command shows this state as "Read only".

ID_VALIDATING

The file system detected inconsistencies in the makeup of the on-disk data structures and is both looking for defects, as well as making repairs as needed (if possible). The file system will not be writable until the validation has completed successfully without errors.

The "Info" CLI command shows this state as "Validating".

ID_VALIDATED

This is the default state of a file system which permits both read and write access.

The "Info" CLI command shows this state as "Read/Write".

Note:

The disk state information is relevant only if there is a storage medium present in the drive which the file system can access.

id_NumBlocks (LONG)

see next.

id_NumBlocksUsed (LONG)

These figures represent the total storage capacity as well as how much of this capacity has already been put to use by the file system.

While you can expect useful information from file systems which make use of mass storage devices with their capacity corresponding to actual storage blocks, ram-handler will report that it is always full. You should be prepared to handle this anomaly correctly.

Note:

The file system may not report how many blocks are used for its own data structures in support of storing the metadata and data. Generally, you should not expect the numbers reported to accurately represent the state of the file system device. It should be broadly correct, but nothing more.

The file system may report itself as complete full or completely empty. It may also report a total capacity of 0 blocks. You should be prepared to handle these states robustly and without crashing because of a division by zero error.

id_BytesPerBlock (LONG)

This member provides the information to turn the id_NumBlocks and id_NumBlocksUsed values into the respective number of bytes for the capacity and how much of it has been used already.

The number of bytes per block is not necessarily a number such as 512, as was the case for most mass storage devices available in the 1980'ies and early 1990'ies. You can expect CD-ROMs and removable magnetic media to feature different block sizes, e.g. 2048.

The file system may not report the physical block size, but the logical block size, i.e. multiple sectors can be combined into a larger block.

The Amiga ROM file system used for floppy disks will report the actual "payload size" of the block, which is 488 bytes, instead of the physical block size of 512 bytes. The difference between these two is in the checksum and data recovery information which is stored along with the file data.

Generally, you should not expect the id_BytesPerBlock value to reflect the parameters of the underlying storage hardware. This is certainly true for ram-handler which, as a rule, neither reports its capacity, nor how much memory it uses, nor how these figures translate into a block size accurately.

id_DiskType (LONG)

Amiga file systems tend to identify themselves through a signature value, such as "DOS\0" which is what the Amiga ROM file system would store as the first four bytes in the first block of a formatted floppy disk. This signature information is translated into a 32-bit integer value which either stands for a specific type of file system being used, or for the file system state.

The file system can report the following states:

ID_NO_DISK_PRESENT

No storage medium is present, or the file system cannot detect it.

ID_UNREADABLE_DISK

The on-disk data structures are damaged, or no such data structures can be found.

ID_NOT_REALLY_DOS

Storage medium is present and readable, but its type is not recognized by the file system. This is typical for floppy disks which are bootable but do not make use of the Amiga operating system beyond loading and then executing the boot block code.

The file system may recognize a special kind of disk signature which it will report:

ID_KICKSTART_DISK

This disk is expected to contain an Amiga ROM operating system image which may be loaded into memory. This is a so-called "Kickstart disk" as used by the Amiga 1000 or perhaps even a "SuperKickstart disk" as used by some Amiga 3000 models.

Beyond these states and disk type information, there are well-defined file system signatures which indicate what data structure format is used on the medium. These signatures are not limited to the following list, though:

• ID_DOS_DISK
  
  
• ID_FFS_DISK
  
  
• ID_INTER_DOS_DISK
  
  
• ID_INTER_FFS_DISK
  
  
• ID_FASTDIR_DOS_DISK
  
  
• ID_FASTDIR_FFS_DISK
  
  
• ID_LONG_DOS_DISK
  
  
• ID_LONG_FFS_DISK
  
  

Note:

The Amiga ROM file system cannot indicate the difference between a disk state and the equivalent signature information stored on the first block of a volume. Hence, if a disk contains the text "BAD\0" in the first four characters of its first block, then the disk "state" will be reported as ID_UNREADABLE_DISK (== 'BAD\0').

The same misidentification of the data stored in the first four characters of the first block happens for "\xff\xff\xff\xff" which will be identified as ID_NO_DISK_PRESENT, in spite of the storage medium being present.

id_VolumeNode (BPTR)

If there is a storage medium present, then this member will contain a BCPL pointer (BPTR) to the "volume node" associated with the disk's contents.

A "volume node" is a data structure known as 'struct DeviceList', which is defined in the <dos/dos.h> header file. A "volume node" persists even if the storage medium is ejected from the mass storage device which the file system manages. Accessing a volume whose storage medium has been ejected will make the file system prompt the user to insert it again.

The id_VolumeNode member can be NULL if there is no storage medium present in the storage device managed by the file system.

Note:

Do not trust the id_VolumeNode information to be at all times consistent or valid. By the time you might want to put it to use, it may no longer refer to a valid data structure in memory.

id_InUse (LONG)

The contents of this member indicate whether the file system has locks or files in active use. If no locks or files are in use, id_InUse will be zero. Otherwise, it will be non-zero.

Note:

The contents of the id_InUse member are at best a snapshot of the state of the file system as it was when Info() was called. Its usefulness may be very limited.

The emphasis on insuring that the InfoData pointer must be longword aligned is profound. Do not take this lightly. It is easy to overlook this requirement and then face the consequences of memory corruption and worse.

Use AllocMem(sizeof(struct InfoData), MEMF_ANY|MEMF_PUBLIC) to allocate memory for the infodata pointer which will be longword aligned. Use FreeMem(infodata, sizeof(struct InfoData)) when you no longer need it.

exec.library/AllocMem, exec.library/FreeMem, IoErr()