Important Notice
The pages on this site contain documentation for very old MS-DOS software,
purely for historical purposes.
If you're looking for up-to-date documentation, particularly for programming,
you should not rely on the information found here, as it will be woefully
out of date.
_harderr, _hardresume, _hardretn
◄Summary► ◄Example► ◄Up► ◄Contents► ◄Index► ◄Back►
────────────────────────────────────────────────────────────────────────────
The _harderr, _hardresume, and _hardretn functions are used to
handle critical error conditions that use DOS interrupt 0x24.
The _harderr function installs a new critical-error handler for
interrupt 0x24.
The _hardresume and _hardreturn functions control how the program
will return from the new critical-error handler installed by
_harderr. The _hardresume function returns to DOS from a user-
installed critical-error handler, and the _hardreturn function
returns directly to the application program from a user-installed
critical-error handler.
The _harderr function does not directly install the handler
pointed to by _handler; instead, _harderr installs a handler that
calls the function referencing _handler. The handler calls the
function with the following parameters:
handler( unsigned deverror, unsigned errcode,
unsigned far *devhdr );
The <deverror> argument is the device error code. It contains
the AX register value passed by DOS to the INT 0x24 handler. The
<errcode> argument is the DI register value that DOS passes
to the handler. The low-order byte of <errcode> can be one of
the following values:
Code Meaning
0 Attempt to write to a write-protected disk
1 Unknown unit
2 Drive not ready
3 Unknown command
4 Cyclic-redundancy-check (CRC) error in data
5 Bad drive-request structure length
6 Seek error
7 Unknown media type
8 Sector not found
9 Printer out of paper
A Write fault
B Read fault
C General failure
The <devhdr> argument is a far pointer to a device header
containing descriptive information about the device on which the
error occurred. The user-defined handler must not change the
information in the device-header control block.
Errors on Disk Devices
If the error occurred on a disk device, the high-order bit (bit
15) of the <deverror> argument will be set to 0, and the deverror
argument will indicate the following:
Bits Meaning
15 Disk error if false (0).
14 Not used.
13 "Ignore" response not allowed if false.
12 "Retry" response not allowed if false.
11 "Fail" response not allowed if false. (Note that DOS
changes "fail" to "abort".)
9-10 Code Location
00 DOS
01 File Allocation Table (FAT)
10 Directory
11 Data area
8 Read error if false; write error if true
The low-order byte of <deverror> indicates the drive where the
error occurred (0 = drive A, 1 = drive B, etc.).
Errors on Other Devices
If the error occurs on a device other than a disk drive, the
high-order bit (bit 15) of the <deverror> argument is 1. The
attribute word located at offset 4 in the device-header block
indicates the type of device which has the error. If bit 15 of the
attribute word is 0, the error is a bad memory image of the File
Allocation Table. If the bit is 1, the error occurred on a
character device, and bits 0-3 of the attribute word indicate the
type of device, as shown below:
Bit Meaning
0 Current standard input
1 Current standard output
2 Current null device
3 Current clock device
Restrictions on Handler Functions
The user-defined handler function can only issue system calls 0x01
through 0x0C, or 0x59. Thus, many of the standard C run-time
functions (such as stream I/O and low-level I/O) cannot be used in
a hardware error handler. Function 0x59 may be used to obtain
further information about the error that occurred.
Using _hardresume and _harderr
If the handler returns, it can do so by any of these three
methods:
■ From the return statement
■ From the _hardresume function
■ From the _hardretn function
If the handler returns by way of _hardresume or a from a
return statement, the handler returns to DOS.
The _hardresume function should be called only from within the
user-defined hardware error-handler function. The result supplied
to _hardresume must be one of the following constants:
_HARDERR_ABORT _HARDERR_IGNORE
_HARDERR_FAIL _HARDERR_RETRY
The _hardretn function allows the user-defined hardware error
handler to return directly to the application program rather than
returning to DOS. The application resumes at the point just after
the failing I/O function request. The _hardretn function should
be called only from within a user-defined hardware error-handler
function.
The error parameter of _hardretn should be a DOS error code, as
opposed to the XENIX-style error code that is available in errno.
If the failing I/O function request is an INT 0x21 function
greater than or equal to function 0x38, then _hardretn will return
to the application with the carry flag set and the AX register set
to the _hardretn error parameter. If the failing INT 0x21 function
request is less than function 0x38 and the function can return an
error, the AL register is set to 0xFF on return to the application.
If the failing INT 0x21 does not have a way of returning an error
condition (as is true of certain INT 0x21 functions below 0x38),
the error parameter of _hardretn is not used and no error code is
returned to the application.
Return Value
None.
-♦-