Previous section.

Systems Management: Data Storage Management (XDSM) API

Systems Management: Data Storage Management (XDSM) API
Copyright © 1997 The Open Group


Scope and Purpose

To adequately support data management applications, a file system and its host Operating System must include a set of functions and semantics not found in most POSIX-compliant systems. These extensions include the capability to monitor events on files and special interfaces to manage and maintain the data in a file.

The important features of the DMAPI as described in this document are the use of events to notify DM applications about operations on files, the ability of DM applications to store arbitrary attribute information with a file, support for managed regions within a file, and the use of DMAPI access rights to control access to a file object.

Data management applications such as file backup and recovery, file migration, and file replication typically function as logical extensions of the operating system. They often must have special permissions (such as root or file system credentials) to operate. The interfaces and data structures described in this document are all designed for these specific applications. These interfaces are not intended for direct use by typical end-users or unprivileged processes.


Events and managed regions are the foundations of the DMAPI. In the event paradigm, the operating system informs a DM application running in user space when a particular event occurs. For example, a DM application in user space can request that it be notified whenever a read of a certain area of a file occurs. When the operating system determines that it is going to read data from the target area, it notifies the DM application via a DMAPI event. In this manner, DM applications can monitor and manage files and specific regions within those files.

Files can be divided into distinct portions known as managed regions. Some types of DMAPI events are produced on a per region basis; this allows for finer granularity of event notification and reduces the number of messages between the operating system and the DM application.


One of the fundamental concepts of the DMAPI is that of a token. A token is a reference to state associated with a synchronous event message. This state may include lists of files affected by the event, the access rights that are currently in force for those files, and so forth. The token provides DM applications with a simple method of referencing this state. Most DMAPI functions require a token as one of their parameters.

Access Rights

The DMAPI provides DM applications with the ability to control access to a file object. There are three forms of access rights: DM_RIGHT_NULL, DM_RIGHT_SHARED, and DM_RIGHT_EXCL. These rights are mutually exclusive; it is not possible to have a DM_RIGHT_SHARED right in effect on an object at the same time as a DM_RIGHT_EXCL right.

A DM_RIGHT_SHARED right grants its holder the right to read or query a file system object; this is called a shared right. A DM_RIGHT_EXCL right grants its holder all of the DM_RIGHT_SHARED rights plus the right to modify a file system object; this is called an exclusive right. As the names suggest, there may be multiple DM_RIGHT_SHARED rights granted on an object at one time. There can be only one DM_RIGHT_EXCL right granted, and it excludes DM_RIGHT_SHARED rights as well.

Access rights to a file system object may be conveyed to a DM application as part of sending a synchronous event message. DM applications must use the dm_query_right(), dm_request_right(), and dm_release_right() interfaces to determine the access rights that have been conveyed.

DMAPI access rights provide a mechanism for a DM application to synchronize accesses by other processes. If a token references an outstanding message that conveys the DM_RIGHT_EXCL access right for a file, then only processes presenting that token as an argument to a DMAPI function may access the file; all other attempted accesses to the file (including from within the operating system) are blocked.

These access rights provide a level of abstraction from internal operating system locks. Each Operating System will have different locking requirements and implementations. Using the DMAPI access rights provides DM applications a consistent interface to the Operating System, regardless of the internal locking model.

For more information on access rights, tokens, and synchronous messages, see the Sessions and Event Messages, Tokens, and Access Rights sections.

Managed Regions

A managed region designates a specific portion of a file that is managed by a DM application. Managed regions allow exception events to be generated only for those parts of the file in which the DM application has interest.

A managed region consists of the following information:

Persistence, the duration of the period over which a given managed region exists, of this information is implementation specific, and can be determined through a DMAPI configuration function.


The DMAPI uses handles to identify file system objects. All of the interfaces in this document use handles as opposed to file descriptors. A special handle that references a file system as a whole is provided along with another one that allows receiving events when file systems are being mounted.


The interface between the operating system and the DM application is session based. Sessions identify the recipient of an event message, and can also provide the DMAPI implementation with the ability to track, audit, and control the use of DMAPI facilities. Internally, sessions can be used by the DMAPI implementation as a mechanism to identify the queues that messages are placed on. Sessions are not persistent across reboots.

Data Management Attributes

DM applications typically use extended attributes to store pertinent information about a file. Attributes in this context are termed opaque since these attributes only have meaning to the application that created them. Non-opaque attributes provide information that is visible to the DMAPI implementation, such as managed region layout or event lists.

For example, the following are typical examples of opaque extended attributes:

Extended attributes accessed through the DMAPI are distinct from any extended attribute facility the underlying file system may happen to provide. (If available, the DMAPI implementation may choose to use such a facility to provide DMAPI attributes, but doing so is not required.)

The DMAPI provides mechanisms for storage of both opaque and non-opaque per-file attributes. Persistence of opaque attributes across reboots is a DMAPI implementation option. DM applications should use the dm_get_config() function to determine what the implementation provides.


Holes in a file can be created in two ways. First, as defined by POSIX 1003.1 - 1990:

The lseek() function shall allow the file offset to be set beyond the end of existing data in the file. If data is later written at this point, subsequent reads of data in the gap shall return bytes with the value zero until data is actually written into the gap.

Holes can also be created by the dm_punch_hole() operation. It is the intent of this specification that a file system optimize the representation of holes so that large holes can be represented without consuming media resources. Most hierarchical-storage style DM application implicitly require the ability of a file system to represent at least one hole (covering the entire file) efficiently.

DMAPI Implementation Options

An implementation of the DMAPI may support optional components of this specification. The specifics of what optional components are implemented can be obtained by the dm_get_config() function. The dm_get_config() function returns, for a file system, whether the following optional functions are supported:

dm_get_config() also returns the implementation's limits on various functions:

If an implementation does not support an optional function, [ENOSYS] will be returned to any calls made.

The dm_init_service() function also returns vendor defined version information. This should contain additional information on the specific DMAPI implementation, such as platform, the supported DMAPI specification version, and a vendor version identifier. A DMAPI implementation should provide information on how to interpret the return value from dm_init_service().

Why not acquire a nicely bound hard copy?
Click here to return to the publication details or order a copy of this publication.

Contents Next section Index