1 <!doctype linuxdoc system>
4 <title>Diskette Sector I/O Routines
5 <author>Christian Groessler, <htmlurl url="mailto:cpg@aladdin.de" name="cpg@aladdin.de">
9 The cc65 library provides functions to read and write raw disk sectors.
10 Include the dio.h header file to get the necessary definitions.
13 <!-- Table of contents -->
16 <!-- Begin the document -->
18 <sect>Opening the disk for low level I/O<p>
20 Prior to using these functions a handle to the drive has to be obtained. This
21 is done with the <tt>dio_open</tt> function. After use, the handle should be
22 released with the <tt>dio_close</tt> function.
25 dhandle_t __fastcall__ dio_open (driveid_t drive_id);
28 The <tt>drive_id</tt> specifies the drive to access, with 0 being the first
29 disk drive, 1 the second, and so on.
32 unsigned char __fastcall__ dio_close (dhandle_t handle);
35 Closes a handle obtained by <tt>dio_open</tt>. Returns status code.
38 <sect>Reading and writing sectors<p>
40 The read and write functions are:
43 unsigned char __fastcall__ dio_read (dhandle_t handle,
48 This function will read the sector specified by sect_num into the memory
52 unsigned char __fastcall__ dio_write (dhandle_t handle,
57 This function will write the memory contents at buffer to the sector specified
58 by <tt>sect_num</tt>. No verify is performed.
61 unsigned char __fastcall__ dio_write_verify (dhandle_t handle,
66 This function will write the memory contents at buffer to the sector specified
67 by <tt>sect_num</tt>. A verification is performed.
70 All these functions will return 0 for success and an OS specific error code in
75 <sect>Converting sector numbers<p>
77 Since the read and write functions expect a sector number, for systems where
78 the sectors aren't addressed by a logical sector number (e.g. CBM drives),
79 there are 2 conversion functions. One of them converts a logical sector number
80 to a head/track/sector triple. The other conversion function works the other
84 unsigned char __fastcall__ dio_phys_to_log (dhandle_t handle,
85 const dio_phys_pos *physpos,
89 This function converts track/head/sector to logical sector number.
92 unsigned char __fastcall__ dio_log_to_phys(_dhandle_t handle,
93 const _sectnum_t *sectnum,
94 dio_phys_pos *physpos);
97 This function converts a logical sector number to track/head/sector notation.
100 Note, that on systems which natively use logical sector numbers (e.g. Atari),
101 the conversion functions are dummies. They ignore head/track
102 (<tt>dio_phys_to_log</tt>) or return them as zero (<tt>dio_log_to_phys</tt>).
103 The logical sector number is returned as physical sector and vice versa.