<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<LINK REL="stylesheet" TYPE="text/css" HREF="doc.css">
<META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 0.9.71">
<TITLE>Diskette Sector I/O Routines</TITLE>
</HEAD>
<BODY>
<H1>Diskette Sector I/O Routines</H1>
<H2>
<A HREF="mailto:chris@groessler.org">Christian Groessler</A></H2>
<HR>
<EM>The cc65 library provides functions to read and write raw disk sectors.
Include the dio.h header file to get the necessary definitions.</EM>
<HR>
<P>
<H2><A NAME="toc1">1.</A> <A HREF="dio.html#s1">Opening the disk for low level I/O</A></H2>
<P>
<H2><A NAME="toc2">2.</A> <A HREF="dio.html#s2">Reading and writing sectors</A></H2>
<P>
<H2><A NAME="toc3">3.</A> <A HREF="dio.html#s3">Querying sector size and count</A></H2>
<P>
<H2><A NAME="toc4">4.</A> <A HREF="dio.html#s4">Converting sector numbers</A></H2>
<HR>
<H2><A NAME="s1">1.</A> <A HREF="#toc1">Opening the disk for low level I/O</A></H2>
<P>Prior to using these functions a handle to the device has to be obtained. This
is done with the <CODE>dio_open</CODE> function. After use, the handle should be
released with the <CODE>dio_close</CODE> function.</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
dhandle_t __fastcall__ dio_open (unsigned char device);
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>The <CODE>device</CODE> specifies the device to access.</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
unsigned char __fastcall__ dio_close (dhandle_t handle);
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>Closes a handle obtained by <CODE>dio_open</CODE>. Returns status code.</P>
<H2><A NAME="s2">2.</A> <A HREF="#toc2">Reading and writing sectors</A></H2>
<P>The read and write functions are:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
unsigned char __fastcall__ dio_read (dhandle_t handle,
unsigned sect_num,
void *buffer);
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>This function will read the sector specified by <CODE>sect_num</CODE> into the memory
location at buffer.</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
unsigned char __fastcall__ dio_write (dhandle_t handle,
unsigned sect_num,
const void *buffer);
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>This function will write the memory contents at buffer to the sector specified
by <CODE>sect_num</CODE>. No verify is performed.</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
unsigned char __fastcall__ dio_write_verify (dhandle_t handle,
unsigned sect_num,
const void *buffer);
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>This function will write the memory contents at buffer to the sector specified
by <CODE>sect_num</CODE>. A verification is performed.</P>
<P>Use the <CODE>
<A HREF="#sectsizecount">dio_query_sectsize</A></CODE> function to query
the size of a sector and the <CODE>
<A HREF="#sectsizecount">dio_query_sectcount</A></CODE>
function to query the number of available sectors.</P>
<P>All these functions will return 0 for success and an OS specific error code in
case of failure.</P>
<H2><A NAME="sectsizecount"></A> <A NAME="s3">3.</A> <A HREF="#toc3">Querying sector size and count</A></H2>
<P>Some systems support multiple diskette formats which have different sector sizes
and/or different sector counts.</P>
<P>The following function returns the sector size of the currently inserted disk:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
unsigned __fastcall__ dio_query_sectsize (dhandle_t handle);
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>On the Atari platform, the sector size is handled specially. Please refer
to the DIO section in the
<A HREF="atari.html">Atari-specific platform documentation</A>.</P>
<P>The following function returns the sector count of the currently inserted disk:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
unsigned __fastcall__ dio_query_sectcount (dhandle_t handle);
</PRE>
</CODE></BLOCKQUOTE>
</P>
<H2><A NAME="s4">4.</A> <A HREF="#toc4">Converting sector numbers</A></H2>
<P>Since the read and write functions expect a sector number, for systems where
the sectors aren't addressed by a logical sector number (e.g. CBM devices),
there are 2 conversion functions. One of them converts a logical sector number
to a head/track/sector triple. The other conversion function works the other
way round.</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
unsigned char __fastcall__ dio_phys_to_log (dhandle_t handle,
const dio_phys_pos *physpos,
unsigned *sectnum);
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>This function converts track/head/sector to logical sector number.</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
unsigned char __fastcall__ dio_log_to_phys (dhandle_t handle,
const unsigned *sectnum,
dio_phys_pos *physpos);
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>This function converts a logical sector number to track/head/sector notation.</P>
<P>Note, that on systems which natively use logical sector numbers (e.g. Atari),
the conversion functions are dummies. They ignore head/track
(<CODE>dio_phys_to_log</CODE>) or return them as zero (<CODE>dio_log_to_phys</CODE>).
The logical sector number is returned as physical sector and vice versa.</P>
</BODY>
</HTML>