Data management application programming interface

Edit online

AIX® provides a data management application programming interface (DMAPI), which is an implementation of the "System Management: Data Storage Management (XDSM) API" X/Open standard that is published by The Open Group.

The DMAPI allows software vendors to develop data management applications using a set of functions and semantics not found in POSIX-compliant systems. It does not provide direct functionality to the end user. Complete documentation of the DMAPI is found in the Publications section of The Open Group's Web site.

The DMAPI provided by AIX is a general purpose implementation. The level of support for optional interfaces and functionality is determined by the underlying file system implementation and is documented in a separate section for the specific file system.

The intent of the DMAPI is to support a single product on any single file system. The DMAPI does not preclude different products from different vendors operating on the same file system, but it is not recommended. Different products on different file systems are fully supported by the DMAPI with regard to event delivery, subject to the following restrictions:

Multiple sessions cannot register disposition for the same event on the same object.
Event messages are targeted to and enqueued on sessions; there is no explicit targeting of an event to a specific process.
If no session has registered a disposition for a particular event other than the mount event, the DMAPI will not generate an event and allow the process to proceed as if there is no event enabled. If no session has registered a disposition for the mount even, which is always enabled, the DMAPI will fail the event and not allow the file system to be mounted.

The DMAPI is implemented in an abstract layer within AIX, allowing any underlying file system to define its individual level of support and implementation options. The journaled file system (JFS) file system does not provide any support for the DMAPI. The enhanced journaled file system (JFS2) behaviors for implementation options, limits, and other specifics described by the X/Open standard are outlined in DMAPI Considerations for the Enhanced Journaled File System.

The dm_init_service function returns 0 when the AIX DMAPI is correctly initialized and -1 if the initialization fails. Use of any other DMAPI function after the initialization fails will also fail.

The AIX DMAPI does not provide support for the following optional DMAPI functions:

dm_downgrade_right
dm_upgrade_right
dm_obj_ref_* family
dm_pending

Other optional interfaces might not be supported by the underlying file system implementation and are indicated in the DMAPI documentation for the specific file system.

When a data management (DM) application specifies that it wants to block until a right becomes available, the DM application is blocked uninterruptibly.

AIX allows multiple, non-overlapping persistent managed regions. Only regular files are allowed to have managed regions. Whether or not managed regions are reordered or coalesced is determined by the underlying file system implementation.

When no session has registered to receive a particular event for which an object is enabled and activity occurs that would otherwise trigger the event, AIX does not generate the event and allows the process to proceed as if there is no event enabled.

Executing the dm_set_eventlist function causes a persistent event list to be stored with the object. If an event list was previously set for the entire file system and a subsequent event list for an object in that file system includes an event that was set for the file system, events will continue to be generated based on the event list for the file system until such time as that event is disabled, in which case the event list for the object will come into play.

When a process generating an event is blocked waiting on a response from a DM application, the sleep is interruptible.

AIX adopts a reasonably reliable model of asynchronous message delivery. The number of undelivered asynchronous messages is limited by the amount of available memory (real or virtual) configured on the system. If the number of messages exceeds the amount of available memory, undelivered asynchronous messages will be lost. Asynchronous delivery of namespace event messages is determined by the underlying file system implementation.

For AIX, DM_SESSION_INFO_LEN is 256, and DM_ATTR_NAME_SIZE is 8.

For DMAPI interfaces that return data to a user buffer and fill in a user variable with the resulting size of the buffer, both the contents of the buffer and the user size variable are undefined when the interface fails with an error other than E2BIG. For any such error, the contents of the user buffer must be ignored. When the interface fails and errno is E2BIG, the content of the user size variable will be set to indicate the required size, in which case the application can retry the interface with a resized buffer.

DMAPI considerations for the enhanced journaled file system

Note: Internal snapshots cannot be used with DMAPI-managed file systems.

In addition to the functionality provided by the general AIX implementation of the DMAPI, the JFS2 implementation provides the following functionality and restrictions.

The dm_get_config function returns the following values for the JFS2 implementation options and limits:

DM_CONFIG_BULKALL: Supported
DM_CONFIG_LEGACY: Supported
DM_CONFIG_PERS_ATTRIBUTES: Supported
DM_CONFIG_PERS_EVENTS: Supported
DM_CONFIG_PERS_INHERIT_ATTRIBS: Supported
DM_CONFIG_PERS_MANAGED_REGIONS: Supported
DM_CONFIG_PUNCH_HOLE: Supported
DM_CONFIG_WILL_RETRY: Supported
DM_CONFIG_CREATE_BY_HANDLE: Not supported
DM_CONFIG_LOCK_UPGRADE: Not supported
DM_CONFIG_OBJ_REF: Not supported
DM_CONFIG_PENDING: Not supported
DM_CONFIG_DTIME_OVERLOAD: TRUE
DM_CONFIG_MAX_ATTR_ON_DESTROY: 128
DM_CONFIG_MAX_ATTRIBUTE_SIZE: 4072
DM_CONFIG_MAX_HANDLE_SIZE: 32
DM_CONFIG_MAX_MANAGED_REGIONS: 167
DM_CONFIG_MAX_MESSAGE_DATA: 65536
DM_CONFIG_TOTAL_ATTRIBUTE_SPACE: 4072

