IoErr

Return extra information from the system

Most dos.library functions return zero or NULL to indicate an error. When this happens (or whatever the defined error return code for the function is) IoErr() may be called to obtain more information. It is also used in some functions to pass back a secondary result which complements or extends what the primary return value of that function provides (see the respective function documentation for details).

Note:

There is no guarantee as to the value returned from IoErr() after a successful operation, unless so specified by the function.

You are best advised to retrieve the IoErr() value as soon as you learn that a function indicated failure. Any dos.library function call to follow could change the value which IoErr() will return, replacing what was previously recorded.

error

integer value, a BCPL pointer or 32-bit address depending upon what the file system operation which preceded this call to IoErr() returns as a secondary result or error code.

AmigaDOS error codes are defined in the <dos/dos.h> and <dos/dosasl.h> header files, which are numbers in the range 100-300. However, these error codes are not the only integer values which may be produced by file systems and handlers.

A file system which uses a mass storage device driver may pass errors produced by the device driver to the client. For example, trackdisk.device may pass the error code TDERR_NoSecHdr (see <devices/trackdisk.h>) to the file system, which then itself returns it as the secondary error. You may also encounter negative values such as IOERR_BADLENGTH (see the <exec/errors.h> header file).

As a rule of thumb, an error code in the range 100-400 is likely an AmigaDOS error. Negative numbers stand for exec device error codes and numbers greater than 0 and smaller than 100 are likely error codes used by specific device drivers such as trackdisk.device, scsi.device or printer.device.

Unfortunately, the less than 50 documented AmigaDOS error codes tend to be ambiguous. For example, file systems are prone to return ERROR_SEEK_ERROR if a file operation cannot be performed for reasons for which no other, more specific documented AmigaDOS error code exists in the first place.

Unlike for UNIX system calls, for which the specifications detail the error codes that may be produced, and under which conditions, it is hard to even supply a list of errors which any of the AmigaDOS library functions might produce.

Listed below you will find a list of AmigaDOS error codes, accompanied by explanations as to what may have caused them.

Because the set of error codes which AmigaDOS uses is a small selection from a much larger set of the Tripos operating system (which features more than 170 error codes), you may have difficulties picking an error code which represents the problem well.

If you are developing a file system or handler, please have a look at the descriptions in the list below and try to pick an error code which is helpful both for the user and also to software developers who make use of your work.

ERROR_NO_FREE_STORE

Not enough memory available, which specifically refers to RAM and not disk storage space.

ERROR_TASK_TABLE_FULL

Used by dos.library V30-V34 only, because the number of CLI Processes was limited to 20. No such limit exists in dos.library V36 and beyond.

ERROR_BAD_TEMPLATE

The AmigaDOS wildcard pattern used is inconsistent, or the command template given to ReadArgs() is faulty.

ERROR_BAD_NUMBER

A numerical argument is required, or, such as for ExAll(), an unsupported data type value was requested.

ERROR_REQUIRED_ARG_MISSING

An argument is required that you did not supply, for example if used with the ReadArgs() function.

ERROR_KEY_NEEDS_ARG

Keyword was specified with no argument, for example if used with the ReadArgs() function.

ERROR_TOO_MANY_ARGS

Too few or too many arguments, for example if used with the ReadArgs() function.

ERROR_UNMATCHED_QUOTES

You have an odd number of quotation marks at the beginning or the end of a path or string.

ERROR_LINE_TOO_LONG

Your command line is incorrect or contains too many arguments, or a string parameter is too-long for the supported length. Often used to indicate that a text or string does not fit into its destination buffer.

ERROR_FILE_NOT_OBJECT

You misspelt the command name or the file is not a loadable (program or script) file.

ERROR_INVALID_RESIDENT_LIBRARY

Used by dos.library V30-V34 to indicate that any of the resident libraries to be opened as part of the program load operation failed to open.

Used by dos.library V36 and beyond to indicate that the operating system does not match the required version. Often used by shell commands.

ERROR_OBJECT_IN_USE

The specified file or directory is being edited by another application or is assigned.

ERROR_OBJECT_EXISTS

The name specified is assigned to another file or directory.

ERROR_DIR_NOT_FOUND

AmigaDOS cannot find the specified directory. This is often used in place of ERROR_OBJECT_NOT_FOUND if it is known beforehand that the object to be located must be a directory and cannot be found.

ERROR_OBJECT_NOT_FOUND

AmigaDOS cannot find the specified file or device.

ERROR_BAD_STREAM_NAME

Occurs when specifying a window size for a Shell, Ed, or IconX window. The window may be too big or too small or you omitted an argument. Also occurs with the NewShell command, if a device name is supplied that is not a window.

ERROR_OBJECT_TOO_LARGE

Not used by AmigaDOS.

ERROR_ACTION_NOT_KNOWN

The device handler/file system handler cannot perform the requested operation, or does not understand the operation.

