Previous section.

Systems Management: Data Storage Management (XDSM) API

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

Data Structures

The DMAPI references a number of data structures that are presented here in alphabetical order. All of these structures can have additional vendor-specific fields unless otherwise stated. Many of the interfaces deal with variable length data, such as handles and path names. This data is encapsulated in the implementation defined dm_vardata_t structure, see the Implementation Notes section for one proposed definition. To access the data, the following functions are provided:
DM_GET_VALUE(p, field, type)

DM_GET_LEN(p, field)

Rationale:

The philosophy behind all the interfaces that deal with variable length data is to allow for such data to be embedded in the same buffer as the structure that contains a reference to it. The references are all relative to the start of the structure containing them, so that buffers containing such structures can be copied without destroying the embedded references. The expectation is that the variable length data will most commonly be appended directly after the structure that references it, but the dm_vardata_t interface does not demand this spatial relationship. However, the interfaces that return variable length data are designed (and implicitly specified) so that this spatial relationship does hold for the information they return.

To access fields within a variable length structure, the DM application must use the macros defined above. For example, to get at the handle in an event message, the following code could be used:

dm_eventmsg_t      *msg = malloc(bufsize);
dm_data_event_t    *event;

dm_get_events(sid, ....msg,...); event = DM_GET_VALUE(msg, data, dm_data_event_t *); hanp = DM_GET_VALUE(event, handle, void *); hlen = DM_GET_LEN(event, handle);

A number of DMAPI functions return lists of variable length structures. To move from one structure to the next in a list, the following macro should be used:

#define DM_STEP_TO_NEXT(struct_ptr, struct_type) 

A suggested implementation of the DM_STEP_TO_NEXT macro is given under Structure Lists .

The following table shows the affected structures:

Structure Name
dm_attrlist_t
dm_dispinfo_t
dm_eventmsg_t
dm_stat_t

Table: Structures used in Lists

The DM_STEP_TO_NEXT macro can be used as shown in the following example:

dm_stat_t    *statbuf = malloc(bufsize);
dm_stat_t    *sbufp;

dm_init_attrloc(...) dm_get_bulkattr(sid, ...statbuf);

sbufp = statbuf; while (sbufp != NULL) { ...... sbufp = DM_STEP_TO_NEXT(sbufp, dm_stat_t *); }

dm_attrlist_t

SYNOPSIS
struct dm_attrlist {
    dm_attrname_t    al_name;
    dm_vardata_t     al_data;
};
typedef struct dm_attrlist    dm_attrlist_t;

DESCRIPTION

A dm_attrlist_t pointer is passed to dm_getall_dmattr() to retrieve all persistent data management attributes associated with the specified file. The data structure includes, but is not limited to, the fields described above.

Since attributes may have different size data fields, use the DM_GET_VALUE and DM_GET_LEN macros to interpret the al_data field. All attribute names are fixed length 8 byte (defined as DM_ATTR_NAME_SIZE) opaque values.

Each attribute may store up to DM_CONFIG_MAX_ATTRIBUTE_SIZE bytes of data per file. The value of DM_CONFIG_MAX_ATTRIBUTE_SIZE is obtained via dm_get_config() and has a lower bound of 32 bytes. The total amount of space available for storage of all persistent attributes on a file system is bounded by DM_CONFIG_TOTAL_ATTRIBUTE_SPACE.

dm_attrloc_t

DESCRIPTION

An opaque scalar that is used in the dm_get_bulkattr() and dm_init_attrloc() functions.

dm_attrname_t

SYNOPSIS
struct dm_attrname {
    u_char an_chars[DM_ATTR_NAME_SIZE]; 
};
typedef struct dm_attrname    dm_attrname_t;

DESCRIPTION

This is used by the data management attribute functions to identify an attribute. All attribute names are fixed length 8 byte (defined as DM_ATTR_NAME_SIZE) opaque values.

