1 .TH DISK 3
2 .SH NAME
3 opendisk, Disk \- generic disk device interface
4 .SH SYNOPSIS
5 .nf
6 .ft L
7 #include <u.h>
8 #include <libc.h>
9 #include <disk.h>
10 .ft
11 .PP
12 .ft L
13 typedef struct Disk {
14 	char *prefix;
15 	char part[NAMELEN];
16 	int fd, wfd, ctlfd, rdonly;
17 	int type;
18 	vlong secs, secsize, size, offset;
19 	int c, h, s;
20 } Disk;
21 .ft
22 .PP
23 .B
24 Disk* opendisk(char *file, int rdonly, int noctl)
25 .SH DESCRIPTION
26 These routines provide a simple way to gather
27 and use information about 
28 disks and disk partitions,
29 as well as plain files.
30 .PP
31 .I Opendisk
32 opens
33 .I file
34 for reading and stores the file descriptor in
35 the 
36 .B fd
37 field of the
38 .B Disk
39 structure.
40 If 
41 .I rdonly
42 is not set, 
43 .I opendisk
44 also opens
45 .I file
46 for writing and stores that file descriptor in
47 .BR wfd .
48 The two file descriptors are kept separate to
49 help prevent accidents.
50 .PP
51 If
52 .I noctl
53 is not set, 
54 .I opendisk
55 looks for a
56 .B ctl
57 file in the same directory as the
58 disk file;
59 if it finds one, it declares
60 the disk to be
61 an
62 .I sd
63 device,
64 setting the
65 .B type
66 field in the
67 .B Disk
68 structure
69 to
70 .BR Tsd .
71 If the passed
72 .I file
73 is named
74 .BI fd n disk \fR,
75 it looks for a file
76 .BI fd n ctl \fR,
77 and if it finds that,
78 declares the disk to be
79 a floppy disk, of type
80 .BR Tfloppy .
81 If either
82 control
83 file is found, it is opened for reading
84 and writing, and the resulting file descriptor
85 is saved as 
86 .BR ctlfd .
87 Otherwise the returned disk
88 has type
89 .BR Tfile .
90 .PP
91 .I Opendisk
92 then stats the file and stores its length in
93 .BR size .
94 If the disk is an
95 .I sd
96 partition, 
97 .I opendisk
98 reads the sector size from the
99 control
100 file and stores it in 
101 .BR secsize ;
102 otherwise the sector size is assumed to be 512,
103 as is the case for floppy disks.
104 .I Opendisk
105 then stores the disk size measured in sectors in
106 .BR secs .
107 .PP
108 If the disk is an
109 .I sd
110 partition, 
111 .I opendisk 
112 parses the
113 control
114 file to find the partition's offset
115 within its disk;
116 otherwise it sets
117 .B offset
118 to zero.
119 If the disk is an ATA disk,
120 .I opendisk
121 reads
122 the disk geometry (number of cylinders, heads, and sectors)
123 from the 
124 .B geometry
125 line in the
126 .I sd
127 control file;
128 otherwise it sets these to zero as well.
129 .B Name
130 is initialized with the base name of
131 the disk partition, and is useful for forming messages to the
132 .I sd
133 control file.
134 .B Prefix
135 is set to the passed filename without
136 the 
137 .B name
138 suffix.
139 .PP
140 The IBM PC BIOS interface allocates
141 10 bits for the number of cylinders, 8 for 
142 the number of heads, and 6 for the number of sectors per track.
143 Disk geometries are not quite so simple
144 anymore, but to keep the interface useful,
145 modern disks and BIOSes present geometries
146 that still fit within these constraints.
147 These numbers are still used when partitioning
148 and formatting disks.
149 .I Opendisk
150 employs a number of heuristics to discover this
151 supposed geometry and store it in the
152 .BR c ,
153 .BR h ,
154 and
155 .B s
156 fields.
157 Disk offsets in partition tables and
158 in FAT descriptors are stored in a form
159 dependent upon these numbers, so
160 .I opendisk
161 works hard to report numbers that
162 agree with those used by other operating
163 systems; the numbers bear little or no resemblance
164 to reality.
165 .SH SOURCE
166 .B /usr/local/plan9/src/libdisk/disk.c
167 .SH SEE ALSO
168 Plan 9's
169 \fIfloppy\fR(3) and \fIsd\fR(3)
170 .SH BUGS
171 Disks on Unix systems do not present the interface
172 that 
173 .I opendisk
174 expects, so
175 .I opendisk
176 will give them type
177 .BR Tfile .