ref: 02ac617541ca1a7bf82b1615fb5a58235469b5d3
dir: /man/2/disks/
.TH DISKS 2 .SH NAME disks: Disk, PCpart, readn, chstext \- generic disk and partition interface .SH SYNOPSIS .EX include "disks.m"; disks := load Disks Disks->PATH; Disk: adt { prefix: string; # prefix before partition name part: string; # partition name (nil if not partition) fd: ref Sys->FD; wfd: ref Sys->FD; ctlfd: ref Sys->FD; rdonly: int; # non-zero if readonly dtype: string; # device type secs: big; # number of sectors in device or partition secsize: int; # device's sector size size: big; # size of device or partition offset: big; # within larger disk, perhaps width: int; # of disk size in bytes as decimal string c: int; # geometry: cyl, head, sectors h: int; s: int; chssrc: string; # source of c/h/s values open: fn(f: string, mode: int, noctl: int): ref Disk; }; PCpart: adt { active: int; # Active or 0 ptype: int; base: big; # base block address offset: big; # block offset from base to partition size: big; # in sectors extract: fn(a: array of byte, d: ref Disk): PCpart; bytes: fn(p: self PCpart, d: ref Disk): array of byte; }; init: fn(); readn: fn(fd: ref Sys->FD, buf: array of byte, n: int): int; chstext: fn(p: array of byte): string; .EE .SH DESCRIPTION .B Disks provides a simple way to gather and use information about .IR floppy (3) and .IR sd (3) disks and disk partitions, as well as plain files. .PP .B Init must be called before invoking any other operations of the module .PP .B Disk.open opens .I file and returns a reference to a .B Disk value to represent the disk. .I Mode should be either .BR Sys->OREAD or .BR Sys->ORDWR to establish the open mode. .B Open always opens .I file for reading and stores that file descriptor in the element .IR fd . If the mode is not .BR Sys->OREAD , .I opendisk also opens .I file for writing and stores that file descriptor in .BR wfd . The two file descriptors are kept separate to help prevent accidents. If .I noctl is not set, .B open looks for a .B ctl file in the same directory as the disk file; if it finds one, it declares the disk to be an .IR sd (3) device, setting .B dtype to \f5"sd"\fP. If the passed .I file is named .BI fd n disk \fR, it looks for a file .BI fd n ctl \fR, and if it finds that, declares the disk to be a floppy disk, of type \f5"floppy"\fP. If either control file is found, it is opened for reading and writing, and the resulting file descriptor is saved as .BR ctlfd . Otherwise the returned disk has type \f5"file"\fP. .PP .B Open then stores the file's length (as given by .IR sys-stat (2)) in .BR size . If the disk is an .IR sd (3) partition, .B open reads the sector size from the control file and stores it in .BR secsize ; otherwise the sector size is assumed to be 512, as is the case for floppy disks. .B Open stores the disk size measured in sectors in .BR secs . .PP If the disk is an .IR sd (3) partition, .B open parses the control file to find the partition's offset within its disk; otherwise it sets .B offset to zero. If the disk is an ATA disk, .B open reads the disk geometry (number of cylinders, heads, and sectors) from the .B geometry line in the .I sd control file; otherwise it sets these to zero as well. .B Name is initialized with the base name of the disk partition, and is useful for forming messages to the .I sd control file. .B Prefix is set to the original .I file name without the .B name suffix. .PP The IBM PC BIOS interface allocates 10 bits for the number of cylinders, 8 for the number of heads, and 6 for the number of sectors per track. Disk geometries are not quite so simple anymore, but to keep the interface useful, modern disks and BIOSes present geometries that still fit within these constraints. These numbers are still used when partitioning and formatting disks. .B Open employs a number of heuristics to discover this supposed geometry and store it in the .BR c , .BR h , and .B s elements of .BR Disk . Disk offsets in partition tables and in FAT descriptors are stored in a form dependent upon these numbers, so .I opendisk works hard to report numbers that agree with those used by other operating systems; the numbers bear little or no resemblance to reality. .PP .B Chssrc names the source of the geometry values: .B disk (values returned by disk itself); .B part (values stored in PC partition table); or .B guess (calculated by module's heuristics). .PP .B Readn attempts to read exactly .I n bytes from file .I fd into .IR buf , using as many .IR sys-read (2) calls as required. It helps insulate a program from any peculiar underlying IO boundaries of a device. It returns less than .I n only if end-of-file is reached. It returns -1 if the first read fails. .PP The PC BIOS and operating systems support an arcane system of disk partitions: a partition table at the end of the master boot record defines up to four partitions. One (or perhaps more) of those can be an extended partition that heads a chain (or perhaps roots a tree) of partition tables elsewhere on disk, allowing many more than four partitions in all. .B Disks represents a partition table entry by a value of type .BR PCpart . It provides the following operations and values: .TP .B active Has the value .B Disks->Active if it is bootable, and zero otherwise. .TP .B ptype Partition type; .B Disks->Type9 is used by Plan 9 and Inferno (see .IR prep (8)). .TP .B base Address of the extended partition that started the chain (or rooted the tree) containing this partition. Zero for primary partitions defined by the master boot record. .TP .B offset Block address of the start of the partition relative to the .BR base . .TP .B size Size of the partition in sectors. .TP .BI extract( "a, d" ) Extracts the relevant data from an array of bytes .I a containing a PC-format partition table entry on .B Disk .IR d , and returns a .B PCpart value that represents the partition. .TP .IB pc .bytes( d ) Return an array of bytes containing the PC-format partition table entry corresponding to .IR pc . It will always be .B TentrySize bytes long. .PP Several other values are defined here for convenience: .TP Active Value for .B PCpart.active if the partition is bootable. .TP .B Type9 Partition type used by Plan 9 and Inferno. .TP .B Toffset Offset (in bytes) of the partition table in a master boot record or extended partition start sector. .TP .B TentrySize Size in bytes of a partition table entry. .TP .B NTentry Number of table entries. .TP .B Magic0 .PD0 .TP .B Magic1 Each sector containing a partition table should end with these two bytes (a master boot record must end with them). .PP .B Chstext takes a 3-byte array containing the packed cylinder/head/sector representation of a disk address and returns the corresponding text in the form .BI c / h / s. .SH SOURCE .B /appl/lib/disks.b .SH SEE ALSO .IR scsiio (2), .IR floppy (3), .IR sd (3), .IR prep (3)