It is recommended that applications use printable eight character names (or pad smaller names with the NULL character) to simplify display of attributes names and use a predefined three byte prefix as specified in section 3.10.2.

dm_boolean_t

DESCRIPTION

An opaque scalar that can contain either DM_TRUE or DM_FALSE.


dm_config_t

REQUIREMENT

This enumeration must contain at least the elements listed here. The DMAPI implementation may choose a different order for the elements.

SYNOPSIS
typedef enum {
    DM_CONFIG_INVALID,
    DM_CONFIG_BULKALL,
    DM_CONFIG_CREATE_BY_HANDLE,
    DM_CONFIG_DTIME_OVERLOAD,
    DM_CONFIG_LEGACY,
    DM_CONFIG_LOCK_UPGRADE,
    DM_CONFIG_MAX_ATTR_ON_DESTROY,
    DM_CONFIG_MAX_ATTRIBUTE_SIZE,
    DM_CONFIG_MAX_HANDLE_SIZE,
    DM_CONFIG_MAX_MANAGED_REGIONS,
    DM_CONFIG_MAX_MESSAGE_DATA,
    DM_CONFIG_OBJ_REF,
    DM_CONFIG_PENDING,
    DM_CONFIG_PERS_ATTRIBUTES,
    DM_CONFIG_PERS_EVENTS,
    DM_CONFIG_PERS_INHERIT_ATTRIBS,
    DM_CONFIG_PERS_MANAGED_REGIONS,
    DM_CONFIG_PUNCH_HOLE,
    DM_CONFIG_TOTAL_ATTRIBUTE_SPACE,
    DM_CONFIG_WILL_RETRY
} dm_config_t;

DESCRIPTION

Enums from dm_config_t are used in dm_get_config() calls to query various options pertaining to the implementation of the DMAPI.

dm_dispinfo_t

SYNOPSIS
struct dm_dispinfo {
    dm_vardata_t     di_fshandle;
    dm_eventset_t    di_eventset;
};
typedef struct dm_dispinfo    dm_dispinfo_t;

DESCRIPTION

The dm_dispinfo_t structure is used on calls to dm_getall_disp() to retrieve the list of all event dispositions for all file systems for a given session. DM applications should use the DM_GET_VALUE macro to retrieve the value of the filesystem handle and DM_STEP_TO_NEXT to move between successive structures.

Event Message Types

dm_eventmsg_t

SYNOPSIS
struct dm_eventmsg {
    dm_eventtype_t    ev_type;
    dm_token_t        ev_token;
    dm_sequence_t     ev_sequence;
    dm_vardata_t      ev_data;
};
typedef struct dm_eventmsg    dm_eventmsg_t;

DESCRIPTION

Every event message is of type dm_eventmsg_t. Since multiple messages can be returned in a single call, DM applications must use the DM_STEP_TO_NEXT macro to move from one message to the next.

All event messages contain an event type. Synchronous messages also contain a token. The dm_eventmsg_t structure represents this common data via the ev_type and ev_token fields. Asynchronous messages never have a token associated with them; therefore ev_token will always be DM_INVALID_TOKEN for asynchronous messages.

The rest of the contents of the message for a given event is distinct for an event's type, and will be contained in a dm_xxx_event buffer, where xxx depends on the event type. As with other data whose size or type isnt known in advance, it is referred to through the DM_GET_VALUE macro applied to a descriptor field that lives in the common prelude part of the event message.

ev_type

The event type that occurred.

ev_token

The token may reference and identify a specific access right for a handle in the event-specific portion of the message. When responding to the message, the token is used to identify the message and is no longer valid when the response call dm_respond_event() has completed. The token field is valid for synchronous messages only; the field will be DM_INVALID_TOKEN for asynchronous event messages.

ev_sequence

This is a sequence identifier for the event message. If the implementation supports the cancel event, the value of this sequence identifier must be unique in the event stream. A subsequent cancel event may refer to this event using the value of this sequence identifier. The contents of this field is not specified if the cancel event is not supported.

