Usage restrictions on DMAPI functions

There are usage restrictions on the DMAPI for GPFS functions.

• The maximum number of DMAPI sessions that can be created on a node is 4000.
• Root credentials are a prerequisite for invoking any DMAPI function, otherwise the function fails with an EPERM error code.
• DMAPI functions are unable to run if the GPFS kernel extension is not loaded, or if the runtime module dmapicalls is not installed. An ENOSYS error code is returned in this case.
• Invoking a DMAPI function that is not implemented in GPFS results in returning the ENOSYS error code.
• DMAPI functions will fail, with the ENOTREADY error code, if the local GPFS daemon is not running.
• DMAPI functions will fail, with the EPERM error code, if DMAPI is disabled for the file system that is referenced by the file handle argument.
• DMAPI functions cannot access GPFS reserved files, such as quota files, inode allocation maps, and so forth. The EBADF error code is returned in this case.
• GPFS does not support access rights on entire file systems (as opposed to individual files). Hence, DMAPI function calls that reference a file system (with a file system handle) cannot present a token, and must use DM_NO_TOKEN. Functions affected by this restriction are:
  • dm_set_eventlist
  • dm_get_eventlist
  • dm_set_disp
  • dm_get_mountinfo
  • dm_set_return_on_destroy
  • dm_get_bulkattr
  • dm_get_bulkall

  If a token is presented, these functions fail with the EINVAL error code.

• DMAPI functions that acquire, change, query, or release access rights, must not present a file system handle. These functions are:
  • dm_request_right
  • dm_upgrade_right
  • dm_downgrade_right
  • dm_release_right
  • dm_query_right

  If a file system handle is presented, these functions fail with the EINVAL error code.

• The function dm_request_right, when invoked without wait (the flags argument has a value of 0), will almost always fail with the EAGAIN error. A GPFS implementation constraint prevents this function from completing successfully without wait, even if it is known that the requested access right is available. The DM_RR_WAIT flag must always be used. If the access right is available, there will be no noticeable delay.
• DMAPI function calls that reference a specific token, either as input or as output, can be made only on the session node. Otherwise, the call fails with the EINVAL error code.
• DMAPI function calls that reference an individual file by handle must be made on the session node. The corresponding file system must be mounted on the session node. The call fails with EINVAL if it is not on the session node, and with EBADF if the file system is not mounted.
• DMAPI function calls that reference a file system by handle (as opposed to an individual file) can be made on any node, not just the session node. The relevant functions are:
  • dm_set_eventlist
  • dm_get_eventlist
  • dm_set_disp
  • dm_get_mountinfo
  • dm_set_return_on_destroy
  • dm_get_bulkattr
  • dm_get_bulkall

  For dm_get_bulkattr and dm_get_bulkall, the system file must be mounted on the node that is making the call. For the other functions, the file system must be mounted on some node, but not necessarily on the node that is making the call. As specified previously, all such function calls must use DM_NO_TOKEN. The function fails with the EBADF error code if the file system is not mounted as required.

• The function dm_punch_hole will fail with the EBUSY error code if the file to be punched is currently memory-mapped.
• The function dm_move_event can only be used when the source session and the target session are on the same node. The function must be called on the session node. Otherwise, the function fails with the EINVAL error code.
• The function dm_create_session, when providing an existing session id in the argument oldsid, can only be called on the session node, except after session node failure. Otherwise, the call will return the EINVAL error code.
• The function dm_destroy_session can only be called on the session node, otherwise the call will fail with the EINVAL error code.
• The function dm_set_fileattr cannot change the file size. If the dm_at_size bit in the attribute mask is set, the call fails with the EINVAL error code.
• DMAPI functions that reference an event with a token fail with the ESRCH error code, if the event is not in an outstanding state. This is related to session recovery. See Failure and recovery of IBM Storage Scale Data Management API for GPFS for details on session failure and recovery.