Partition

Version:1.0
Status:Beta
Date:May 2004
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 2004. All rights reserved.



Description

The Partition module provides support for the analysis and modification of hard disk partition tables. Before attempting to use the functions provided by this module, we recommend that you research publicly available documentation on hard disk partitioning. This is important if you intend to manipulate the partition table of the hard disk, which can potentially damage your drive information if not done correctly.

The Partition module analyses the structure of all the user's hard disks the moment that it is opened for the first time. The GetPartitionDisks() function can then be called to get a structural overview of the hard disks and their partitions.

The Partition module is only available in the commercial and Linux versions of Athene.

Function Index
CreatePartition  Returns an array of detected hard disks.
DeletePartition  Deletes a partition and its content from the partition table.
GetPartitionDisks  Returns an array of detected hard disks.
RebootPartitions  Returns TRUE if the only way to resync the partition table is through a system reboot.
TranslatePartitionCode  Translate a partition code value to a human readable string.
TranslatePartitionFS  Converts a filesystem ID into a human-readable string.
WritePartitionTable  Writes a disk's partition table to the hard disk.

 

Function:CreatePartition()
Short:Returns an array of detected hard disks.
Synopsis:ERROR CreatePartition(struct Partition *Partition, ULONG Sectors, LONG FileSystem)
Arguments:
Partition  Reference to a partition node inside a disk, must be marked as empty space.
Sectors  The size of the partition in sectors. The size will be truncated to fit the disk geometry.
FileSystem  The filesystem code to set for the new partition (refer TranslatePartitionFS()). This is an indicator only - you still need to format the partition afterwards.

New partitions can be created on a hard disk by scanning a disk for empty regions and calling CreatePartition() to allocate new partition space. To find an empty disk region, call GetPartitionDisks() and scan the available disks for a partition marked as empty (the PTYPE_FREESPACE flag will be set in the Flags field of empty partitions). Call CreatePartition() with a pointer to the empty partition and set the Sectors argument to indicate how large the partition should be (one sector equals 512 bytes). The FileSystem argument needs to be set to a file system code, as listed in the TranslatePartitionFS() function.

If this function succeeds, the change to the disk structure is immediate. The disk structure will be re-scanned and the partition structures will be rebuilt from scratch irrespective of whether or not the call succeeds. The operating system may not be able to update its view of the new disk structure - if this is the case, the RebootPartitions() function will return a value of TRUE.

If you would like to create a new partition at an offset within empty space (e.g. creating a 10 GB partition at the end of a 30 GB drive) then you can change the Sector field of the empty Partition structure before calling this function.

There is a limit of 4 primary/extended partitions to a disk. If creating a new partition inside free space requires a 5th partition entry, the error code ERR_ArrayFull is returned.

Result
ERR_Okay  The partition was successfully created.
ERR_Args  Invalid arguments detected.
ERR_ArrayFull  The maximum number of primary partitions has been reached.
ERR_OutOfSpace  The Partition structure that you referred to is not an empty space.
ERR_OpenFile  The hard disk partition table could not be opened.
ERR_SanityFailure  A sanity check was failed before the partition table was written.
ERR_Seek  Seeking to a new sector position in the hard disk failed.

Function:DeletePartition()
Short:Deletes a partition and its content from the partition table.
Arguments:
Partition  Reference to the partition that you want to delete.

A partition can be deleted from a disk by calling the DeletePartition() function. If this function succeeds, the change to the disk structure is immediate.

After deleting a partition, the partition table will be re-read from scratch. This will invalidate all existing partition structures and replace them with freshly allocated structures. The addresses of the main disk structures will remain intact.

The operating system may not be able to update its view of the altered disk structure - if this is the case, the RebootPartitions() function will return a value of TRUE.

Result
ERR_Okay  The partition was deleted.
ERR_Args  The Partition argument was not specified.
ERR_OpenFile  The hard disk partition table could not be opened.
ERR_SanityFailure  A sanity check was failed before the partition table was written.
ERR_Seek  Seeking to a new sector position in the hard disk failed.

Function:GetPartitionDisks()
Short:Returns an array of detected hard disks.
Synopsis:struct PartitionDisk * GetPartitionDisks(void)

Returns a pointer to a chain of disk structures that represent the hard disks connected to a machine. The PartitionDisk structure is arranged as follows:

FieldDescription
struct PartitionDisk *NextPointer to the next hard disk.
struct Partition *PartitionPointer to the first partition of the hard disk.
STRING DeviceThe file system device path, e.g. "/dev/hda".
STRING ModelThe drive model.
ULONG SizeSize of the disk, measured in 512-byte sectors.
ULONG HeadsDrive geometry - heads.
ULONG CylindersDrive geometry - cylinders.
ULONG SectorsDrive geometry - sectors per track.
UBYTE MBR[512]The master boot record (first sector of the drive).

The Partition structure is arranged as follows:

FieldDescription
struct Partition *NextReference to the next partition on the disk.
struct PartitionDisk *DiskReference to the parent disk structure.
STRING DeviceThe partition device name, e.g. "/dev/hda1".
STRING FileSystemFile system human-readable string description.
LONG FSTypeFSTYPE flag indicating the detected file system.
WORD NumberSequential identifier for the partition.
WORD FlagsPTYPE flags - see flag descriptions.
ULONG SectorStarting position on the disk, in 512-byte sectors.
UBYTE Label[32]File system volume label. Note that not all file systems support labels.
ULONG EndSectorSector at which the partition ends.
ULONG OffsetFor logical partitions - indicates where the partition actually starts (usually 1 track away).

Available PTYPE flags are as follows:

FlagDescription
FREESPACEIndicates that the partition structure represents free space that you can use to create a real partition.
EXTENDEDIndicates an extended partition (a partition that contains logical partitions).
LOGICALThis is a logical partition that is contained by an extended partition.
PRIMARYThe partition is 'primary' - i.e. is one of the four partitions registered in the first hard disk sector.
ACTIVEThe partition is bootable. Matters only if using a DOS-based MBR.

Result
This function returns a PartitionDisk structure, or NULL if no disks are available.


Function:RebootPartitions()
Short:Returns TRUE if the only way to resync the partition table is through a system reboot.
Synopsis:LONG RebootPartitions(void)

If the partition tables of one or more disks have been updated and the operating system cannot recognise the changes, this function returns TRUE. In doing so, it is recommending a reboot of the machine so that the operating system can detect the partition table changes.

Result
Returns TRUE if a reboot is recommended.


Function:TranslatePartitionCode()
Short:Translate a partition code value to a human readable string.
Synopsis:STRING TranslatePartitionCode(LONG Type)
Arguments:
Type  The partition code.

Converts a partition code into a human readable string.

Result
Returns a string that represents the partition code.


Function:TranslatePartitionFS()
Short:Converts a filesystem ID into a human-readable string.
Synopsis:STRING TranslatePartitionFS(LONG FileSystem)

Returns a short human-readable string that describes the given filesystem ID. Known file system identifiers are (preceded with the FSTYPE prefix):

FieldDescription
UNKNOWNThe file system is not recognised, or the partition is unformatted.
EXT2Ext 2 Linux file system.
EXT3Ext 3 Linux file system.
SWAPDedicated swap partition.
REISERFSReiser file system.
JFSJFS.
XFSXFS.
FAT32Microsoft Windows FAT 32 file system.
FAT16Microsoft DOS FAT 16 file system.
NTFSMicrosoft Windows NTFS file system.
HFSHFS.
UFS_SUNUFS (SUN).
UFS_HPUFS (HP).
EXT_PARTITIONExtended partition with no file system.
FREESPACENot a real partition - indicates unused hard disk space.

Result
Returns a human-readable string for the given file system ID. If the file system ID is not registered, an "Unknown" string is returned.


Function:WritePartitionTable()
Short:Writes a disk's partition table to the hard disk.
Synopsis:ERROR WritePartitionTable(struct PartitionDisk *Disk)
Arguments:
Disk  Pointer to the disk structure that you want to write to the hard disk.

Call this function to write a disk structure and its partition chain directly to the hard disk. By doing so, any existing partition information on the hard disk will be lost (replaced by the new disk information).

Result
ERR_Okay  The partition table was written successfully.
ERR_Args  The Disk argument was not specified.
ERR_OpenFile  The hard disk partition table could not be opened.
ERR_SanityFailure  A sanity check was failed before the partition table was written.
ERR_Seek  Seeking to a new sector position in the hard disk failed.