ev_data

The event-specific data.

dm_cancel_event_t

SYNOPSIS
struct dm_cancel_event {
    dm_sequence_t    ce_sequence;
    dm_token_t       ce_token;
};
typedef struct dm_cancel_event    dm_cancel_event_t;

DESCRIPTION

The dm_cancel_event structure is used for the cancel event message type.

dm_data_event_t

SYNOPSIS
struct dm_data_event {
    dm_vardata_t    de_handle;
    dm_off_t        de_offset;
    dm_size_t       de_length;
};
typedef struct dm_data_event    dm_data_event_t;

DESCRIPTION

The dm_data_event structure is used for all data events.

dm_destroy_event_t

SYNOPSIS
struct dm_destroy_event {
    dm_vardata_t     ds_handle;
    dm_attrname_t    ds_attrname;
    dm_vardata_t     ds_attrcopy;
};
typedef struct dm_destroy_event    dm_destroy_event_t;

DESCRIPTION

The dm_destroy_event structure is used for the destroy event.

dm_mount_event_t

SYNOPSIS
struct dm_mount_event {
    mode_t          me_mode;
    dm_vardata_t    me_handle1;
    dm_vardata_t    me_handle2;
    dm_vardata_t    me_name1;
    dm_vardata_t    me_name2;
    dm_vardata_t    me_roothandle;
};
typedef struct dm_mount_event     dm_mount_event_t;

DESCRIPTION

The dm_mount_event structure is used for the mount event.

dm_namesp_event_t

SYNOPSIS
struct dm_namesp_event {
    mode_t          ne_mode;
    dm_vardata_t    ne_handle1;
    dm_vardata_t    ne_handle2;
    dm_vardata_t    ne_name1;
    dm_vardata_t    ne_name2;
    int             ne_retcode;
};
typedef struct dm_namesp_event    dm_namesp_event_t;

DESCRIPTION

The dm_namesp_event structure is used for all namespace events.

dm_eventset_t

DESCRIPTION

To specify events, the dm_eventset_t type must be used. This is an opaque type (to the DM application) that is manipulated via the DMEV_ZERO, DMEV_SET and DMEV_CLR macros in a manner analogous to the FD_SET type that is used in calls to select(2).

dm_eventtype_t

REQUIREMENT

This enumeration must contain at least the elements listed here. The DMAPI implementation may choose a different order for the elements.

SYNOPSIS
typedef enum {
    DM_EVENT_INVALID,
    DM_EVENT_CLOSE,
    DM_EVENT_MOUNT,    
    DM_EVENT_PREUNMOUNT,    DM_EVENT_UNMOUNT,
    DM_EVENT_NOSPACE, 
    DM_EVENT_DEBUT,
    DM_EVENT_CREATE,        DM_EVENT_POSTCREATE,
    DM_EVENT_REMOVE,        DM_EVENT_POSTREMOVE,
    DM_EVENT_RENAME,        DM_EVENT_POSTRENAME,
    DM_EVENT_SYMLINK,       DM_EVENT_POSTSYMLINK,
    DM_EVENT_LINK,          DM_EVENT_POSTLINK,
    DM_EVENT_READ,
    DM_EVENT_WRITE,
    DM_EVENT_TRUNCATE,
    DM_EVENT_ATTRIBUTE,
    DM_EVENT_CANCEL,
    DM_EVENT_DESTROY,
    DM_EVENT_USER,
    DM_EVENT_MAX
} dm_eventtype_t;


DESCRIPTION

Event types are encoded in message structures and dm_eventset_t types as dm_eventtype_t enums. DM_EVENT_MAX is guaranteed to be larger than the number of the largest valid event type that can be represented in the dm_eventset_t type. DM_EVENT_INVALID is guaranteed to be smaller than the number of the smallest valid event type that can be represented in the dm_eventset_t type.

dm_extent_t

