]> git.sur5r.net Git - cc65/blob - doc/dio.sgml
add "invalid parameter" error code -- contributed by Stefan Haubenthal
[cc65] / doc / dio.sgml
1 <!doctype linuxdoc system>
2
3 <article>
4 <title>Diskette Sector I/O Routines
5 <author>Christian Groessler, <htmlurl url="mailto:chris@groessler.org" name="chris@groessler.org">
6 <date>20-Feb-2005
7
8 <abstract>
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.
11 </abstract>
12
13 <!-- Table of contents -->
14 <toc>
15
16 <!-- Begin the document -->
17
18 <sect>Opening the disk for low level I/O<p>
19
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.
23
24 <tscreen><verb>
25     dhandle_t __fastcall__ dio_open (driveid_t drive_id);
26 </verb></tscreen>
27
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.
30
31 <tscreen><verb>
32     unsigned char __fastcall__ dio_close (dhandle_t handle);
33 </verb></tscreen>
34
35 Closes a handle obtained by <tt>dio_open</tt>. Returns status code.
36 <p>
37
38 <sect>Reading and writing sectors<p>
39
40 The read and write functions are:
41
42 <tscreen><verb>
43     unsigned char __fastcall__ dio_read (dhandle_t handle,
44                                          sectnum_t sect_num,
45                                          void *buffer);
46 </verb></tscreen>
47
48 This function will read the sector specified by <tt>sect_num</tt> into the memory
49 location at buffer.
50
51 <tscreen><verb>
52     unsigned char __fastcall__ dio_write (dhandle_t handle,
53                                           sectnum_t sect_num,
54                                           const void *buffer);
55 </verb></tscreen>
56
57 This function will write the memory contents at buffer to the sector specified
58 by <tt>sect_num</tt>. No verify is performed.
59
60 <tscreen><verb>
61     unsigned char __fastcall__ dio_write_verify (dhandle_t handle,
62                                                  sectnum_t sect_num,
63                                                  const void *buffer);
64 </verb></tscreen>
65
66 This function will write the memory contents at buffer to the sector specified
67 by <tt>sect_num</tt>. A verification is performed.
68 <p>
69
70 Use the <tt><ref name="dio_query_sectsize" id="sectsizecount"></tt> function to query
71 the size of a sector and the <tt><ref name="dio_query_sectcount" id="sectsizecount"></tt>
72 function to query the number of available sectors.
73 <p>
74
75 All these functions will return 0 for success and an OS specific error code in
76 case of failure.
77 <p>
78
79 <sect>Querying sector size and count<label id="sectsizecount"><p>
80
81 Some systems support multiple diskette formats which have different sector sizes
82 and/or different sector counts.
83 <p>
84
85 The following function returns the sector size of the currently inserted disk:
86
87 <tscreen><verb>
88     sectsize_t __fastcall__ dio_query_sectsize (dhandle_t handle);
89 </verb></tscreen>
90
91 On the Atari platform, the sector size is handled specially. Please refer
92 to the DIO section in the <htmlurl url="atari.html" name="Atari">
93 specific platform documentation.
94 <p>
95
96 The following function returns the sector count of the currently inserted disk:
97
98 <tscreen><verb>
99     sectnum_t __fastcall__ dio_query_sectcount (dhandle_t handle);
100 </verb></tscreen>
101
102 <sect>Converting sector numbers<p>
103
104 Since the read and write functions expect a sector number, for systems where
105 the sectors aren't addressed by a logical sector number (e.g. CBM drives),
106 there are 2 conversion functions. One of them converts a logical sector number
107 to a head/track/sector triple. The other conversion function works the other
108 way round.
109
110 <tscreen><verb>
111     unsigned char __fastcall__ dio_phys_to_log (dhandle_t handle,
112                                                 const dio_phys_pos *physpos,
113                                                 sectnum_t *sectnum);
114 </verb></tscreen>
115
116 This function converts track/head/sector to logical sector number.
117
118 <tscreen><verb>
119     unsigned char __fastcall__ dio_log_to_phys (dhandle_t handle,
120                                                 const _sectnum_t *sectnum,
121                                                 dio_phys_pos *physpos);
122 </verb></tscreen>
123
124 This function converts a logical sector number to track/head/sector notation.
125 <p>
126
127 Note, that on systems which natively use logical sector numbers (e.g. Atari),
128 the conversion functions are dummies. They ignore head/track
129 (<tt>dio_phys_to_log</tt>) or return them as zero (<tt>dio_log_to_phys</tt>).
130 The logical sector number is returned as physical sector and vice versa.
131 <p>
132
133
134 </article>
135
136
137