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
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.
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
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.
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:
starting offset in the file
length of the region
a set of event flags.
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:
location on secondary or tertiary storage
indication that portions of the file are non-resident
inheritable policy bits such as
lock on magnetic storage.
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
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
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
function returns, for a file system, whether the following optional functions
"legacy" handle functions
non-blocking lock upgrades
persistent, opaque attributes
persistent event masks
persistent inherited attributes
persistent managed regions.
also returns the implementation's limits on various functions:
maximum number of bytes returned for the attribute copy with destroy events
maximum size of persistent attributes, if supported
maximum handle size, if known
maximum number of managed regions per file
maximum number of bytes in user created event messages.
If an implementation does not support an optional function, [ENOSYS]
will be returned to any calls made.
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
Why not acquire a nicely bound hard copy?
Click here to return to the publication details or order a copy
of this publication.