Overview

Scope and Purpose

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

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.

Tokens

Access Rights

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 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.

Handles

Sessions

Data Management Attributes

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

• bitfile IDs

• 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 dm_get_config() function to determine what the implementation provides.

Holes

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

• the dm_get_bulkall() function

• creation-by-handle functions

• "legacy" handle functions

• non-blocking lock upgrades

• the dm_pending() function

• persistent, opaque attributes

• persistent event masks

• persistent inherited attributes

• persistent managed regions.

dm_get_config() 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.

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().