Click above to get retro games delivered to your door ever month!

Synopsis:
    #include <dos.h>
    void _harderr( int (__far *handler)() );
    void _hardresume( int action );
    void _hardretn( int error );

Description:
    The _harderr routine installs a critical error handler (for INT 0x24) to
    handle hardware errors.  This critical error handler will call the
    user-defined function specified by handler when a critical error occurs
    (for example, attempting to open a file on a floppy disk when the drive
    door is open).  The parameters to this function are as follows:


         int handler( unsigned deverror,
                      unsigned errcode,
                      unsigned __far *devhdr );

    The low-order byte of errcode can be one of the following values:

    Value     Meaning

0x00
    Attempt to write to a write-protected disk

0x01
    Unknown unit

0x02
    Drive not ready

0x03
    Unknown command

0x04
    CRC error in data

0x05
    Bad drive-request structure length

0x06
    Seek error

0x07
    Unknown media type

0x08
    Sector not found

0x09
    Printer out of paper

0x0A
    Write fault

0x0B
    Read fault

0x0C
    General failure

    The devhdr argument points to a device header control-block that
    contains information about the device on which the error occurred.  Your
    error handler may inspect the information in this control-block but must
    not change it.

    If the error occurred on a disk device, bit 15 of the deverror argument
    will be 0 and the deverror argument will indicate the following:

    Bit     Meaning

bit 15
    0 indicates disk error

bit 14
    not used

bit 13
    0 indicates "Ignore" response not allowed

bit 12
    0 indicates "Retry" response not allowed

bit 11
    0 indicates "Fail" response not allowed

bit 9,10
    location of error

    Value     Meaning

00
    MS-DOS

01
    File Allocation Table (FAT)

10
    Directory

11
    Data area

bit 8
    0 indicates read error, 1 indicates write error

    The low-order byte of deverror indicates the drive where the error
    occurred; (0 = drive A, 1 = drive B, etc.).

    The handler is very restricted in the type of system calls that it can
    perform.  System calls 0x01 through 0x0C, and 0x59 are the only system
    calls allowed to be issued by the handler.  Therefore, many of the
    standard C run-time functions such as stream I/O and low-level I/O
    cannot be used by the handler.  Console I/O is allowed (e.g., cprintf,
    cputs).

    The handler must indicate what action to take by returning one of the
    following values or calling  _hardresume with one of the following
    values:

    Value     Meaning

_HARDERR_IGNORE
    Ignore the error

_HARDERR_RETRY
    Retry the operation

_HARDERR_ABORT
    Abort the program issuing INT 0x23

_HARDERR_FAIL
    Fail the system call that is in progress (DOS 3.0 or higher)

    Alternatively, the handler can return directly to the application
    program rather than returning to DOS by using the  _hardretn function.
     The application program 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 argument of  _hardretn should be a DOS error code.  See The
    MS-DOS Encyclopedia or Programmer's PC Sourcebook, 2nd Edition, for more
    detailed information on DOS error codes that may be returned by a given
    DOS function call.

    If the failing I/O function request is an INT 0x21 function greater than
    or equal to function 0x38,  _hardretn will return to the application
    with the carry flag set and the AX register set to the  _hardretn error
    argument.  If the failing INT 0x21 function request is less than
    function 0x38 abd the function can return an error, the AL register will
    be set to 0xFF on return to the application.  If the failing INT 0x21
    function does not have a way of returning an error condition (which is
    true of certain INT 0x21 functions below 0x38), the error argument of
     _hardretn is not used, and no error code is returned to the
    application.

Returns:
    These functions do not return a value.  The  _hardresume and  _hardretn
    functions do not return to the caller.

Example:
    #include <stdio.h>
    #include <conio.h>
    #include <dos.h>

    int __far critical_error_handler( unsigned deverr,
                                      unsigned errcode,
                                      unsigned far *devhdr )
      {
        cprintf( "Critical error: " );
        cprintf( "deverr=%4.4X errcode=%d\r\n",
                 deverr, errcode );
        cprintf( "devhdr = %Fp\r\n", devhdr );
        return( _HARDERR_IGNORE );
      }

    main()
      {
        FILE *fp;

        _harderr( critical_error_handler );
        fp = fopen( "a:tmp.tmp", "r" );
        printf( "fp = %p\n", fp );
      }

    produces the following:

    Critical error: deverr=1A00 errcode=2
    devhdr = 0070:01b6
    fp = 0000

Classification:
    DOS

Systems:
     _harderr - DOS

    _hardresume - DOS
    _hardretn - DOS/16
    _hardresume - DOS
    _hardretn - DOS/16

See Also:
    _chain_intr, _dos_getvect, _dos_setvect