As used by AmigaDOS, there is a fine line between a file system or handler being unable to comply with a request it understands (e.g. the console handler cannot rename things.) and it rejecting a request which it does not understand. Past practice defaults to use the ERROR_ACTION_NOT_KNOWN error code in spite of the ambiguity involved. The original Tripos error code which became ERROR_ACTION_NOT_KNOWN would bear a different name which is closer to what ERROR_NOT_IMPLEMENTED stands for.

ERROR_INVALID_COMPONENT_NAME

There is an invalid character in the file name or the file name is too long. For example, some file systems do not allow unprintable characters to feature in a path or directory name. A device or volume may not contain a colon (":") or slash ("/") character.

ERROR_INVALID_LOCK

An operation was attempted on a Lock or FileHandle and the provided parameter was found to be inconsistent or invalid.

ERROR_OBJECT_WRONG_TYPE

You may have specified a file name for an operation that requires a directory name, or vice versa.

ERROR_DISK_NOT_VALIDATED

If you have just inserted a disk, the disk validation process may be in progress. It is also possible that the disk is corrupt, thus preventing the validation process from being performed in the first place.

ERROR_DISK_WRITE_PROTECTED

The plastic tab of a floppy disk is in the write-protect position or the disk has been locked. It is also possible that the file system cannot be written to (CD-ROM).

ERROR_RENAME_ACROSS_DEVICES

The Rename() function can move a file from one directory to another, but not from one volume to another.

ERROR_DIRECTORY_NOT_EMPTY

You tried to delete a directory that contains files or subdirectories.

ERROR_TOO_MANY_LEVELS

Directory nesting is too deep to handle. Also, soft link resolution, which may require several repetitions of the resolution process, will at some point be aborted without producing the correct path name, returning failure and setting this error code. The MatchFirst() and MatchNext() functions may abort the operation if the available stack space of the caller drops below a minimum safe value, returning failure and setting this error code.

ERROR_DEVICE_NOT_MOUNTED

If the device is a floppy disk, it has not been inserted in a drive. If it is another type of device, it has not been mounted, or the name is misspelt.

ERROR_SEEK_ERROR

This can occur if you are calling any function that changes the internal file pointer position and the final file position is beyond the beginning or the end of the file. File systems may also set this error code for conditions under which no other error code may be a better fit.

ERROR_COMMENT_TOO_BIG

This can occur with SetComment() if the comment string is larger than permitted (typically 79 characters).

ERROR_DISK_FULL

There is no more room on the medium to complete a file system operation.

ERROR_DELETE_PROTECTED

A file or directory on an otherwise write-enabled medium cannot be deleted or replaced.

ERROR_WRITE_PROTECTED

A file or directory on an otherwise write-enabled medium cannot be modified.

ERROR_READ_PROTECTED

A file cannot be read from.

ERROR_NOT_A_DOS_DISK

A medium cannot be accessed since the file system responsible for it cannot make sense of its contents.

ERROR_NO_DISK

There is no medium present in a disk drive. The requested file system operation cannot be completed.

ERROR_NO_MORE_ENTRIES

This error code indicates that the ExNext() or ExAll() functions have reached the end of a directory and will return no further entries.

ERROR_IS_SOFT_LINK

This is returned by file systems in order to indicate to dos.library that the name of the object given must be resolved as a soft link and does not point to a directory or file which the file system itself could handle.

ERROR_BAD_HUNK

The structure of an executable file is inconsistent. The file may have been damaged and corrupted.

ERROR_NOT_IMPLEMENTED

Used by AmigaDOS, file systems and handlers to indicate that a requested operation is known but cannot be performed because it is not implemented. For example, some file systems do not support the LockRecord()/UnLockRecord() family of operations and will return ERROR_NOT_IMPLEMENTED as an error, as opposed to the more general and unspecific ERROR_ACTION_NOT_KNOWN.

ERROR_RECORD_NOT_LOCKED

The record you tried to unlock through UnLockRecord() is not actually locked.

ERROR_LOCK_COLLISION

The record you tried to lock is already locked.

ERROR_LOCK_TIMEOUT

Your attempt to lock a record failed, even after waiting for the period you specified.

ERROR_UNLOCK_ERROR

Not used by AmigaDOS, but was originally used by the UnLockRecord()/UnLockRecords() functionality in ram-handler.

ERROR_BUFFER_OVERFLOW

User or internal buffer overflow. This can happen for the MatchFirst() and MatchNext() functions.

ERROR_BREAK

A program was aborted, such as by sending it a Break signal in the Shell.

ERROR_NOT_EXECUTABLE

Not used by AmigaDOS.

There are many notable exceptions to the general rule that dos.library functions return zero or NULL (as their primary result), such as the Seek() and FRead() functions which both return -1 on error. The documentation for functions which do not use zero or NULL to indicate failure will describe what exactly the result means (success or failure).

Fault(), PrintFault(), SetIoErr()