Error handling API reference

hipFile functions communicate errors through two mechanisms: a dual-field hipFileError_t struct returned by most API calls, and a signed ssize_t return value used by hipFileRead and hipFileWrite. This page documents the types, constants, function, and helper macros that form the error handling surface.

For guidance on interpreting errors in practice, see Synchronous read and write API reference.

nodiscard attribute

The hipFileError_t struct carries the [[nodiscard]] attribute when compiled with C++ 17 or newer (__cplusplus >= 201703L) or C23 or newer (__STDC_VERSION__ >= 202311L). The compiler emits a warning if a caller discards the return value of any function that returns hipFileError_t.

ssize_t return convention

hipFileRead and hipFileWrite return an ssize_t instead of a hipFileError_t. A non-negative value indicates the number of bytes transferred. A return value of -1 signals a system error; check errno for details. Any other negative value is the negation of the corresponding hipFileOpError_t code. Use IS_HIPFILE_ERR and HIPFILE_ERRSTR (passing the absolute value) to inspect such errors.

Error types

enum hipFileOpError_t

hipFile function return codes

An error code of -1 indicates a that a C or POSIX error has occurred and errno is likely to have been set.

Note

HIPFILE_BASE_ERR + 21 and 32 are intentionally omitted.

Values:

enumerator hipFileSuccess

hipFile operation completed successfully

enumerator hipFileDriverNotInitialized

GPU IO driver is not loaded.

enumerator hipFileDriverInvalidProps

Invalid GPU IO driver property provided.

enumerator hipFileDriverUnsupportedLimit

GPU IO Driver property value is unsupported.

enumerator hipFileDriverVersionMismatch

hipFile version does not match GPU IO driver version

enumerator hipFileDriverVersionReadError

Unable to read the GPU IO driver version.

enumerator hipFileDriverClosing

GPU IO driver is closing and not accepting new requests.

enumerator hipFilePlatformNotSupported

hipFile is not supported on the current platform

enumerator hipFileIONotSupported

hipFile is not supported on the selected file

enumerator hipFileDeviceNotSupported

The selected GPU does not support hipFile.

enumerator hipFileDriverError

GPU IO driver error.

enumerator hipFileHipDriverError

GPU driver error: Inspect the hipError_t value for additional information.

enumerator hipFileHipPointerInvalid

Invalid GPU pointer.

enumerator hipFileHipMemoryTypeInvalid

Memory type backing pointer is incompatible with hipFile.

enumerator hipFileHipPointerRangeError

Pointer range exceeds allocated memory region.

enumerator hipFileHipContextMismatch

GPU driver context mismatch.

enumerator hipFileInvalidMappingSize

Accessing memory beyond pinned memory buffer.

enumerator hipFileInvalidMappingRange

Accessing memory beyond mapped memory region.

enumerator hipFileInvalidFileType

Unsupported file type.

enumerator hipFileInvalidFileOpenFlag

Unsupported file open flags.

enumerator hipFileDIONotSet

O_DIRECT flag not set.

enumerator hipFileInvalidValue

One or more arguments have an invalid value.

enumerator hipFileMemoryAlreadyRegistered

Device pointer is already registered.

enumerator hipFileMemoryNotRegistered

Device pointer is not registered.

enumerator hipFilePermissionDenied

Permission error on device or file access.

enumerator hipFileDriverAlreadyOpen

GPU IO driver is already open.

enumerator hipFileHandleNotRegistered

File handle for GPU IO is not registered.

enumerator hipFileHandleAlreadyRegistered

File handle for GPU IO is already registered.

enumerator hipFileDeviceNotFound

Selected device not found.

enumerator hipFileInternalError

Internal GPU IO library error.

enumerator hipFileGetNewFDFailed

Unable to obtain a new file descriptor.

enumerator hipFileDriverSetupError

GPU IO Driver initialization error.

enumerator hipFileIODisabled

GPU IO config file prohibits GPU IO on specified file.

enumerator hipFileBatchSubmitFailed

Failed to submit request for batch operation.

enumerator hipFileGPUMemoryPinningFailed

Failed to allocated pinned device memory.

enumerator hipFileBatchFull

Batch operation queue is full.

enumerator hipFileAsyncNotSupported

hipFile async IO is not supported

enumerator hipFileIOMaxError

Internal flag to mark largest hipFile error code.

HIPFILE_API const char *hipFileGetOpErrorString(hipFileOpError_t status)

Return a descriptive string for a hipFile error.

Parameters:

status – [in] Return code provided by hipFile

Returns:

Description of the error encountered

HIPFILE_BASE_ERR

The base value for hipFile error codes.

IS_HIPFILE_ERR(hip_op_err)

Determine if an error code is a hipFile error.

Signature

bool IS_HIPFILE_ERR(hipFileOpError err)

Returns:

true/false

HIPFILE_ERRSTR(hip_op_err)

Get an error string for a hipFile error.

Signature

const char *HIPFILE_ERRSTR(hipFileOpError err)

Returns:

A string description of a hipFile error

IS_HIP_DRV_ERR(hip_err)

Determine if an error is a hipFile driver error.

Signature

bool IS_HIP_DRV_ERR(hipFileError_t err)

Returns:

true/false

HIP_DRV_ERR(hip_err)

Get the driver error from a hipFileError_t.

Signature

hipError_t HIP_DRV_ERR(hipFileError_t err)

Returns:

The hipError_t component of err

struct hipFileError_t

#include <hipfile.h>

Error status returned from hipFile API calls.

Note

This struct has the [[nodiscard]] attribute in C++ >= 17 and C >= 23 so unhandled return values will generate warnings