SYNOPSIS
struct dm_extent {
    dm_extenttype_t     ex_type;
    dm_off_t            ex_offset;
    dm_size_t           ex_length;
};
typedef struct dm_extent    dm_extent_t;

DESCRIPTION

The extent structures returned by the call to dm_get_allocinfo() contains the ex_type field, whose value is one of two indicators for the type of extent. If a DMAPI implementation can know that an extent of a file would be read as zeros, for example because no media resources are mapped to that extent of the file, it should indicate that knowledge about the extent by associating DM_EXTENT_HOLE with that extent. Otherwise, the value DM_EXTENT_RES should be associated with that extent. The ex_offset field is the byte offset into the file where the extent begins, and ex_length is the byte count of the extent.

dm_extenttype_t

SYNOPSIS
typedef enum {
    DM_EXTENT_INVALID,
    DM_EXTENT_RES,
    DM_EXTENT_HOLE
} dm_extenttype_t;

DESCRIPTION

The dm_extenttype_t enum is used to specify the type of extent in the dm_extent_t structure.


dm_fileattr_t

SYNOPSIS
struct dm_fileattr {
    mode_t      fa_mode;
    uid_t       fa_uid;
    gid_t       fa_gid;
    time_t      fa_atime;
    time_t      fa_mtime;
    time_t      fa_ctime;
    time_t      fa_dtime;
    dm_off_t    fa_size;
} ;
typedef struct dm_fileattr dm_fileattr_t;

DESCRIPTION

These are the fields that can be modified by dm_set_fileattr().

DM Handles

SYNOPSIS
    void      *hanp;
    size_t     hlen;

DESCRIPTION

Handles are opaque to DM applications. The length of a handle is implementation defined. When a handle must be used in a function, it is specified using two parameters. The hlen parameter specifies the length of the opaque data that is pointed to by hanp.

When a handle is embedded in a structure, the dm_vardata_t structure is used. The DM application should use the DM_GET_VALUE macro to access the handle data and DM_GET_LEN to determine the length of the opaque handle data.

dm_fsid_t

DESCRIPTION

This is a scalar used to represent a file system identifier.

dm_igen_t

DESCRIPTION

This is a scalar used to represent a file inode generation number.

dm_inherit_t

SYNOPSIS
struct dm_inherit {
    dm_attrname_t    ih_name ;
    mode_t           ih_filetype;
};
typedef struct dm_inherit    dm_inherit_t;

DESCRIPTION

A dm_inherit_t pointer is passed to dm_getall_inherit() to retrieve all data management attributes that have been made inheritable through the dm_set_inherit() function. The call is made on a per file system basis. The ih_filetype field is the type of the file as defined in Single UNIX Specification.

dm_msgtype_t

SYNOPSIS
typedef enum {
    DM_MSGTYPE_INVALID,
    DM_MSGTYPE_SYNC, 
    DM_MSGTYPE_ASYNC
} dm_msgtype_t;

DESCRIPTION

This is used when creating a user event via dm_send_msg() to specify the type of event message that should be created, synchronous or asynchronous.

dm_off_t

DESCRIPTION

This is a signed scalar used to represent file offsets.

Rationale:
Vendors have taken different approaches for extending file addressibility beyond the off_t type, which is usually 32 bits. For example, some vendors have an offset_t type or an off64_t type for working with files larger than 2GB.

The intent is that dm_off_t be a suitable type for addressing all files supported by the system.

dm_region_t

SYNOPSIS
struct dm_region {
    dm_off_t     rg_offset;
    dm_size_t    rg_size;
    u_int        rg_flags;
};
typedef struct dm_region    dm_region_t;

DESCRIPTION

The dm_region structure defines the range of bytes that are managed in the file. The rg_flags field can be set to generate synchronous read, write, and truncate events whenever the associated operation is performed within the managed region. A region may extend outside the current valid portions of a file. If rg_size is set to zero, then that region extends from rg_offset through EOF and beyond. Thus operations beyond the end of file, including appends and sparse writes, will generate events according to the flag setting. This means that the rg_flags field must always be set to a valid state. Regions may also be allocated with no associated events set by using DM_REGION_NOEVENT. This may be used to allocate space for future control of a region of the file in DMAPI implementations that provide persistent managed regions.

