DOS Error Reporting

IoErr() returns a numeric error code; printing the number is rarely helpful. dos.library provides three layers of help: convert the code to a string, print the string on the error stream, or pop a requester on the Workbench.

Need Function
Build a string for the code Fault()
Print the string on the error stream PrintFault()
Print an arbitrary string on the error stream PutErrStr() (V47+)
Pop a requester on screen ErrorReport()
Intercept "please insert volume" notices VolumeRequestHook() (V47+)

dos.library calls ErrorReport() itself on most failures. Application code rarely needs to.

Fault — build the human message

LONG Fault(LONG code, STRPTR header, STRPTR buffer, LONG size);   /* V36 */

Fills buffer (at most size bytes including the NUL terminator) with the formatted message:

[<header>: ]<description of code>
  • If header != NULL, it is copied first, followed by ": ".
  • If code != 0, a (localized) description of the error is appended.
  • If code == 0, the buffer is left untouched.
  • If no localized description is available, the numeric value is substituted.
  • The message does not include a line feed.

Fault() does not set IoErr(). The return value is documented as "number of characters inserted" but is broken even in V47 — do not rely on it. Use strlen(buffer) instead when code != 0:

LONG err = IoErr();
char buf[128];
if (err) {
    Fault(err, "MyApp", buf, sizeof(buf));
    printf("Error: %s\n", buf);
}

PrintFault — print the message

BOOL PrintFault(LONG code, STRPTR header);   /* V36 */

Equivalent to Fault() followed by FPuts() to the calling process's error stream (pr_CES). Falls back to standard output (pr_COS) if pr_CES is missing. (Pre-V45 always wrote to pr_COS.)

  • If header != NULL, prints header: first.
  • If a description of code exists, prints it; otherwise prints a numeric placeholder.
  • A code == 0 is a no-op and IoErr() is left alone.
  • Otherwise, IoErr() is set to code (so a follow-up IoErr() reads back the same code).

Returns non-zero on success; DOSFALSE if code != 0 and no description was available.

PutErrStr — write an arbitrary string to the error stream

LONG PutErrStr(STRPTR str);   /* V47 */

Writes the NUL-terminated str to pr_CES, falling back to pr_COS if missing. Returns 0 on success, ENDSTREAMCH (-1) on failure. IoErr() is set only if the underlying file handle's buffer is flushed.

ErrorReport — requester on screen

BOOL ErrorReport(LONG code, LONG type, ULONG arg1, struct MsgPort *device);   /* V36 */

Builds and shows an error requester on the Workbench screen, or on the screen of the window pointed to by the calling process's pr_WindowPtr. Returns a Boolean indicating whether the user wants to abort (DOSTRUE) or retry (DOSFALSE). If pr_WindowPtr == -1, the requester is suppressed and the function immediately returns DOSTRUE (abort).

If the calling process is a filesystem, ErrorReport() checks the FS process's pr_WindowPtr — not the client's — so requesters originating from inside the FS cannot be turned off by setting the client's pr_WindowPtr. The FFS bypasses ErrorReport() entirely and builds its own requesters.

Supported errors

Only a subset of error codes is recognised; all others return DOSTRUE (abort):

Error Meaning
ERROR_DISK_NOT_VALIDATED Corrupt volume, not yet validated
ERROR_DISK_WRITE_PROTECTED Volume is write-protected
ERROR_DISK_FULL Volume is full
ERROR_DEVICE_NOT_MOUNTED Handler/filesystem not mounted
ERROR_NOT_A_DOS_DISK Volume does not carry a valid filesystem
ERROR_NO_DISK No physical medium in the drive
ABORT_DISK_ERROR Physical read/write error on the medium (FS-internal, never returned to apps)
ABORT_BUSY Medium has dirty buffers and needs to be reinserted (FS-internal)

ABORT_DISK_ERROR and ABORT_BUSY are defined in dos/dosextens.h. The requester waits for the user to retry; if the user inserts the requested medium while the requester is open, ErrorReport() returns DOSFALSE (retry).

Source object type

type says what arg1 points at, providing the volume/lock/file information that goes into the requester text:

type arg1 is
REPORT_STREAM BPTR to a FileHandle
REPORT_LOCK BPTR to a FileLock
REPORT_VOLUME BPTR (despite the autodoc) to a DosList entry
REPORT_INSERT Regular C pointer to an absolute path string

When type == REPORT_INSERT, arg1 is split at the colon to extract the volume/device name. This is what dos.library itself does when an absolute-path lookup fails.

device is a regular pointer to a MsgPort. It is consulted only when type == REPORT_LOCK and arg1 == ZERO (root-of-FS lock), or when the faulting volume is no longer accessible. In those cases, dos.library sends ACTION_CURRENT_VOLUME to device to retrieve the volume name shown in the requester.

Behaviour notes

  • For ERROR_DEVICE_NOT_MOUNTED with REPORT_INSERT, ErrorReport() first calls VolumeRequestHook() to give assign-wedge code a chance to inject a binding or suppress the requester.
  • IoErr() is set to code on return, regardless of the abort/retry decision.
  • If pr_WindowPtr == -1, the system runs out of memory, or the error code is not in the supported set, the function returns DOSTRUE (abort) without showing a requester.

VolumeRequestHook — intercept "please insert volume"

LONG VolumeRequestHook(UBYTE *volume);   /* V47 */

dos.library calls this stub before showing an ERROR_DEVICE_NOT_MOUNTED requester. Return DOSTRUE to let the requester proceed; return DOSFALSE to suppress it as if the user pressed Cancel.

This function is not intended for client code to call. It is a hook: patch it (or wrap it) to implement "assign wedges" that lazy-create assigns on first use, or to suppress requesters the user has previously rejected.

See Also

Sources: Thomas Richter, "ROM Kernel Reference Manual: AmigaDOS" (First Edition, 2024), Chapter 16.2 — Reporting Errors. Raw: raw/rkm/rkm-dos-book.md Updated: 2026-10-02