Additional error codes returned by DMAPI functions

DMAPI for GPFS uses additional error codes, not specified in the XDSM standard, for most DMAPI functions.

For C declarations of all the DMAPI for GPFS functions, refer to the dmapi.h file located in the /usr/lpp/mmfs/include directory.

For all DMAPI functions, these error codes are used:

ENOSYS: The GPFS kernel extension is not loaded, or the runtime module dmapicalls is not installed.
ENOSYS: An attempt has been made to invoke a DMAPI function that is not implemented in GPFS.
ENOTREADY: The local GPFS daemon is not running or is initializing.
ENOMEM: DMAPI could not acquire the required resources to complete the call. ENOMEM is defined in the XDSM standard for some DMAPI functions, but not for all.
ESTALE: An error has occurred which does not fit any other error code specified for this function.

For DMAPI functions that provide a file handle as an input argument, these error codes are used:

EINVAL: The format of the file handle is not valid.
This error is returned without attempting to locate any object that is referenced by the handle. The EINVAL error code is to be distinguished from the EBADF error code, which, as specified in the XDSM standard, indicates that the object does not exist or is inaccessible. Thus, GPFS provides a refinement, distinguishing between format and access errors related to handles.
EPERM: DMAPI is disabled for the file system that is referenced by the file handle.

For DMAPI functions that provide a token as an input argument, these error codes are used:

ESRCH: The event referenced by the token is not in outstanding state.
This is to be distinguished from the EINVAL error code, which is returned when the token itself is not valid. ESRCH is defined in the XDSM standard for some DMAPI functions, but not for all relevant functions. In GPFS, the ESRCH error code occurs mostly after recovery from session failure. See Event recovery for details.

For these specific DMAPI functions, the error code listed is used:

Table 1. Specific DMAPI functions and associated error codes.
Name of function	Error codes and descriptions
dm_downgrade_right() dm_upgrade_right()	EINVAL - The session or token is not valid.
dm_get_region()	EPERM - The caller does not hold the appropriate privilege.
dm_init_service()	EFAULT - The system detected an invalid address in attempting to use an argument.
dm_move_event() dm_respond_event()	EINVAL - The token is not valid.
dm_punch_hole()	EBUSY - The file is currently memory mapped.
dm_probe_hole() dm_punch_hole()	EINVAL - The argument len is too large, and will overflow if cast into offset_t. EINVAL - The argument off is negative.
dm_write_invis()	EINVAL - The argument flags is not valid.
dm_read_invis() dm_write_invis()	EINVAL - The argument len is too large, and will overflow if placed into the uio_resid field in the structure uio. EINVAL - The argument off is negative.
dm_sync_by_handle()	EROFS - The operation is not allowed on a read-only file system.
dm_find_eventmsg() dm_get_bulkall() dm_get_bulkattr() dm_get_dirattrs() dm_get_events() dm_get_mountinfo() dm_getall_disp() dm_getall_dmattr() dm_handle_to_path()	EINVAL - The argument buflen is too large; it must be smaller than INT_MAX.
dm_get_alloc_info() dm_getall_sessions() dm_getall_tokens()	EINVAL - The argument nelem is too large; DMAPI cannot acquire sufficient resources.