Valid values for the rg_flags field are as follows:

DM_REGION_READ

Generate synchronous event for read operations that overlap this managed region

DM_REGION_WRITE

Generate synchronous event for write operations that overlap this managed region

DM_REGION_TRUNCATE

Generate synchronous event for truncate operations that overlap this managed region

DM_REGION_NOEVENT

Do not generate any events for this managed region.

Region Flags

DEFINES
#define DM_REGION_NOEVENT     xxx
#define DM_REGION_READ        xxx
#define DM_REGION_WRITE       xxx
#define DM_REGION_TRUNCATE    xxx

DESCRIPTION

The defines above are used to specify the generation of events in the rg_flags field of the managed region structure. DM_REGION_READ, DM_REGION_WRITE and DM_REGION_TRUNCATE may be ORed together.

dm_response_t

REQUIREMENT

This enumeration must contain at least the elements listed here. The DMAPI implementation may choose a different order for the elements.

SYNOPSIS
typedef enum {
    DM_RESP_INVALID,
    DM_RESP_CONTINUE,    
    DM_RESP_ABORT,
    DM_RESP_DONTCARE
} dm_response_t;

DESCRIPTION

When a DM application responds to an event via dm_respond_event(), the response codes must be an enum taken from dm_response_t.

dm_right_t

SYNOPSIS
typedef enum {
    DM_RIGHT_NULL, 
    DM_RIGHT_SHARED,
    DM_RIGHT_EXCL
} dm_right_t;

DESCRIPTION

The dm_right_t enum specifies the access rights for an object.

dm_sequence_t

DESCRIPTION:

This is an unsigned scalar used to represent one of a sequence of event messages for message cancellation.

dm_sessid_t

DESCRIPTION:

The session ID is an opaque scalar. Implementations of the DMAPI may differ in the information they require to be stored with the session ID. A special value, DM_NO_SESSION, is available for use as an invalid or non-existent session.

dm_size_t

DESCRIPTION

This is an unsigned scalar used to represent sizes of extents within files (among other things).

dm_ssize_t

DESCRIPTION

This is a signed scalar used for function calls that return the size of the file or -1 to indicate error.

dm_stat_t

SYNOPSIS
struct dm_stat {
    dm_vardata_t     dt_handle;
    dm_vardata_t     dt_compname;
    dm_eventset_t    dt_emask;
    int              dt_nevents;
    int              dt_pers;
    int              dt_pmanreg;
    time_t           dt_dtime;
    u_int            dt_change;

    dev_t            dt_dev;
    ino_t            dt_ino;
    mode_t           dt_mode;
    nlink_t          dt_nlink;
    uid_t            dt_uid;
    gid_t            dt_gid;
    dev_t            dt_rdev;
    dm_off_t         dt_size;
    time_t           dt_atime;
    time_t           dt_mtime;
    time_t           dt_ctime;
    u_int            dt_blksize;
    dm_size_t        dt_blocks;
};
typedef struct dm_stat    dm_stat_t;

DESCRIPTION

The dm_stat structure is used for retrieving per file attributes via the dm_get_fileattr(), dm_get_dirattrs() and dm_get_bulkattr() functions. The structure is composed of at least fields found in the Single UNIX Specification struct stat as well as additional DMAPI specific fields.

Since handles are variable length, the structure is somewhat problematic as dm_get_bulkattr() can return a variable number of variable length structures. To access the variable length data in an individual structure, the DM_GET_VALUE macro should be used. To move between structures, the DM_STEP_TO_NEXT macro is used.

The dm_stat structure contains at least the following fields:

dt_handle

A dm_vardata_t structure that contains the offset from the beginning of the structure where the data for the handle begins. The DM_GET_VALUE macro should be used to access the handle.

