D_DISK -- A POSIX-like DISK I/O library for non-Unix OSs

NOTES.TXT, 30-Nov-1998

Copyright (C) 1998, Gregg Jennings

See D_DISK.HTM for the library specifications.
See D_DISK.TXT for overview the implementation.
See CHANGELOG.TXT for the latest changes.
See also my DISKLIB library documentation.

I am in the process of converting D_DISK to use DISKLIB (see
http://www.diskwarez.com/disklib.htm for the source code). If
DISKLIB is defined on the command line (see the makefiles) it
will be used.

DISKLIB is more up to date than the sub-directory files here, and
also has a more complete implementation for Windows. The test
applications here (see NOTES.TXT) have been proven for DOS and
Windows 98. The DJGPP version has also not been tested yet.

I will be updating D_DISK for Windows 95/NT and DJGPP soon.


LIBRARY CONTENTS

File            Description

d_disk.c        the main part of the D_DISK library
d_error.c       DOS/BIOS errors to D_E... errors
d_perror.c      display error messages to stderr
d_disk.h        for library/user
d_error.h       D_E... definitions
d_lib.h         for sub-directory code / OS functions
types.h         for sub-directory code / OS typedefs
iface.h         for test program
dos\            directory for DOS (Watcom/Microsoft)
dos\gcc\        directory for DOS (DJGPP)
win32\          directory for WIN32 (Watcom/Microsoft)

Note that if my DISKLIB library is used, the D_DISK sub-directory
contents are not used, except for DISKGET.C, and that the D_DISK
and DISKLIB directories are off of the same base directory.

Also in the D_DISK directory are several test applications. The
number of these applications will grow as I come up with new uses.
Here are a couple examples:

dt.c            a command line (console) library test program
sf.c            save a floppy disk's free data to a file


MAKEFILES

The makefiles are in the OS sub-directories, and are used even if my
DISKLIB library is used instead of the files in the sub-directories.


SUB-DIRECTORY CONTENTS

Note that if my DISKLIB library is used, the D_DISK sub-directory
contents are NOT USED.

The sub-directories are for the OS dependent system calls, as well
as compiler specifics. Each sub-directory has the following files
(with a few exceptions noted):

File            Description

diskget.c       part of D_DISK
dosio.h         DOS data structure definitions
win32.h         Windows stuff (WIN32 only)
ioctl.c         DOS IOCTL calls
free.c          DOS Get Free Space call
getdisk.c       DOS Get Device Parameters
read.c          DOS Absolute Disk Read
write.c         DOS Absolute Disk Write
bios.c          BIOS (INT 13h) calls
edump.c         display DOS error information
rdump.c         display 80x86 registers
dosmem.c        alloc/free DOS (conventional) memory (GCC only)
device.c        Windows device drive calls (WIN32 only)
conio.c         Windows console I/O (WIN32 only)


OS FUNCTION SUMMARY

Note that if my DISKLIB library is used, these files are not used.

                                needs   return  DOS     HDW     LIB
file        function            d_disk  success error   error   error

ioctl.c     dos_ioctl           N       -1      0       (1)     (2)
free.c      disk_free_space     N       -1      0       (1)     n/a
getdisk.c   disk_get_parameters Y       -1      0       (1)     n/a
read.c      disk_read/ext (3)   N       -1      n/a     > 0     n/a
write.c     write_read/ext (3)  N       -1      n/a     > 0     n/a
bios.c      disk_get_physical   N       -1      n/a     > 0     n/a
"           disk_read_p         N       -1      n/a     > 0     n/a

All of the non-void functions return -1 for success, 0 for a DOS
error, or greater than 0 for a BIOS error. This _is_ the best way
(4); otherwise data and more functions would have to be shared
between these functions and those of D_DISK (i.e. for d_errno).

Retrieving error codes for non-success will be done by the D_DISK
function dskerror_to_derrno() for BIOS errors and the standard
CTRL functions (and/or 'errno') for DOS errors.

Notes:  1   hardware errors are trapped by DOS; it's possible that an
            interrupt 24h handler will have to be installed
        2   for DJGPP, dos_ioctl can possibly, although remotely,
            return 0 if out of memory
        3   INT 25h (and 26h) leaves the stack unbalanced--leaves the
            flags pushed. Other DOS RTLs (intdos/int86) fix this, but
            I was unable to verify if the DPMI code that comes with
            DJGPP handles it. This code DOES NOT, though, cause any
            runtime errors, and just stepping over the call shows that
            SP is okay... However, until this can be confirmed, WORRY!

        4   Okay, perhaps it is not. See how things are done in my
            DISKLIB code.


CODING STYLE

I use tab stops of four.

First and most important is that the files are small! Usually
containing just one or perhaps two external functions. Local
functions are used to keep function length (in lines) to a
minimum! This may complicate the makefiles but eases editing,
compiling and debugging immensely.

Secondly is the putting of OS and compiler specific files into
sub-directories! Again this eases editing and debugging. The lack
of hundreds of #ifdef/#endif blocks is really worth it, believe me!

Lastly is brace form, indenting and commenting; these are: K&R style,
tab are 4 and spaces, and many, many, many. Rather than writing
yet-another-treatsie on C style, I will briefly state the three most
important aspects; I choose them solely to help in debugging:

    enums       some debuggers can display them symbolically
    rvalues     only one per line lets you see extacly what
                will happen during "stepping" in the debugger
    comment     introduce blocks on a line or lines above and
                comment of what a line (or block) does to the
                right
    braces      most of the time they are used on single line
                conditionals to make adding lines a bit faster

NOTE: The GCC makefile must use hard tabs! (Why? How stupid.)


MODIFICATION AND RE-DISTRIBUTION

Yes and yes. Informing me of any changes, or if you place a modified
version on a publicly accessible FTP/HTTP site, would be nice but is
not an absolute. This code is going to be changed and/or enhanced, so
please make note of that in any re-distribution or web-sites.

I would like submissions of changes, additions, suggestions and any
other things you can think of for this library.


LICENSE

There ain't one. My code is copyrighted by me. If anyone adds code,
their code portions will be copyrighted by them.

I want to keep this a source code only distribution (what good will
a library be in binary form only?!?!?). So the only restriction that
I would feel appropriate for this is no binary only re-distribution,
and that means no binary only re-distribution "with a pointer to
where the source is [_may_ be!] archived." It won't work that way.

But D_DISK will not be "copylefted", or GPL'ed. This ain't GNU-shit.
(Sorry if you feel GNU is a god; I don't. GNU has it's place. But
not with my shit.)

O yeah... NO MONEY. NO WARRANTY. NO GAURANTEE. I mean that. SUPPORT,
yes; by anyone. You don't like my terms... DO NOT USE THIS LIBRARY!

My terms may change, but only by removing restrictions (or wording,
phrasing, etc.), not by adding restrictions.


FINAL NOTES

I hope that this library will be of use to you and to others. I ask
nothing in return for its "being". All I ask is that no others ask
for anything in return for its "being" either. Is that
understandable?


THANK YOU FOR LISTENING

Gregg Jennings, 30-Nov-1998
http://www.diskwarez.com/d_disk.htm
http://www.diskwarez.com/disklib.htm