In the JFS2 implementation, all DM attribute values share the same allocation. Consequently, the size of any one attribute's value cannot exceed DM_CONFIG_MAX_ATTRIBUTE_SIZE and is further restricted by the sum of the value sizes of all DM attributes associated with an object, which is also limited to DM_CONFIG_MAX_ATTRIBUTE_SIZE.

In addition to the optional interfaces not supported by AIX, the JFS2 implementation does not support the optional DMAPI cancel and debut events, nor the additional optional dm_getall_dmattr, dm_create_by_handle, and dm_symlink_by_handle functions.

Due to the current implementation of JFS2's extended attribute support, the dm_set_region function causes the file's ctime to be modified. JFS2 does not attempt to reorder nor coalesce managed regions.

JFS2 generates asynchronous namespace event messages for all corresponding operations, whether they succeed or fail.

JFS2 provides interfaces that allow pre-allocation and direct control of metadata within a file system. Use of these interfaces with either the MM_ALLOC or MM_RECORD modes generates a DMAPI write event for the specified offset and length.

If a value is not specified for the mask to the dm_get_bulkall, dm_get_bulkattr, dm_get_dirattrs, and dm_get_fileattr functions (that is, it is set to zero), JFS2 will return all fields in the dm_stat structure. If the mask is set to a specific value, only the fields requested by the mask are returned; the values for the fields not specified by the mask are undefined.

JFS2 does not use the respbufp parameter of the dm_respond_event function. If specified, the content of the buffer is undefined when the functions returns.

Because JFS2 overloads dm_ctime and dm_dtime (that is, DM_CONFIG_DTIME_OVERLOAD is true), the setdtime parameter of the dm_set_dmattr function is ignored.

At the time a file is memory mapped (that is, when the mmap(2) call is executed), any non-resident portions of a file must be made resident by the DM application. To notify the application of the mapping, JFS2 will generate a read or write event corresponding to the mode and region being mapped.

Activating the DMAPI on a JFS2 file system

To activate the DMAPI on a JFS2 file system, type the following:

chfs -a managed=yes mountpoint

If the file system is currently mounted when the chfs command is issued, there must be a DMAPI-enabled application listening for and responding to mount events when the managed parameter is set; the success of the chfs command will depend on how the application responds to the mount event.

To deactivate the DMAPI on a JFS2 file system, type the following:

chfs -a managed=no mountpoint

If the file system is currently mounted when the chfs command is issued, there must be a DMAPI-enabled application listening for and responding to pre-unmount events when the managed parameter is set. The success of the chfs command depends on how the application responds to the pre-unmount event.

Using the DMAPI on JFS2 encrypted file systems

When you perform invisible I/O operations on encrypted files in a JFS2 encrypted file system, the same offset and length alignment restrictions apply as if you performed RAW mode I/O on the file. In particular, the offset and length of the I/O must be block-aligned according to the block size of the file system. The size of the encrypted data is always a multiple of file system blocks, even when the decrypted file size is not; when the file size is not block aligned, the file contains encrypted data beyond the file size.

Note: The stat subroutine and DMAPI interfaces, such as the dm_get_fileattr function, report the clear text (decrypted) file size, while the statx subroutine reports the block-aligned encrypted data size when you pass STX_EFSRAW as the command parameter.

The dm_read_invis function and the dm_write_invis function must meet the following requirements to make the operation successful:

dm_read_invis: For encrypted files, both the off and the len parameters must be file system block-size aligned, or the operation fails with the EINVAL error code.
dm_write_invis: For encrypted files, both the off and the len parameters must be file system block-size aligned and the operation must not attempt to extend the file, or the operation fails with the EINVAL error code.

Using the DMAPI on AIX workload partitions

You must add the PV_FS_DMAPI privilege to the set of privileges and assign them to the processes running in the Workload Partition (WPAR) to run the DMAPI applications within a WPAR. You can add and assign the set of privileges to a WPAR when it is being created, or you can modify the set of privileges later.

Examples

mkwpar -S privs+=PV_FS_DMAPI -n wparname

chwpar -S privs+=PV_FS_DMAPI wparname

By default, only the root processes obtain the privilege to run in a WPAR. In a root-disabled system or in an Trusted AIX installation, where root is disabled by default, nonroot processes obtain this privilege by using the privcmds table in a global or WPAR system. For more information, see RBAC privileges.