dt_compname

A dm_vardata_t structure that contains the offset from the beginning of the structure where the name of the file begins. This field is valid only for dm_get_dirattrs(). The DM_GET_VALUE macro should be used to access the file name.

dt_emask

The event bindings that are stored persistently with the file. The event types in this set can be manipulated by the dm_set_eventlist() functions.

Not all DMAPI implementations support persistent event bindings. Support can be determined through use of the dm_get_config() function.

dt_nevents

The number of events in the event mask, dt_emask.

dt_pers

A boolean indicating whether the file does or does not have associated persistent opaque data management attributes. A non-zero value indicates presence of persistent attributes.

dt_pmanreg

A boolean indicating whether the file does or does not have associated persistent managed regions. A non-zero value indicates presence of persistent managed regions.

dt_dtime

The value of the data management attribute time stamp if dt_pers is a non-zero value. This field may be the same as ctime as determined by calling dm_get_config() with DM_CONFIG_DTIME_OVERLOADED.

This field will be set to zero if persistent attributes are not supported by the DMAPI or associated with this file.

dt_change

This field is a file change indicator that is changed on each file modification (of either data or metadata) and on each persistent attribute change. It can be used by DM applications during lock upgrade to determine whether the file has changed state. If the same value is returned in dt_change between two calls, the file is guaranteed not to have changed; however, some implementations of the DMAPI may return a different dt_change value even if the file has not really been modified.

The following fields are taken from the Single UNIX Specification struct stat.

dt_dev

ID of device containing file

dt_ino

File serial number

dt_mode

Mode of file

dt_nlink

Number of links to the file

dt_uid

User ID of file

dt_gid

Group ID of file

dt_rdev

Device ID (if file is character/block special)

dt_size

File size in bytes (if file is regular file)

dt_atime

Time of last access

dt_mtime

Time of last data modification

dt_ctime

Time of last status change

dt_blksize

A file system specific preferred I/O block size for this object. In some file system types, this may vary from file to file.

dt_blocks

Number of blocks of a file system-specific size allocated for this object.

dm_timestruct_t

SYNOPSIS
struct dm_timestruct {
    time_t   dm_tv_sec; 
    int32    dm_tv_nsec; 
};
typedef struct dm_timestruct dm_timestruct_t;

DESCRIPTION

A dm_timestruct_t is the structure passed to dm_pending(), used to represent an interval of time in seconds and nanoseconds. It contains at least the following information:

dm_tv_sec

dm_tv_nsec

dm_token_t

DESCRIPTION

A dm_token_t is an opaque scalar. There are two distinguished values, DM_NO_TOKEN, which signifies automatic token acquisition, and DM_INVALID_TOKEN, which signifies no legal value.

dm_vardata_t

DESCRIPTION

A dm_vardata_t is an opaque structure. Implementations of the DMAPI may differ in the information they require to be stored in a variable length data structure. Use the macros as mentioned at the beginning of this chapter to access dm_vardata_t fields. See the Implementation Notes chapter for an example definition of the dm_vardata_t structure and its access macros.

dm_xstat_t

SYNOPSIS
struct dm_xstat {
    dm_stat_t       dx_statinfo;
    dm_vardata_t    dx_attrdata;
};
typedef struct dm_xstat    dm_xstat_t;

DESCRIPTION

The dm_xstat structure is used for retrieving per file attributes and one persistent data management attribute via dm_get_bulkall(). The data structure includes, but is not limited to, the fields described above.

The dm_xstat structure contains at least the following fields:

dx_statinfo
The dm_stat_t structure

dx_attrdata
The attribute data for the object as set by dm_set_dmattr() on the object.

Attribute Mask Defines

