1 <!doctype linuxdoc system>
4 <title>Diskette Sector I/O Routines
5 <author><url url="mailto:chris@groessler.org" name="Christian Groessler">
8 The cc65 library provides functions to read and write raw disk sectors.
9 Include the dio.h header file to get the necessary definitions.
12 <!-- Table of contents -->
15 <!-- Begin the document -->
17 <sect>Opening the disk for low level I/O<p>
19 Prior to using these functions a handle to the device has to be obtained. This
20 is done with the <tt>dio_open</tt> function. After use, the handle should be
21 released with the <tt>dio_close</tt> function.
24 dhandle_t __fastcall__ dio_open (unsigned char device);
27 The <tt>device</tt> specifies the device to access.
30 unsigned char __fastcall__ dio_close (dhandle_t handle);
33 Closes a handle obtained by <tt>dio_open</tt>. Returns status code.
36 <sect>Reading and writing sectors<p>
38 The read and write functions are:
41 unsigned char __fastcall__ dio_read (dhandle_t handle,
46 This function will read the sector specified by <tt>sect_num</tt> into the memory
50 unsigned char __fastcall__ dio_write (dhandle_t handle,
55 This function will write the memory contents at buffer to the sector specified
56 by <tt>sect_num</tt>. No verify is performed.
59 unsigned char __fastcall__ dio_write_verify (dhandle_t handle,
64 This function will write the memory contents at buffer to the sector specified
65 by <tt>sect_num</tt>. A verification is performed.
68 Use the <tt><ref name="dio_query_sectsize" id="sectsizecount"></tt> function to query
69 the size of a sector and the <tt><ref name="dio_query_sectcount" id="sectsizecount"></tt>
70 function to query the number of available sectors.
73 All these functions will return 0 for success and an OS specific error code in
77 <sect>Querying sector size and count<label id="sectsizecount"><p>
79 Some systems support multiple diskette formats which have different sector sizes
80 and/or different sector counts.
83 The following function returns the sector size of the currently inserted disk:
86 unsigned __fastcall__ dio_query_sectsize (dhandle_t handle);
89 On the Atari platform, the sector size is handled specially. Please refer
90 to the DIO section in the <url url="atari.html" name="Atari-specific
91 platform documentation">.
94 The following function returns the sector count of the currently inserted disk:
97 unsigned __fastcall__ dio_query_sectcount (dhandle_t handle);
100 <sect>Converting sector numbers<p>
102 Since the read and write functions expect a sector number, for systems where
103 the sectors aren't addressed by a logical sector number (e.g. CBM devices),
104 there are 2 conversion functions. One of them converts a logical sector number
105 to a head/track/sector triple. The other conversion function works the other
109 unsigned char __fastcall__ dio_phys_to_log (dhandle_t handle,
110 const dio_phys_pos *physpos,
114 This function converts track/head/sector to logical sector number.
117 unsigned char __fastcall__ dio_log_to_phys (dhandle_t handle,
118 const unsigned *sectnum,
119 dio_phys_pos *physpos);
122 This function converts a logical sector number to track/head/sector notation.
125 Note, that on systems which natively use logical sector numbers (e.g. Atari),
126 the conversion functions are dummies. They ignore head/track
127 (<tt>dio_phys_to_log</tt>) or return them as zero (<tt>dio_log_to_phys</tt>).
128 The logical sector number is returned as physical sector and vice versa.