.TH DISKS 2.SH NAMEdisks: Disk, PCpart, readn, chstext \- generic disk and partition interface.SH SYNOPSIS.EXinclude "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 Disksprovides a simple way to gatherand use information about .IR floppy (3)and.IR sd (3)disks and disk partitions,as well as plain files..PP.B Initmust be called before invoking any other operations of the module.PP.B Disk.openopens.I fileand returns a reference to a.B Diskvalue to represent the disk..I Modeshould be either.BR Sys->OREADor.BR Sys->ORDWRto establish the open mode..B Openalways opens.I filefor reading and stores that file descriptor inthe element.IR fd .If the mode is not.BR Sys->OREAD ,.I opendiskalso opens.I filefor writing and stores that file descriptor in.BR wfd .The two file descriptors are kept separate tohelp prevent accidents.If.I noctlis not set, .B openlooks for a.B ctlfile in the same directory as thedisk file;if it finds one, it declaresthe disk to bean.IR sd (3)device,setting.B dtypeto\f5"sd"\fP.If the passed.I fileis 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 bea floppy disk, of type\f5"floppy"\fP.If either controlfile is found, it is opened for readingand writing, and the resulting file descriptoris saved as .BR ctlfd .Otherwise the returned diskhas type\f5"file"\fP..PP.B Openthen 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 openreads the sector size from the controlfile and stores it in .BR secsize ;otherwise the sector size is assumed to be 512,as is the case for floppy disks..B Openstores the disk size measured in sectors in.BR secs ..PPIf the disk is an.IR sd (3)partition, .B openparses thecontrolfile to find the partition's offsetwithin its disk;otherwise it sets.B offsetto zero.If the disk is an ATA disk,.B openreadsthe disk geometry (number of cylinders, heads, and sectors)from the .B geometryline in the.I sdcontrol file;otherwise it sets these to zero as well..B Nameis initialized with the base name ofthe disk partition, and is useful for forming messages to the.I sdcontrol file..B Prefixis set to the original.I filename without the .B namesuffix..PPThe IBM PC BIOS interface allocates10 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 simpleanymore, but to keep the interface useful,modern disks and BIOSes present geometriesthat still fit within these constraints.These numbers are still used when partitioningand formatting disks..B Openemploys a number of heuristics to discover thissupposed geometry and store it in the.BR c ,.BR h ,and.B selements of.BR Disk .Disk offsets in partition tables andin FAT descriptors are stored in a formdependent upon these numbers, so.I opendiskworks hard to report numbers thatagree with those used by other operatingsystems; the numbers bear little or no resemblanceto reality..PP.B Chssrcnames 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 Readnattempts to read exactly.I nbytes from file.I fdinto.IR buf ,using as many.IR sys-read (2)calls as required.It helps insulate a program from any peculiar underlying IO boundariesof a device.It returns less than.I nonly if end-of-file is reached.It returns -1 if the first read fails..PPThe PC BIOS and operating systems support an arcane system of disk partitions:a partition table at the end of the master boot recorddefines up to four partitions.One (or perhaps more) of those can be an extended partitionthat heads a chain (or perhaps roots a tree) of partition tableselsewhere on disk, allowing many more than four partitions in all..B Disksrepresents a partition table entry by a value of type.BR PCpart .It provides the following operations and values:.TP.B activeHas the value.B Disks->Activeif it is bootable, and zero otherwise..TP.B ptypePartition type;.B Disks->Type9is used by Plan 9 and Inferno (see.IR prep (8))..TP.B baseAddress 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 offsetBlock address of the start of the partition relative to the.BR base ..TP.B sizeSize of the partition in sectors..TP.BI extract( "a, d" )Extracts the relevant data from an array of bytes.I acontaining a PC-format partition table entry on.B Disk.IR d ,and returns a.B PCpartvalue that represents the partition..TP.IB pc .bytes( d )Return an array of bytes containing the PC-format partitiontable entry corresponding to.IR pc .It will always be.B TentrySizebytes long..PPSeveral other values are defined here for convenience:.TPActiveValue for.B PCpart.activeif the partition is bootable..TP.B Type9Partition type used by Plan 9 and Inferno..TP.B ToffsetOffset (in bytes) of the partition table in a master boot record or extended partition start sector..TP.B TentrySizeSize in bytes of a partition table entry..TP.B NTentryNumber of table entries..TP.B Magic0.PD0.TP.B Magic1Each sector containing a partition table should end withthese two bytes (a master boot record must end with them)..PP.B Chstexttakes a 3-byte array containing the packed cylinder/head/sectorrepresentation of a disk address and returns the corresponding textin 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)