DEFINES
#define DM_AT_ATIME        xxx
#define DM_AT_CFLAG        xxx
#define DM_AT_CTIME        xxx
#define DM_AT_DTIME        xxx
#define DM_AT_EMASK        xxx
#define DM_AT_GID          xxx
#define DM_AT_HANDLE       xxx
#define DM_AT_MODE         xxx
#define DM_AT_MTIME        xxx
#define DM_AT_PATTR        xxx
#define DM_AT_PMANR        xxx
#define DM_AT_SIZE         xxx
#define DM_AT_STAT         xxx
#define DM_AT_UID          xxx

DESCRIPTION

The #defines shown above are used by the dm_get_bulkall(), dm_get_bulkattr(), dm_get_dirattrs(), dm_get_fileattr() and dm_set_fileattr() functions. They are OR-able flags. For descriptions of these flags, see the man-page definitions for these functions. in DMAPI Definitions .

Get Events Defines

DEFINES
#define DM_EV_WAIT        xxx

DESCRIPTION

There is currently one definition used for retrieving DM messages via dm_get_events(). This definition is an OR-able flag. Refer to the dm_get_events() reference manual page for a description of this flag.

Mount Event Defines

DEFINES
#define DM_MOUNT_RDONLY        xxx

DESCRIPTION

The possible flags contained in the me_mode field of the dm_mount_event structure during the mount event. These definitions are OR-ed flags. The DM_MOUNT_RDONLY flag is set when the mount command is run with the read-only option set.

Request Right Defines

DEFINES
#define DM_RR_WAIT        xxx

DESCRIPTION

There is currently one definition used for requesting rights via dm_request_right(). This definition is an OR-able flag. Refer to the dm_request_right() reference manual page for a description of this flag.

Unmount Event Defines

DEFINES
#define DM_UNMOUNT_FORCE    xxx

DESCRIPTION

The possible flags contained in the ne_mode field of the dm_namesp_event structure during the preunmount and unmount events. These definitions are OR-ed flags. The DM_UNMOUNT_FORCE flag is set when the unmount command is run with the force unmount option set.

Invisible Write Defines

DEFINES
#define DM_WRITE_SYNC        xxx

DESCRIPTION

There is currently one flag definition for the flags parameter to dm_write_invis(). This definition is an OR-able flag. Refer to the dm_write_invis() reference manual page for a description of this flag.

Miscellaneous Defines

DEFINES
#define DM_SESSION_INFO_LEN    xxx
#define DM_NO_SESSION          xxx

#define DM_TRUE                xxx
#define DM_FALSE               xxx
 
#define DM_INVALID_TOKEN       xxx
#define DM_NO_TOKEN            xxx

#define DM_INVALID_HANP        xxx
#define DM_INVALID_HLEN        xxx

#define DM_GLOBAL_HANP         xxx
#define DM_GLOBAL_HLEN         xxx

#define DM_VER_STR_CONTENTS    xxx

#define DM_ATTR_NAME_SIZE      8

DESCRIPTION

The #defines shown above are referenced by various DMAPI functions. The DMAPI does not mandate their value, as is indicated by the xxx. Each implementation of the DMAPI is free to chose a suitable value.

DM_SESSION_INFO_LEN is the length of the string that can be associated with the session on the dm_create_session() call. 256 bytes is the recommended length.

DM_NO_SESSION is used on dm_create_session() to indicate that session assumption is not wanted. The implementation of the DMAPI should choose a meaningful value.

DM_TRUE and DM_FALSE are boolean values used in several functions such as dm_get_bulkattr() and dm_get_fileattr().

DM_INVALID_TOKEN is a special token value which signifies no legal token value.

DM_NO_TOKEN is a special token value which is used in calls to functions that require a token but the caller wants the DM implementation to automatically acquire the appropriate rights.

DM_INVALID_HANP and DM_INVALID_HLEN are used to specify invalid handles.

DM_GLOBAL_HANP and DM_GLOBAL_HLEN are used to specify the global handle.

DM_VER_STR_CONTENTS specifies the DMAPI implementation specific version string as returned from the dm_init_service() function.

DM_ATTR_NAME_SIZE specifies the fixed length of an attribute name in bytes.


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