DMAPI Definitions

(I)

indicates an input parameter

(O)

indicates an output parameter

(I/O)

indicates both an input and an output parameter.

Many of the following functions reference data structures that are defined by the DMAPI. To provide a consistent API from platform to platform, these data structures are defined in a header file named <dmapi.h>. DM applications that need to use these functions must include this header file. The specification of this header file is not shown on the following function definitions, but is of the following format:

#include <dmapi.h>

There are two paradigms used for DMAPI functions:

• iterative
  which allow DM applications to make repeated calls to the same function to obtain all available data

• non-iterative
  which require a DM application to provide a buffer large enough to hold all available data in a single call.

The error conditions specified in these man-pages are the recommended values. A DMAPI implementation may recognize and report additional error conditions.

A number of the functions are optional in the DMAPI specification. It is left to an implementation as to whether those optional functions are supported. If an optional function is not supported, it must still be implemented as a stub function that returns -1 and sets errno to ENOSYS. A DM application can use the dm_get_config() function to also determine which optional functions are supported by an implementation rather than having to first call the function and check for ENOSYS.

Non-iterative Functions

There are two distinct flavors of the E2BIG paradigm:

• functions which return variable sized data structures

• functions which return a variable number of fixed size structures.

Generally, functions that return variable sized structures specify the size of the input buffer in bytes via the buflen parameter. If E2BIG is returned, then the parameter rlenp is set to the required buffer size. These types of functions take a void * pointer to a buffer.

Functions that return fixed size structures specify the number of elements that fit in the input buffer, via the nelem parameter. If [E2BIG] is returned, the nelemp parameter is updated to indicate the number of elements that are available. DM applications can use this return value to resize their buffer. These types of functions take a buffer pointer to a specific type.

This is summarized in the following table:

Table: Non-iterating Function Types

Iterating Functions

These functions return -1 on error and set the global errno to indicate the cause of error. If a zero is returned, the function completed successfully, and no more data is available. If the function completed successfully, but more data maybe available, a value of 1 is returned.

The following functions are the only iterating functions:

Table: Iterating Functions

DMAPI Macros

DMEV_CLR

remove an event from an event list

DMEV_ISSET

determine if an event is set in an event list

DMEV_SET

add an event to an event list

DMEV_ZERO

initialize the event list to contain no events

NAME

DMEV_CLR - remove an event from an event list
DMEV_ISSET - determine if an event is set in an event list
DMEV_SET - add an event to an event list
DMEV_ZERO - initialize the event list to contain no events

SYNOPSIS

int
DMEV_SET(
    dm_eventtype_t    event_type,
    dm_eventset       event_list)

int
DMEV_CLR(
    dm_eventtype_t    event_type,
    dm_eventset       event_list)

int
DMEV_ISSET(
    dm_eventtype_t    event_type,
    dm_eventset       event_list)

void
DMEV_ZERO(
    dm_eventset       event_list)

DESCRIPTION

These macros manipulate event sets as defined by dm_eventset_t. DMEV_SET() adds the specified event_type to the event_list set, while DMEV_CLR() removes the specified event from the list. DMEV_ISSET() evaluates to non-zero if the specified event_type is a member of the event_list set, otherwise it evaluates to zero. DMEV_ZERO() initializes the event_list set to contain no events.

SEE ALSO

dm_get_eventlist(), dm_set_eventlist().

DMAPI Functions

In some cases, a single reference manual page definition covers several functions. These cases are identified in column 2 of DMAPI Functions . In these cases, the man-page title is stylized to reflect the functions it covers. In addition, where space for this title on the man-page does not allow the function names to be concatenated, a descriptive name reflecting the nature of the common operation is enclosed in braces "{ }".

Table: DMAPI Functions

NAME

dm_clear_inherit - clear an attribute's inherit-on-create status

SYNOPSIS

int
dm_clear_inherit(
    dm_sessid_t     sid,
    void           *hanp,
    size_t          hlen,
    dm_token_t      token,
    dm_attrname_t  *attrnamep)

DESCRIPTION

The dm_clear_inherit() function marks the named attribute as no longer inheritable on the specified file system.

dm_sessid_t sid (I)

The identifier for the session of interest.

void *hanp (I)

The filesystem handle.

size_t hlen (I)

The length of the handle in bytes.

dm_token_t token (I)

The token referencing the access right for the file system handle. The access right must be DM_RIGHT_EXCL or the token DM_NO_TOKEN may be used and the interface acquires the appropriate rights.

dm_attrname_t *attrnamep (I)

The attribute name that marks the name as no longer inheritable.

RETURN VALUE

Zero is returned on success. On error, -1 is returned, and the global errno is set to one of the following values:

[EACCES]

The access right referenced by the token for the handle is not DM_RIGHT_EXCL.

[EBADF]

The filesystem handle does not refer to an existing or accessible object.

[EFAULT]

The system detected an invalid address in attempting to use an argument.

[EINVAL]

The argument attrname specifies an attribute that has not been marked inheritable.

[EINVAL]

The argument token is not a valid token.

[EINVAL]

The session is not valid.

[EIO]

The attempt to clear the inheritable attribute resulted in an I/O error.

[ENOSYS]

The DMAPI implementation does not support this optional function.

[EPERM]

The caller does not hold the appropriate privilege.

SEE ALSO

dm_set_inherit(), dm_getall_inherit().

NOTES

dm_clear_inherit() is an optional component of the DMAPI.

NAME

dm_create_by_handle - create a file system object using a DM handle

SYNOPSIS

int
dm_create_by_handle(
    dm_sessid_t    sid,
    void          *dirhanp,
    size_t         dirhlen,
    dm_token_t     token,
    void          *hanp,
    size_t         hlen,
    char          *cname)

DESCRIPTION

The dm_create_by_handle() function allows applications the ability to create an object in a directory specified by dirhanpandwithacomponentnamespecifiedby cname that can, after creation, be referenced by the supplied target handle hanp. This is useful when an application is reconstructing a file system object for which it still has the data and attributes stored on an alternate media.

It is the responsibility of the user of this function to reconstruct the object state including extended attributes. See dm_set_fileattr() and dm_set_dmattr().

If an object cannot be constructed by the file system for the specified handle, an error is returned.

dm_sessid_t sid (I)

The identifier for the session of interest.

void *dirhanp (I)

The handle for the directory that contains the target file.

size_t dirhlen (I)

The length of the directory handle in bytes.

dm_token_t token (I)

The token referencing the access right for the directory handle. The access right must be DM_RIGHT_EXCL right or the token DM_NO_TOKEN may be used and the interface acquires the appropriate rights.

void *hanp (I)

The file handle of the object.

size_t hlen (I)

The length of the file handle in bytes.

char *cname (I)

The name of the object to be created in the specified directory.

RETURN VALUE

Zero is returned on success. On error, -1 is returned, and the global errno is set to one of the following values:

[EACCES]

The access right referenced by the token for the directory handle is not DM_RIGHT_EXCL.

[EBADF]

The parent handle does not refer to an existing or accessible object.

[EEXIST]

The file handle refers to an existing object.

[EFAULT]

The system detected an invalid address in attempting to use an argument.

[EINVAL]

The argument token is not a valid token.

[EINVAL]

The session is not valid.

[ENOSYS]

The DMAPI implementation does not support this optional function.

[EPERM]

The caller does not hold the appropriate privilege.

SEE ALSO

dm_set_fileattr(), dm_set_dmattr(), dm_mkdir_by_handle(), dm_symlink_by_handle().

NOTES

edm_create_by_handle() is an optional component of the DMAPI.

NAME

dm_create_session - create a session

SYNOPSIS

int
dm_create_session(
    dm_sessid_t    oldsid,
    char          *sessinfop,
    dm_sessid_t   *newsidp)

DESCRIPTION

The dm_create_session() function establishes a DMAPI session. Sessions are guaranteed to be unique as long as the system that grants them is up; sessions are not unique across reboots. Applications should treat the session id as opaque.

To later identify the session during recovery, an arbitrary string can be associated with the session. This NULL-terminated string must have a length of DM_SESSION_INFO_LEN bytes (including the NULL) or less. The sessinfop parameter is an arbitrary string; the DMAPI assigns no semantics to it whatsoever. It is not an error for more than one session to have identical sessinfop strings.

To support recovery, the DMAPI supports the notion of session assumption. This is provided by the oldsid parameter. If specified, the DMAPI atomically updates all messages that refer to oldsid to be associated with a new session id, which is returned to the caller. When dm_create_session() returns, oldsid is no longer valid; attempts to use it in subsequent DMAPI calls result in an error.

To determine a previous session identifier, the DM application can use dm_getall_sessions() and dm_query_session() to find a specific old session identifier. If oldsid is provided, then when dm_create_session() returns, the new session has assumed what was an active, open session. It is not necessary to register to receive events; the new session has assumed the context of the previous session, including all default event registrations. If a sessinfop string is provided, it replaces any existing sessinfop string associated with the old session.

Sessions are not tied to a particular process. Once a session has been established, any processes with sufficient permissions (such as the super-user) may use the session. This permits an application to hand a session off to another process for further operations. The hand off can be accomplished merely by conveying the value of the session ID to the other process via any mechanism (shared memory, message, pipe, file, etc.). Because sessions are not tied to any particular process, no DMAPI calls are needed to accomplish session hand off.

dm_sessid_t oldsid (I)

A value previously returned by dm_create_session(), or DM_NO_SESSION if no assumption is desired.

char *sessinfop (I)

A NULL-terminated string of at most DM_SESSION_INFO_LEN to be associated with the session.

dm_sessid_t *newsidp (O)

The new session id created by the DMAPI.

RETURN VALUE

Zero is returned on success. On error, -1 is returned, and the global errno is set to one of the following values:

[E2BIG]

sessinfop string was longer than DM_SESSION_INFO_LEN bytes.

[EFAULT]

The system detected an invalid address in attempting to use an argument.

[ENOMEM]

The DMAPI could not obtain the required resources to complete the call.

[EINVAL]

The argument oldsid contains an invalid session id.

[EPERM]

The caller does not hold the appropriate privilege.

SEE ALSO

dm_destroy_session(), dm_set_disp(), dm_getall_sessions(), dm_query_session().

NAME

dm_create_userevent - generate a user pseudo-event message

SYNOPSIS

int
dm_create_userevent(
    dm_sessid_t    sid,
    size_t         msglen,
    void          *msgdatap,
    dm_token_t    *tokenp)

DESCRIPTION

Tokens are always associated with an event message. If a DM application needs to obtain a token to get specific access rights to an object, it must generate a pseudo-event message to define a context for that token.

DM applications can use the user defined message data to record information about the state of the operation they are performing. This information could be useful during recovery processing. The DMAPI implementation does not interpret the contents of the message data.

The dm_create_userevent() function allows a token to be associated with arbitrary message data. The DMAPI creates a new token, and associate it with an event message whose data is given by the msgp parameter. The message is enqueued on the specified session, and is in the same state as synchronous messages that have been received by DM applications via dm_get_events() but not yet responded to. The type of the message is set to be DM_EVENT_USER. The token is valid until the DM application does a dm_respond_event() on the token.

The generated token does not reference any access rights for any object handles. DM applications must use dm_request_right() to obtain access rights.

dm_sessid_t sid (I)

The identifier for the session of interest.

size_t msglen (I)

The length of the message data in bytes.

void *msgdatap (I)

The data that is to be included in the message.

dm_token_t *tokenp (O)

A newly created token identifying the message.

RETURN VALUE

Zero is returned on success. On error, -1 is returned, and the global errno is set to one of the following values:

[E2BIG]

The user message data is too big to fit into implementation defined limits. The limit can be determined by calling the dm_get_config() function using the value DM_CONFIG_MAX_MESSAGE_DATA.

[EFAULT]

The system detected an invalid address in attempting to use an argument.

[EINVAL]

The session is not valid.

[ENOMEM]

The DMAPI could not obtain the required resources to complete the call.

[EPERM]

The caller does not hold the appropriate privilege.

SEE ALSO

dm_request_right(), dm_send_msg().

NAME

dm_destroy_session - destroy the specified session

SYNOPSIS

int
dm_destroy_session(
    dm_sessid_t    sid)

DESCRIPTION

To perform a graceful shutdown, DM applications must shut down and destroy a session as part of their termination procedures. Upon successful return from dm_destroy_session() the session id is invalid.

If the file system is active or the session is registered for any events, dm_destroy_session() cannot invalidate the session id. If there are any outstanding or undelivered events, dm_destroy_session() will fail.

dm_sessid_t sid (I)

The session id to destroy.

RETURN VALUE

Zero is returned on success. On error, -1 is returned, and the global errno is set to one of the following values:

[EBUSY]

There are outstanding events for the session that have not been delivered, or there are synchronous events that have not been responded to.

[EINVAL]

The session is not valid.

[EPERM]

The caller does not hold the appropriate privilege.

SEE ALSO

dm_create_session()

NAME

dm_downgrade_right - downgrade an exclusive access right to a shared right

SYNOPSIS

int
dm_downgrade_right(
    dm_sessidt     sid,
    void          *hanp,
    size_t         hlen,
    dm_token_t     token)

DESCRIPTION

Downgrade an exclusive access right currently held for the object specified by the handle and referenced by the token. The downgrade operation does not drop the exclusive access right currently held for the object before acquiring the share right. The minimum right to hold when making this request is DM_RIGHT_EXCL.

dm_sessid_t sid (I)

The identifier for the session of interest.

void *hanp (I)

The handle for the file system object for which downgrading access right is being requested and with which an exclusive access right is already associated.

size_t hlen (I)

The length of the handle in bytes.

dm_token_t token (I)

The token referencing the exclusive access right for the object to be manipulated

RETURN VALUE

Zero is returned on success. On error, -1 is returned, and the global errno is set to one of the following values:

[EBADF]

The file handle does not refer to an existing or accessible object.

[EFAULT]

The system detected an invalid address in attempting to use an argument.

[EINVAL]

The token does not grant a DM_RIGHT_EXCL right to the specified object.

[ENOSYS]

The DMAPI implementation does not support this optional function.

[ESRCH]

The token does not refer to any outstanding DM event.

[EPERM]

The caller does not hold the appropriate privilege.

[EPERM]

The access right currently held is not DM_RIGHT_EXCL.

SEE ALSO

dm_release_right(), dm_request_right(), dm_upgrade_right().

NOTES

dm_downgrade_right() is an optional component of the DMAPI.

NAME

dm_find_eventmsg - get the message for the event

SYNOPSIS

int
dm_find_eventmsg(
    dm_sessid_t    sid,
    dm_token_t     token,
    size_t         buflen,
    void          *bufp,
    size_t        *rlenp)

DESCRIPTION

Obtains the message that is associated with the token. It is only possible to obtain messages that are outstanding, that is, messages that have been delivered but not responded to.

Tokens are always associated with an event message; receipt of a message is the only way a DM application can obtain a token. Once a message has been responded to, the token (and the corresponding message) is no longer valid.

dm_sessid_t sid (I)

The identifier for the session of interest.

dm_token_t token (I)

The token that corresponds to an outstanding event message.

size_t buflen (I)

The length of the message buffer in bytes.

void *bufp (O)

The buffer that should be filled in with a dm_eventmsg structure.

size_t *rlenp (O)

The size of the requested information. If the buffer is not large enough to hold the requested information (as indicated by the buflen parameter), then no data is copied, the call fails with [E2BIG], and rlenp is set to the required size. rlenp is updated if either the call was successful or the call fails with [E2BIG], but is undefined otherwise.

RETURN VALUE

Zero is returned on success. On error, -1 is returned, and the global errno is set to one of the following values:

[E2BIG]

The information is too large to fit into the buffer.

[EFAULT]

The system detected an invalid address in attempting to use an argument.

[EINVAL]

The session or token is not valid.

[ENOMEM]

The DMAPI could not obtain the required resources to complete the call.

[EPERM]

The caller does not hold the appropriate privilege.

SEE ALSO

dm_getall_tokens),() dm_getall_sessions(), dm_respond_event(), dm_query_session().

NAME

dm_get_allocinfo - return the current allocation information for a file

SYNOPSIS

int
Dm_get_allocinfo(
    dm_sessid_t    sid,
    void          *hanp,
    size_t         hlen,
    dm_token_t     token,
    dm_off_t      *offp,
    u_int          nelem,
    dm_extent_t   *extentp,
    u_int         *nelemp)

DESCRIPTION

The dm_get_allocinfo() function returns allocation information for a file. This function is iterative in nature and allows the application to begin retrieving extent information about a file at any byte offset.

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_sessid_t sid (I)

The identifier for the session of interest.

void *hanp (I)

The handle for the target file.

size_t hlen (I)

The length of the handle in bytes.

dm_token_t token (I)

The token referencing the access right for the handle. The access right must be at least DM_RIGHT_SHARED or the token DM_NO_TOKEN may be used and the interface acquires the appropriate rights.

dm_off_t *offp (I/O)

On output, the byte address of the beginning of the extent following the last returned extent. When *offp returns zero, there are no more extents. On input, the byte address from which to start reporting extent information. Assigning zero to *offp causes the initial extents of the file to be returned. Assigning the value returned by the previous call to dm_get_allocinfo() causes the next extents to be returned. The value in *offp may point beyond the current size of the file.

u_int nelem (I)

The number of elements in the extent array.

dm_extent_t *extentp (O)

The residency information for the file.

u_int *nelemp (O)

The number of elements returned.

RETURN VALUE

Zero indicates success and that no more information is available. 1 is returned on success and indicates more information maybe available. On error, -1 is returned and the global errno is set to indicate the error.

[EACCES]

The access right referenced by the token for the handle is not at least DM_RIGHT_SHARED.

[EBADF]

The file handle does not refer to an existing accessible object.

[EFAULT]

The system detected an invalid address in attempting to use an argument.

[EINVAL]

nelem is zero and must be at least one.

[EINVAL]

The argument offp does not point to a valid extent.

[EINVAL]

The file handle does not refer to a regular file.

[EINVAL]

The session is not valid.

[EINVAL]

The argument token is not a valid token.

[EIO]

An attempt to read the file residency information resulted in an I/O error.

[ENOTSUP]

This call is not meaningful for the object being checked.

[EPERM]

The caller does not hold the appropriate privilege.

SEE ALSO

dm_punch_hole(), dm_probe_hole().

NAME

dm_get_bulkattr - get bulk attributes for an entire file system
dm_get_bulkall - get bulk data management attributes for a file system
dm_get_dirattrs - get bulk attributes for a directory

SYNOPSIS

int
dm_get_bulkattr(
    dm_sessid_t     sid,
    void           *hanp,
    size_t          hlen,
    dm_token_t      token,
    u_int           mask,
    dm_attrloc_t   *locp,
    size_t          buflen,
    void           *bufp,
    size_t         *rlenp)

int
dm_get_bulkall(
    dm_sessid_t     sid,
    void           *hanp,
    size_t          hlen,
    dm_token_t      token,
    u_int           mask,
    dm_attrname_t  *attrnamep,
    dm_attrloc_t   *locp,
    size_t          buflen,
    void           *bufp,
    size_t         *rlenp)

int
dm_get_dirattrs(
    dm_sessid_t     sid,
    void           *hanp,
    size_t          hlen,
    dm_token_t      token,
    u_int           mask,
    dm_attrloc_t   *locp,
    size_t          buflen,
    void           *bufp,
    size_t         *rlenp)

DESCRIPTION

The function dm_get_bulkattr() retrieves both standard file attributes and DM specific file attributes for the file system specified by the argument hanp. The bufp argument is filled with one or more dm_stat structures on return. The argument mask indicates which fields of the dm_stat structure to return (see dm_stat_t for the flag definitions). For fields that are not returned, the corresponding fields of the dm_stat structure are undefined; the dt_compname field is always undefined. The file system specified by hanp must be mounted.

The function dm_get_bulkall() is similar to dm_get_bulkattr(), except that it returns a series of dm_xstat structures in the buffer identified by the bufp argument. The dx_attrdata field of each dm_xstat structure will contain the data associated with the attribute name that is specified by the attrnamep argument. If the named attribute is not set on a given file, that file will show a zero-length attribute in dx_attrdata. Because dm_xstat structures contain variable data, the output buffer should be traversed using the DM_STEP_TO_NEXT macro. dm_get_bulkall() is an optional interface in the DMAPI.

The dm_get_dirattrs() function performs a similar function for directories. It returns the file name, attributes, and DM specific file attributes for the files in the directory specified by hanp. The bufp argument is filled with one or more dm_stat structures on return. The argument mask indicates which fields of the dm_stat structure to return. For fields that are not returned, the corresponding fields of the dm_stat structure are undefined. The dt_compname field is always filled in. The directory specified by hanp must be on a mounted file system. If a file is named several times within the directory (that is, multiple links to the same file), a dm_stat structure is returned for each one.

These functions can be repeated, and each time fill the buffer bufp with zero or more dm_stat (or dm_xstat) structures, until all structures have been returned. The argument locp must be initialized via dm_init_attrloc() (see dm_init_attrloc ) before calling dm_get_bulkattr(), dm_get_bulkall() or dm_get_dirattrs(). The same handle must be used for initializing locp as is used for retrieving the attributes.

The arguments to dm_get_bulkattr() are as follows:

dm_sessid_t sid (I)

The identifier for the session of interest.

void *hanp (I)

The handle for the file system. Information on all allocated files is returned; unallocated inodes are skipped.

size_t hlen (I)

The length of the handle in bytes.

dm_token_t token (I)

The token referencing the access right for the handle. The access right must be at least DM_RIGHT_SHARED or the token DM_NO_TOKEN may be used and the interface acquires the appropriate rights.

u_int mask (I)

The mask argument controls which fields in the dm_stat structure should be returned. The mask is constructed by OR-ing together one or more of the following flags:

DM_AT_HANDLE

The file's handle is returned.

DM_AT_EMASK

The file's persistent event mask is returned.

DM_AT_PMANR

A boolean (DM_TRUE or DM_FALSE) is returned indicating whether the file has persistent managed regions.

DM_AT_PATTR

A boolean (DM_TRUE or DM_FALSE) is returned indicating whether the file has persistent data management attributes.

DM_AT_DTIME

The time stamp of the persistent attributes if associated with the file.

DM_AT_CFLAG

The file change indicator is returned.

DM_AT_STAT

The file's general attributes as defined by the Single UNIX Specification structstat.

dm_attrloc_t *locp (I/O)

This is an offset, which is opaque to the calling DM application, that can be used by the DMAPI implementation to indicate the location in the object. It should not be modified by the DM application. It must be initialized via dm_init_attrloc() before calling dm_get_bulkattr(), dm_get_bulkall() or dm_get_dirattrs().

size_t buflen (I)

The size of the buffer, in bytes.

void *bufp (O)

This is filled in with the dm_stat information for the file system.

size_t *rlenp (O)

The size of the returned information.

The arguments to dm_get_bulkall() are identical to those for dm_get_bulkattr(), with the addition of one argument to specify the attribute of interest:

dm_attrname_t *attrnamep (I)

The DM attribute to be retrieved.

The arguments to dm_get_dirattrs() are identical to those for dm_get_bulkattr() with the exception of the specification of the file handle:

void *hanp (I)

The handle for the directory. Information on all the files in the directory is returned. Subdirectories are not traversed. If a subdirectory is a mount point, dm_get_dirattrs() returns information on the underlying mounted-on subdirectory, not the new mount point.

RETURN VALUE

dm_get_bulkattr(), dm_get_bulkall() and dm_get_dirattrs() return 1 to indicate success and more information maybe available, or zero to indicate success and no more information is available. -1 is returned on error, in which case the global errno is set to one of the following values:

[EACCES]

The access right referenced by the token for the handle is not at least DM_RIGHT_SHARED.

[EBADF]

The file handle does not refer to an existing or accessible object.

[EFAULT]

The system detected an invalid address in attempting to use an argument.

[EINVAL]

The argument locp or mask is not a valid value.

[EINVAL]

The argument token is not a valid token.

[EINVAL]

The file handle does not represent a directory or the file system object.

[EINVAL]

The session is not valid.

[EIO]

An attempt to read the attributes resulted in an I/O error.

[ENOMEM]

The DMAPI could not obtain the required resources to complete the call.

[ENOSYS]

The DMAPI does not support dm_get_bulkall().

[EPERM]

The caller does not hold the appropriate privilege.

SEE ALSO

dm_get_allocinfo(), dm_get_fileattr(), dm_init_attrloc().

NAME

dm_get_config - return DMAPI implementation details and limits

SYNOPSIS

int
dm_get_config(
    void          *hanp,
    size_t         hlen,
    dm_config_t    flagname,
    dm_size_t     *retvalp)

DESCRIPTION

The function dm_get_config() returns information specific to an implementation of the DMAPI.

void *hanp (I)

A handle for any file on the file system or a handle for the file system.

size_t hlen (I)

The length of the handle in bytes.

dm_config_t flagname (I)

The argument flagname is an enum and may contain one of the following values:

DM_CONFIG_BULKALL

A boolean value indicating whether the DMAPI implementation supports the dm_get_bulkall() function.

DM_CONFIG_CREATE_BY_HANDLE

A boolean value indicating whether the DMAPI implementation supports the dm_create_by_handle(), dm_mkdir_by_handle() and dm_symlink_by_handle() functions.

DM_CONFIG_DTIME_OVERLOAD

A boolean value that indicates whether the ctime and dtime fields in the dm_stat structure share the same storage.

DM_CONFIG_LEGACY

A boolean value indicating whether the DMAPI implementation supports the dm_make_handle(), dm_make_fshandle(), dm_handle_to_fshandle(), dm_handle_to_igen() and dm_handle_to_ino() legacy functions.

DM_CONFIG_LOCK_UPGRADE

A boolean value indicating whether the DMAPI implementation does or does not support upgrading/downgrading rights in non-blocking fashion without releasing the current right.

DM_CONFIG_MAX_ATTR_ON_DESTROY

The maximum number of bytes returned for the attribute copy field within a destroy event message. A size of 0 is returned if this feature is not supported by the implementation.

DM_CONFIG_MAX_ATTRIBUTE_SIZE

The maximum size in bytes per file that a single persistent attribute can occupy is returned. This is the size of the attribute data only.

DM_CONFIG_MAX_HANDLE_SIZE

The maximum size of handles in the file system. A size of 0 means it is unknown.

DM_CONFIG_MAX_MANAGED_REGIONS

The maximum number of managed regions supported per file is returned.

DM_CONFIG_MAX_MESSAGE_DATA

The number of bytes of data in the largest user-created event message. DM applications can use this value to determine the largest buffer size allowed in calls to dm_create_userevent() and dm_send_msg()).

DM_CONFIG_OBJ_REF

A boolean value indicating whether the DMAPI implementation supports the dm_obj_xxx() functions.

DM_CONFIG_PENDING

A boolean value indicating whether the DMAPI implementation supports the dm_pending() function.

DM_CONFIG_PERS_ATTRIBUTES

A boolean value indicating whether the file system does or does not support persistent, opaque data management attributes.

DM_CONFIG_PERS_EVENTS

A boolean value is returned which indicates whether the DMAPI implementation supports support persistent event masks.

DM_CONFIG_PERS_INHERIT_ATTRIBS

A boolean value indicating whether the file system does or does not support inherited opaque data management attributes.

DM_CONFIG_PERS_MANAGED_REGIONS

A boolean value is returned that indicates whether the DMAPI implementation supports or does not support persistent managed regions.

DM_CONFIG_PUNCH_HOLE

A boolean value indicating whether the file system does or does not support punching holes (see dm_punch/probe_hole ).

DM_CONFIG_TOTAL_ATTRIBUTE_SPACE

The total available space per file for the storage of all persistent data management attributes, in bytes.

DM_CONFIG_WILL_RETRY

A boolean value is returned that indicates whether the DMAPI implementation retries the operation that caused a nospace event to be generated if a DM_RESP_CONTINUE response is returned.

For boolean values, a DM_TRUE return value indicates that the property is supported, while DM_FALSE indicates that the property is not supported. Other return values are dependent on the value of the flagname argument.

dm_size_t *retvalp (O)

The value of the requested flag if the call succeeds. If dm_get_config() returns -1, the value is undefined.

RETURN VALUE

Zero is returned on success. On error, -1 is returned, and the global errno is set to one of the following values:

[EBADF]

The file handle does not refer to an existing or accessible object.

[EFAULT]

The system detected an invalid address in attempting to use an argument.

[EINVAL]

The argument flag_name does not contain a valid option.

[EPERM]

The caller does not hold the appropriate privilege.

SEE ALSO

dm_punch_hole(), dm_get_allocinfo().

NAME

dm_get_config_events - get a list of all events supported by the DMAPI implementation

SYNOPSIS

int
dm_get_config_events(
    void             *hanp,
    size_t            hlen,
    u_int             nelem,
    dm_eventset_t    *eventsetp,
    u_int            *nelemp)

DESCRIPTION

Return the list of supported events for a specific file system. The object can be either a regular file or the file system object. The returned event list is the set of all supported events in the file system containing the object. DM applications can use the DMEV_ISSET macro to determine if a specific event is supported.

void *hanp (I)

The handle for an object in the file system or a file system handle.

size_t hlen (I)

The length of the handle in bytes.

u_int nelem (I)

The number of elements in the event set array.

dm_eventset_t *eventsetp (O)

Buffer to be filled in with the list of supported events.

u_int *nelemp (O)

The number of elements read. If the buffer is not large enough to hold the requested information (as determined by the nelem parameter), then no data is copied, the call fails with [E2BIG], and nelemp is set to the number of elements that are available. nelemp is updated if either the call was successful or the call fails with [E2BIG], but is undefined otherwise.

RETURN VALUE

Zero is returned on success. On error, -1 is returned, and the global errno is set to one of the following values:

[E2BIG]

The information is too large to fit into the buffer.

[EBADF]

The handle does not refer to an existing or accessible object.

[EFAULT]

The system detected an invalid address in attempting to use an argument.

[EPERM]

The caller does not hold the appropriate privilege.

SEE ALSO

dm_get_events().

NAME

dm_get_dmattr - retrieve a data management attribute

SYNOPSIS

int
dm_get_dmattr(
    dm_sessid_t      sid,
    void            *hanp,
    size_t           hlen,
    dm_token_t       token,
    dm_attrname_t   *attrnamep,
    size_t           buflen,
    void            *bufp,
    size_t          *rlenp)

DESCRIPTION

The dm_get_dmattr() function retrieves a single, specific data management attribute for a file. The file's attribute time stamp is not altered.

dm_sessid_t sid (I)

The identifier for the session of interest.

void *hanp (I)

The handle for the file for which the attributes should be retrieved.

size_t hlen (I)

The length of the handle in bytes.

dm_token_t token (I)

The token referencing the access right for the handle. The access right must be at least DM_RIGHT_SHARED, or the token DM_NO_TOKEN may be used and the interface acquires the appropriate rights.

dm_attrname_t *attrnamep (I)

The attribute to be retrieved.

size_t buflen (I)

The size of the buffer in bytes.

void *bufp (O)

The buffer to be filled in with the value of the specified attribute's data.

size_t *rlenp (O)

The size of the requested information. If the buffer is not large enough to hold the requested information (as indicated by the buflen parameter), then no data is copied, the call fails with [E2BIG], and rlenp is set to the required size. rlenp is updated if either the call was successful or the call fails with [E2BIG], but is undefined otherwise.

RETURN VALUE

Zero is returned on success. On error, -1 is returned, and the global errno is set to one of the following values:

[E2BIG]

The information is too large to fit into the buffer.

[EACCES]

The access right referenced by the token for the handle is not at least DM_RIGHT_SHARED.

[EBADF]

The file handle does not refer to an existing or accessible object.

[EFAULT]

The system detected an invalid address in attempting to use an argument.

[EINVAL]

The argument token is not a valid token.

[EINVAL]

The session is not valid.

[ENOENT]

The attribute was not found.

[ENOMEM]

The DMAPI could not acquire the required resources to complete the call.

[ENOSYS]

The DMAPI implementation does not support this optional function.

[EIO]

An attempt to read the attribute resulted in an I/O error.

[EPERM]

The caller does not hold the appropriate privilege.

SEE ALSO

dm_set_dmattr(), dm_remove_dmattr(), dm_getall_dmattr().

NOTES

dm_get_dmattr() is an optional component of the DMAPI.

NAME

dm_get_eventlist - get the list of enabled events for an object

SYNOPSIS

int
dm_get_eventlist(
    dm_sessid_t       sid,
    void             *hanp,
    size_t            hlen,
    dm_token_t        token,
    u_int             nelem,
    dm_eventset_t    *eventsetp,
    u_int            *nelemp)

DESCRIPTION

Return the list of enabled events for the specified object. The object can be either a regular file or the file system object. The returned event list is the set of all events for the object. DM applications can use the DMEV_ISSET macro to determine if a specific event is enabled.

For DMAPI implementations that do not store event lists persistently and support the debut event, dm_get_eventlist() returns only those events that have been set via dm_set_eventlist() since the most recent debut event. The function does not itself cause a debut event to be generated.

The synchronous managed region events are set via the dm_set_region() interface. If there are any managed regions that have any events set (as determined by the rg_flags field in the struct B dm_region ), dm_get_eventlist() returns the union of all of those flags fields.

dm_sessid_t sid (I)

The identifier for the session of interest.

void *hanp (I)

The handle for the object.

size_t hlen (I)

The length of the handle in bytes.

dm_token_t token (I)

The token referencing the access right for the handle. The access right must be at least DM_RIGHT_SHARED or the token DM_NO_TOKEN may be used and the interface acquires the appropriate rights.

u_int nelem (I)

The number of elements in the event set array.

dm_eventset_t *eventsetp (O)

Buffer to be filled in with the list of events.

u_int *nelemp (O)

The number of elements read. If the buffer is not large enough to hold the requested information (as determined by the nelem parameter), then no data is copied, the call fails with [E2BIG], and nelemp is set to the number of elements that are available. nelemp is updated if either the call was successful or the call fails with [E2BIG], but is undefined otherwise.

RETURN VALUE

Zero is returned on success. On error, -1 is returned, and the global errno is set to one of the following values:

[E2BIG]

The information is too large to fit into the buffer.

[EACCES]

The access right referenced by the token for the handle is not at least DM_RIGHT_SHARED.

[EBADF]

The handle does not refer to an existing or accessible object.

[EFAULT]

The system detected an invalid address in attempting to use an argument.

[EINVAL]

The argument token is not a valid token.

[EINVAL]

The session is not valid.

[ENOMEM]

The DMAPI could not obtain the required resources to complete the call.

[EPERM]

The caller does not hold the appropriate privilege.

SEE ALSO

dm_set_eventlist(), dm_set_disp(), dm_get_events(), macro DMEV_ISSET.

NAME

dm_get_events - get the next available event messages

SYNOPSIS

int
dm_get_events(
    dm_sessid_t    sid,
    u_int          maxmsgs,
    u_int          flags,
    size_t         buflen,
    void          *bufp,
    size_t        *rlenp)

DESCRIPTION

Get the next event or events for a session. The event message is copied to the message buffer and includes both the common and event-specific fields of the event.

Messages can be retrieved in bulk; up to maxmsgs can be copied to the output buffer, provided that enough space is available.

If no messages are immediately available, and the DM_EV_WAIT flag is set in the flags argument, then the calling process blocks interruptibly.

dm_sessid_t sid (I)

The identifier for the session of interest.

u_int maxmsgs (I)

The maximum number of messages that should be transferred in a single call. A value of zero indicates return all available messages that fit into the message buffer.

u_int flags (I)

If the DM_EV_WAIT flag is not set and no messages are available, the calling process returns with [EAGAIN]. If DM_EV_WAIT is set and no messages are available, the calling process blocks interruptibly, waiting for messages to be enqueued on the session.

size_t buflen (I)

The size of the message buffer in bytes. It must be large enough to hold at least one maximum sized event message.

void *bufp (O)

The message buffer to be filled in with one or more dm_eventmsg structures.

size_t rlenp (O)

The size of the requested information. If the buffer is not large enough to hold the requested information (as indicated by the buflen parameter), then no data is copied, the call fails with [E2BIG], and rlenp is set to the required size. rlenp is updated if either the call was successful or the call fails with [E2BIG], but is undefined otherwise.

RETURN VALUE

Zero indicates success. On error, -1 is returned and the global errno is set to indicate the error.

[E2BIG]

The information is too large to fit into the buffer.

[EAGAIN]

The flags parameter had the DM_EV_WAIT flag set, and no messages are immediately available.

[EFAULT]

The system detected an invalid address in attempting to use an argument.

[EINVAL]

The session is not valid.

[EINTR]

The process was blocked waiting for messages and was interrupted.

[ENOMEM]

The DMAPI could not obtain the required resources to complete the call.

[EPERM]

The caller does not hold the appropriate privilege.

SEE ALSO

dm_set_eventlist(), dm_set_disp().

NAME

dm_get_fileattr - return file attributes

SYNOPSIS

int
dm_get_fileattr(
    dm_sessid_t     sid,
    void           *hanp,
    size_t          hlen,
    dm_token_t      token,
    u_int           mask,
    dm_stat_t      *statp)

DESCRIPTION

The function dm_get_fileattr() retrieves both standard file attributes and DM specific file attributes for the file specified by handle.

dm_sessid_t sid (I)

The identifier for the session of interest.

void *hanp (I)

The handle for the file for which the file attributes should be retrieved.

size_t hlen (I)

The length of the handle in bytes.

dm_token_t token (I)

The token referencing the access right for the handle. The access right must be at least DM_RIGHT_SHARED, or the token DM_NO_TOKEN may be used and the interface acquires the appropriate rights.

u_int mask (I)

The argument mask indicates which fields of the dm_stat structure to return. The mask is constructed by OR-ing together one or more of the following flags:

DM_AT_EMASK

The file's persistent event mask is returned.

DM_AT_PMANR

A boolean (DM_TRUE or DM_FALSE) is returned indicating whether the file has persistent managed regions.

DM_AT_PATTR

A boolean (DM_TRUE or DM_FALSE) is returned indicating whether the file has persistent data management attributes.

DM_AT_DTIME

The time stamp of the persistent attributes if associated with the file.

DM_AT_CFLAG

The file change indicator is returned.

DM_AT_STAT

The file's general attributes as defined by the Single UNIX Specification struct stat.

dm_stat_t *statp (O)

The buffer to be filled in with the required information. For fields that were not specified by the mask input value, the values of the corresponding field are not defined.

RETURN VALUE

Zero is returned on sucess. On error, -1 is returned, and the global errno is set to one of the following values:

[EACCES]

The access right referenced by the token for the handle is not at least DM_RIGHT_SHARED.

[EBADF]

The file handle does not refer to an existing or accessible object.

[EFAULT]

The system detected an invalid address in attempting to use an argument.

[EINVAL]

The argument mask is not valid.

[EINVAL]

The argument token is not a valid token.

[EINVAL]

The session is not valid.

[EIO]

An attempt to read the attributes resulted in an I/O error.

[ENOMEM]

The DMAPI could not obtain the required resources to complete the call.

[EPERM]

The caller does not hold the appropriate privilege.

SEE ALSO

dm_punch_hole(), dm_get_allocinfo(), dm_get_bulkattr(), dm_get_dirattr().

NAME

dm_get_mountinfo - return the information that was delivered on a mount event

SYNOPSIS

int
dm_get_mountinfo(
    dm_sessid_t    sid,
    void          *hanp,
    size_t         hlen,
    dm_token_t     token,
    size_t         buflen,
    void          *bufp,
    size_t        *rlenp)

DESCRIPTION

During initialization and often during recovery, DM applications need to get information about the file systems they are operating on. To facilitate this, dm_get_mountinfo() provides the same information that was originally generated on a mount event. This information is most likely kept in a static area in the DMAPI implementation; thus it is not a large burden on the implementation to return it both in a message and via this interface.

dm_sessid_t sid (I)

The identifier for the session of interest.

void *hanp (I)

The handle for the file system meta-object.

size_t hlen (I)

The length of the handle in bytes.

dm_token_t token (I)

The token referencing the access right for the handle. The access right must be at least DM_RIGHT_SHARED, or the token DM_NO_TOKEN may be used and the interface acquires the appropriate rights.

size_t buflen (I)

The length of the input buffer in bytes.

void *bufp (O)

A pointer to a buffer that is to be filled in with the information. The buffer should point to a dm_mount_event structure.

size_t rlenp (O)

The size of the requested information. If the buffer is not large enough to hold the requested information (as indicated by the buflen parameter), then no data is copied, the call fails with [E2BIG], and rlenp is set to the required size. rlenp is updated if either the call was successful or the call fails with [E2BIG], but is undefined otherwise.

RETURN VALUE

Zero is returned on success. On error, -1 is returned, and the global errno is set to one of the following values:

[E2BIG]

The buffer is not large enough to hold the requested information.

[EBADF]

The handle does not refer to an existing or accessible object.

[EFAULT]

The system detected an invalid address in attempting to use an argument.

[EINVAL]

The handle is not a file system handle.

[EINVAL]

The session is not valid.

[EIO]

An attempt to read the mount information resulted in an I/O error.

[ENOMEM]

The DMAPI could not obtain the required resources to complete the call.

[EPERM]

The caller does not hold the appropriate privilege.

SEE ALSO

mount event.

NAME

dm_get_region - get the managed regions for a file

SYNOPSIS

int
dm_get_region(
    dm_sessid_t    sid,
    void          *hanp,
    size_t         hlen,
    dm_token_t     token,
    u_int          nelem,
    dm_region_t   *regbufp,
    u_int         *nelemp)

DESCRIPTION

Get the set of managed regions for a file.

dm_sessid_t sid (I)

The identifier for the session of interest.

void *hanp (I)

The handle for the regular file.

size_t hlen (I)

The length of the handle in bytes.

dm_token_t token (I)

The token referencing the access right for the handle. The access right must be at least DM_RIGHT_SHARED, or the token DM_NO_TOKEN may be used and the interface acquires the appropriate rights.

u_int nelem (I)

The number of elements in the region buffer.

dm_region_t *regbufp (O)

A pointer to the structure defining the regions to be filled in.

u_int *nelemp (O)

The number of elements read. If the buffer is not large enough to hold the requested information (as determined by the nelem parameter), then no data is copied, the call fails with [E2BIG], and nelemp is set to the number of elements that are available. nelemp is updated if either the call was successful or the call fails with [E2BIG], but is undefined otherwise.

RETURN VALUES

Zero is returned on success. On error, -1 is returned, and the global errno is set to one of the following values:

[E2BIG]

The information is too large to fit into the buffer.

[EACCES]

The access right referenced by the token for the handle is not at least DM_RIGHT_SHARED.

[EBADF]

The file handle does not refer to an existing or accessible object.

[EFAULT]

The system detected an invalid address in attempting to use an argument.

[EINVAL]

The handle does not refer to a regular file.

[EINVAL]

The session is not valid.

[EINVAL]

The argument token is not a valid token.

[ENOMEM]

The DMAPI could not acquire the required resources to complete the call. LI "[EPERM]"
The caller does not hold the appropriate privilege.

SEE ALSO

dm_set_region().

NAME

dm_getall_disp - get disposition of events for all file systems for a session

SYNOPSIS

int
dm_getall_disp(
    dm_sessid_t    sid,
    size_t         buflen,
    void          *bufp,
    size_t        *rlenp)

DESCRIPTION

Get the set of all dispositions of events for all file systems for the indicated session. Since a session may be receiving events on more than one file system, dm_getall_disp() returns the disposition of events for every file system that was specified in a dm_set_disp() function.

dm_sessid_t sid (I)

The identifier for the session of interest.

size_t buflen (I)

The length of the input buffer in bytes.

void *bufp (O)

The buffer to be filled in with dm_dispinfo structures.

size_t *rlenp (O)

The size of the requested information. If the buffer is not large enough to hold the requested information (as indicated by the buflen parameter), then no data is copied, the call fails with [E2BIG], and rlenp is set to the required size. rlenp is updated if either the call was successful or the call fails with [E2BIG], but is undefined otherwise.

RETURN VALUE

Zero is returned on success. On error, -1 is returned, and the global errno is set to one of the following values:

[E2BIG]

The information is too large to fit into the buffer.

[EFAULT]

The system detected an invalid address in attempting to use an argument.

[EINVAL]

The session is not valid.

[ENOMEM]

The DMAPI could not acquire the required resources to complete the call.

[EPERM]

he caller does not hold the appropriate privilege.

SEE ALSO

dm_set_disp().

NAME

dm_getall_dmattr - retrieve all of a file's data management attributes

SYNOPSIS

int
dm_getall_dmattr(
    dm_sessid_t    sid,
    void          *hanp,
    size_t         hlen,
    dm_token_t     token,
    size_t         buflen,
    void          *bufp,
    size_t        *rlenp)

DESCRIPTION

The dm_getall_dmattr() function returns all the attributes and attribute data associated with the specified file system object.

dm_sessid_t sid (I)

The identifier for the session of interest.

void *hanp (I)

The handle for the file for which the attributes should be retrieved.

size_t hlen (I)

The length of the handle in bytes.

dm_token_t token (I)

The token referencing the access right for the handle. The access right must be at least DM_RIGHT_SHARED or the token DM_NO_TOKEN may be used and the interface acquires the appropriate rights.

size_t buflen (I)

The size of the buffer in bytes.

void *bufp (O)

The buffer to be filled in with dm_attrlist structures.

size_t *rlenp (O)

The size of the requested information. If the buffer is not large enough to hold the requested information (as indicated by the buflen parameter), then no data is copied, the call fails with [E2BIG], and rlenp is set to the required size. rlenp is updated if either the call was successful or the call fails with [E2BIG], but is undefined otherwise.

RETURN VALUE

Zero is returned on success. On error, -1 is returned, and the global errno is set to one of the following values:

[E2BIG]

The information is too large to fit into the buffer.

[EACCES]

The access right referenced by the token for the handle is not at least DM_RIGHT_SHARED.

[EBADF]

The file handle does not refer to an existing or accessible object.

[EFAULT]

The system detected an invalid address in attempting to use an argument.

[EINVAL]

The argument token is not a valid token.

[EINVAL]

The session is not valid.

[EIO]

An attempt to read the attributes resulted in an I/O error.

[ENOMEM]

The DMAPI could not acquire the required resources to complete the call.

[ENOSYS]

The DMAPI implementation does not support this optional function.

[EPERM]

The caller does not hold the appropriate privilege.

SEE ALSO

dm_get_dmattr(), dm_attrlist_t().

NOTES

dm_getall_dmattr() is an optional component of the DMAPI.

NAME

dm_getall_inherit - get all inheritable attributes for the specified file system

SYNOPSIS

int
dm_getall_inherit(
    dm_sessid_t     sid,
    void           *hanp,
    size_t          hlen,
    dm_token_t      token,
    u_int           nelem,
    dm_inherit_t    inheritbufp,
    u_int          *nelemp)

DESCRIPTION

The dm_getall_inherit() function returns a list of all inheritable attributes associated with the given file system object. The inheritability property of attributes is not persistent across reboots. The attributes are returned in a dm_inherit structure, which gives the attribute name and the file type that the attribute applies to.

dm_sessid_t sid (I)

The identifier for the session of interest.

void *hanp (I)

The file system handle.

size_t hlen (I)

The length of the handle in bytes.

dm_token_t token (I)

The token referencing the access right for the handle. The access right must be at least DM_RIGHT_SHARED or the token DM_NO_TOKEN may be used and the interface acquires the appropriate rights.

u_int nelem (I)

The number of elements to return. No more than nelem is returned.

dm_inherit_t *inheritbufp (O)

The buffer to be filled with inheritable attributes.

u_int *nelemp (O)

The number of elements read. If the buffer is not large enough to hold the requested information (as determined by the nelem parameter), then no data is copied, the call fails with [E2BIG], and nelemp is set to the number of elements that are available. nelemp is updated if either the call was successful or the call fails with [E2BIG], but is undefined otherwise.

RETURN VALUE

Zero is returned on success. On error, -1 is returned, and the global errno is set to one of the following values:

[E2BIG]

The information is too large to fit into the buffer.

[EACCES]

The access right referenced by the token for the handle is not at least DM_RIGHT_SHARED.

[EBADF]

The file handle does not refer to an existing or accessible object.

[EFAULT]

The system detected an invalid address in attempting to use an argument.

[EINVAL]

The argument token is not a valid token.

[EINVAL]

The handle is not a file system handle.

[EINVAL]

The session is not valid.

[EIO]

An attempt to read the attributes resulted in an I/O error.

[ENOSYS]

The DMAPI implementation does not support this optional function.

[EPERM]

The caller does not hold the appropriate privilege.

SEE ALSO

dm_set_inherit(), dm_clear_inherit(), dm_inherit_t.

NOTES

dm_getall_inherit() is an optional component of the DMAPI.

NAME

dm_getall_sessions - get all extant sessions

SYNOPSIS

int
dm_getall_sessions(
    u_int          nelem,
    dm_sessid_t   *sidbufp,
    u_int         *nelemp)

DESCRIPTION

The dm_getall_sessions() function returns a list of all the sessions that exist on a system.

u_int nelem (I)

The maximum number of elements to return.

dm_sessid_t *sidbufp (O)

The buffer where the active sessions are to be deposited.

u_int *nelemp (O)

The number of elements read. If the buffer is not large enough to hold the requested information (as determined by the nelem parameter), then no data is copied, the call fails with [E2BIG], and nelemp is set to the number of elements that are available. nelemp is updated if either the call was successful or the call fails with [E2BIG], but is undefined otherwise.

RETURN VALUE

Zero is returned on success. On error, -1 is returned, and the global errno is set to one of the following values:

[E2BIG]

The information is too large to fit into the buffer.

[EFAULT]

The system detected an invalid address in attempting to use an argument.

[ENOMEM]

The DMAPI could not obtain the required resources to complete the call.

[EPERM]

The caller does not hold the appropriate privilege.

SEE ALSO

dm_find_eventmsg(), dm_create_session(), dm_getall_tokens(), dm_query_session().

NAME

dm_getall_tokens - get all outstanding tokens for a session

SYNOPSIS

int
dm_getall_tokens(
    dm_sessid_t   sid,
    u_int         nelem,
    dm_token_t   *tokenbufp,
    u_int        *nelemp)

DESCRIPTION

This gets all the outstanding tokens that are associated with a session. An outstanding token is a token that corresponds to a synchronous message that has been delivered but not responded to. User event messages created with dm_create_userevent() are implicitly synchronous, and if tokens exist for these messages, they are also returned.

dm_sessid_t sid (I)

The identifier for the session of interest.

u_int nelem (I)

The maximum number of elements to return.

dm_token_t *tokenbufp (O)

The buffer that should be filled in with all outstanding tokens.

u_int *nelemp (O)

The number of elements read. If the buffer is not large enough to hold the requested information (as determined by the nelem parameter), then no data is copied, the call fails with [E2BIG], and nelemp is set to the number of elements that are available. nelemp is updated if either the call was successful or the call fails with [E2BIG], but is undefined otherwise.

RETURN VALUE

Zero is returned on success. On error, -1 is returned, and the global errno is set to one of the following values:

[E2BIG]

The information is too large to fit into the buffer.

[EFAULT]

The system detected an invalid address in attempting to use an argument.

[EINVAL]

The session is not valid.

[ENOMEM]

The DMAPI could not obtain the required resources to complete the call.

[EPERM]

The caller does not hold the appropriate privilege.

SEE ALSO

dm_getall_sessions(), dm_find_eventmsg(), dm_respond_event(), dm_create_session().

NAME

dm_handle_cmp - file handle comparison

SYNOPSIS

int
dm_handle_cmp(
    void      *hanp1,
    size_t     hlen1,
    void      *hanp2,
    size_t     hlen2)

DESCRIPTION

Compare two handles for equality.

void *hanp1 (I)

The first handle to compare.

size_t hlen1 (I)

The length of the first handle in bytes.

void *hanp2 (I)

The second handle to compare.

size_t hlen2 (I)

The length of the second handle in bytes.

RETURN VALUE

<0

hanp1 is less than hanp2 (according to an implementation defined rule).

=0

hanp1 and hanp2 represent the same object.

>0

hanp1 is greater than hanp2 (according to an implementation defined rule).

The rationale behind multiple return values is so that DM applications can use dm_handle_cmp() in sorting.

NAME

dm_handle_hash - hashes the contents of a handle

SYNOPSIS

u_int
dm_handle_hash(
    void     *hanp,
    size_t    hlen)

DESCRIPTION

Hashes the contents of a handle and returns the hashed value.

void *hanp (I)

A pointer to a handle.

size_t hlen (I)

The length of the handle in bytes.

RETURN VALUE

Returns a value derived in an implementation defined manner from the contents of the handle. dm_handle_hash() has no failure indication.

NAME

dm_handle_is_valid - determine if a handle is valid

SYNOPSIS

dm_boolean_t
dm_handle_is_valid(
    void      *hanp,
    size_t     hlen)

DESCRIPTION

Determine if a handle is valid.

void *hanp (I)

The handle to check for validity.

size_t hlen (I)

The length of the handle.

RETURN VALUE

DM_TRUE

The handle is valid.

DM_FALSE

The handle is not a valid DM handle.

NAME

dm_handle_to_fshandle - obtain the file system handle corresponding to an object handle

SYNOPSIS

int
dm_handle_to_fshandle(
    void      *hanp,
    size_t     hlen,
    void     **fshanpp,
    size_t    *fshlenp)

DESCRIPTION

The dm_handle_to_fshandle() function obtains the handle for the file system in which the object handle resides. hanp may not be a file system handle or the global handle.

void *hanp (I)

The object handle.

size_t hlen (I)

The length of the handle in bytes.

void **fshanpp (O)

A pointer that is set to point to the file system handle.

size_t *fshlenp (O)

The length of the file system handle in bytes.

RETURN VALUE

Zero is returned on success. On error, -1 is returned, and the global errno is set to one of the following values:

[EBADF]

hanp does not refer to an existing or accessible object.

[EFAULT]

The system detected an invalid address in attempting to use an argument.

[ENOMEM]

The DMAPI could not obtain the required resources to complete the call.

[EPERM]

The caller does not hold the appropriate privilege.

NAME

dm_handle_to_path - get a path name

SYNOPSIS

int
dm_handle_to_path(
    void     *dirhanp,
    size_t    dirhlen,
    void     *targhanp,
    size_t    targhlen,
    size_t    buflen,
    char     *pathbufp,
    size_t   *rlenp)

DESCRIPTION

Takes two object handles, one of which must be the handle of a directory containing the file identified by the other handle, and constructs a path name. If the first character of the path is "/", then the path is an absolute path name, otherwise it is relative to the containing file system.

void *dirhanp (I)

A handle for the directory containing the target file.

size_t dirhlen (I)

The length of the directory handle in bytes.

void *targhanp (I)

A file handle for the target file. The target file must be in the directory represented by dirhanp.

size_t targhlen (I)

The length of the target handle in bytes.

size_t buflen (I)

The length of the path name buffer in bytes.

char *pathbufp (O)

The buffer for the path name.

size_t *rlenp (O)

Always updated if the call is successful and undefined if [E2BIG] is returned.

RETURN VALUE

Zero is returned on success. On error, -1 is returned, and the global errno is set to one of the following values:

[E2BIG]

The information is too large to fit into the buffer.

[EBADF]

Either dirhanp or targhanp does not refer to an existing or accessible object.

[EFAULT]

The system detected an invalid address in attempting to use an argument.

[ENOMEM]

The DMAPI could not obtain the required resources to complete the call.

[EPERM]

The caller does not hold the appropriate privilege.

NAME

dm_init_attrloc - initialize a bulk attribute location offset

SYNOPSIS

int
dm_init_attrloc(
    dm_sessid_t     sid,
    void           *hanp,
    size_t          hlen,
    dm_token_t      token,
    dm_attrloc_t   *locp)

DESCRIPTION

The function dm_init_attrloc() initializes an opaque cookie for use by the functions dm_get_bulkattr(), dm_get_bulkall() and dm_get_dirattrs().

The arguments to dm_init_attrloc() are as follows:

dm_sessid_t sid (I)

The identifier for the session of interest.

void *hanp (I)

The handle for the file system or the directory.

size_t hlen (I)

The length of the handle in bytes.

dm_token_t token (I)

The token referencing the access right for the handle. The access right must be at least DM_RIGHT_SHARED or the token DM_NO_TOKEN may be used and the interface acquires the appropriate rights.

dm_attrloc_t *locp (O)

Pointer to an offset "cookie" to initialize.

RETURN VALUE

dm_init_attrloc() returns a value of zero upon successful completion. Otherwise a value of -1 is returned and errno is set to one of the following values:

[EACCES]

The access right referenced by the token for the handle is not at least DM_RIGHT_SHARED.

[EBADF]

The file handle does not refer to an existing or accessible object.

[EFAULT]

The system detected an invalid address in attempting to use an argument.

[EINVAL]

The argument token is not a valid token.

[EINVAL]

The file handle does not represent a directory or the file system object.

[EINVAL]

The session is not valid.

[EPERM]

The caller does not hold the appropriate privilege.

SEE ALSO

dm_get_bulkattr(), dm_get_bulkall(), dm_get_dirattr().

NAME

dm_init_service - perform implementation-defined initialization

SYNOPSIS

int
dm_init_service(
    char    **versionstrpp)

DESCRIPTION

Each process that uses the DMAPI must call dm_init_service() before any other DMAPI function. This allows the implementation of the DMAPI to perform any required initialization. The dm_init_service() function returns a NULL terminated version string which is unique to an implementation and may be compared against DM_VER_STR_CONTENTS to verify at run-time that the DMAPI implementation which the DM application was compiled for is the one that is running.

The results of using any other DMAPI function are undefined if dm_init_service() is not called before other DMAPI functions.

RETURN VALUE

Zero is returned on success. On error, -1 is returned, and the global errno is set to one of the following values:

[ENOMEM]

The DMAPI could not obtain the required resources to complete the call.

[ENOSYS]

The DMAPI is not supported on this platform.

[EPERM]

The caller does not hold the appropriate privilege.

NAME

dm_make_handle - construct DMAPI object handle
dm_make_fshandle - construct DMAPI file system handle
dm_handle_to_fsid - extract file system ID from handle
dm_handle_to_igen - extract inode generation count from handle
dm_handle_to_ino - extract inode from handle

SYNOPSIS

int
dm_make_handle(
    dm_fsid_t     *fsidp,
    dm_ino_t      *inop,
    dm_igen_t     *igenp,
    void         **hanpp,
    size_t        *hlenp)

int
dm_make_fshandle(
    dm_fsid_t     *fsid,
    void         **hanpp,
    size_t        *hlenp)

int
dm_handle_to_fsid(
    void          *hanp,
    size_t         hlen,
    dm_fsid_t     *fsidp)

int
dm_handle_to_igen(
    void          *hanp,
    size_t         hlen,
    dm_igen_t     *igenp)

int
dm_handle_to_ino(
    void          *hanp,
    size_t         hlen,
    dm_ino_t      *inop)

DESCRIPTION

This set of functions allows a DM application to compose and decompose DMAPI opaque handles. It is intended as a porting aid when upgrading legacy HSM applications to the DMAPI interface.

The dm_make_handle() function converts a file system ID, inode number, and inode generation count into a handle.

dm_fsid_t *fsidp (I)

The file system ID.

dm_ino_t *inop (I)

The inode number.

dm_igen_t *igenp (I)

The inode generation count.

void **hanpp (O)

A pointer which is initialized by the DMAPI to point to a region of memory containing an opaque DM handle. The caller is responsible for freeing the allocated memory.

size_t *hlenp (O)

The length of the handle in bytes.

The dm_make_fshandle() function converts a file system ID into a file system handle.

dm_fsid_t *fsidp (I)

The file system ID.

void **hanpp (O)

A pointer which is initialized by the DMAPI to point to a region of memory containing an opaque DM handle. The caller is responsible for freeing the handle.

size_t *hlenp (O)

The length of the handle in bytes.

The dm_handle_to_fsid() function extracts a file system ID from a handle.

void *hanp (I)

A pointer to an opaque DM handle previously returned by DMAPI.

size_t hlen (I)

The length of the handle in bytes.

dm_fsid_t *fsidp (O)

A pointer to the file system ID.

The dm_handle_to_igen() function extracts an inode generation count from a handle.

void *hanp (I)

A pointer to an opaque DM handle previously returned by DMAPI.

size_t hlen (I)

The length of the handle in bytes.

dm_igen_t *igenp (O)

A pointer to the inode generation count.

The dm_handle_to_ino() function extracts an inode number from a handle.

void *hanp (I)

A pointer to an opaque DM handle previously returned by DMAPI.

size_t hlen (I)

The length of the handle in bytes.

dm_ino_t *inop (O)

A pointer to the inode number.

RETURN VALUE

Zero is returned on success. On error, -1 is returned, and the global errno is set to one of the following values:

[EBADF]

The file handle does not refer to an existing or accessible object.

[EFAULT]

The system detected an invalid address in attempting to use an argument.

[EINVAL]

The argument token is not a valid token.

[ENOMEM]

The DMAPI could not obtain the required resources to complete the call.

[ENOSYS]

Function is not supported by the DM implementation.

[EPERM]

The caller does not hold the appropriate privilege.

SEE ALSO

dm_handle_free().

NOTES

dm_make_handle(), dm_make_fshandle(), dm_handle_to_fsid(), dm_handle_to_igen() and dm_handle_to_ino() are optional components of the DMAPI.

NAME

dm_mkdir_by_handle - create a directory object using a handle

SYNOPSIS

int
dm_mkdir_by_handle(
    dm_sessid_t    sid,
    void          *dirhanp,
    size_t         dirhlen,
    dm_token_t     token,
    void          *hanp,
    size_t         hlen,
    char          *cname)

DESCRIPTION

dm_mkdir_by_handle() allows applications the ability to create a directory in a directory specified by dirhanp and with a component name specified by cname that can, after creation, be referenced by the supplied target handle hanp. This is useful when an application is reconstructing a directory for which it still has the data and attributes stored on alternate media.

It is the responsibility of the user of this function to reconstruct the object state, including extended attributes. See dm_set_fileattr() and dm_set_dmattr().

If an object cannot be constructed by the file system for the specified handle, an error is returned.

dm_sessid_t sid (I)

The identifier for the session of interest.

void *dirhanp (I)

The handle for the directory that contains the target directory.

size_t dirhlen (I)

The length of the directory handle in bytes.

dm_token_t token (I)

The token referencing the access right for the parent directory handle. The access right must be at DM_RIGHT_EXCL or the token DM_NO_TOKEN may be used and the interface acquires the appropriate rights.

void *hanp (I)

The file handle of the directory.

size_t hlen (I)

The length of the file handle in bytes.

char *cname (I)

The name of the directory to be created in the specified directory.

RETURN VALUE

Zero is returned on success. On error, -1 is returned, and the global errno is set to one of the following values:

[EACCES]

The access right referenced by the token for the parent directory handle is not DM_RIGHT_EXCL.

[EBADF]

The parent directory handle does not refer to an existing or accessible object.

[EEXIST]

The target directory handle refers to an existing object.

[EFAULT]

The system detected an invalid address in attempting to use an argument.

[EINVAL]

The argument token is not a valid token.

[EINVAL]

The session is not valid.

[EPERM]

The caller does not hold the appropriate privilege.

SEE ALSO

dm_set_fileattr(), dm_set_dmattr(), dm_create_by_handle(), dm_symlink_by_handle().

NAME

dm_move_event - move an event from one session to another

SYNOPSIS

int
dm_move_event
    dm_sessid_t    srcsid,
    dm_token_t     token,
    dm_sessid_t    targetsid,
    dm_token_t    *rtokenp)

DESCRIPTION

The dm_move_event() function transfers an outstanding event message between sessions.

The event message remains outstanding, even though it is now enqueued on a different session. Once the call returns successfully, the old token that references the message is no longer valid. The token returned in rtokenp must be used in subsequent calls to reference the message.

dm_sessid_t srcsid (I)

The source session identifier.

dm_token_t token (I)

The token that identifies the message that is to be moved.

dm_sessid_t targetsid (I)

The new session that is to receive the outstanding event.

dm_token_t *rtokenp (O)

The new token that must be used to refer to the message.

RETURN VALUE

Zero is returned on success. On error, -1 is returned, and the global errno is set to one of the following values:

[EFAULT]

The system detected an invalid address in attempting to use an argument.

[EINVAL]

The source or target sessions are not valid.

[ENOENT]

There is no message corresponding to the token.

[ENOMEM]

The DMAPI could not obtain the required resources to complete the call.

[EPERM]

The caller does not hold the appropriate privilege.

SEE ALSO

dm_get_events(), dm_respond_event().

NAME

dm_obj_ref_hold - place a hold on a file system object
dm_obj_ref_rele - release a hold on a file system object
dm_obj_ref_query - query for a hold on a file system object

SYNOPSIS

int
dm_obj_ref_hold(
    dm_sessid_t     sid,
    dm_token_t      token,
    void           *hanp,
    size_t          hlen)

int
dm_obj_ref_rele(
    dm_sessid_t     sid,
    dm_token_t      token,
    void           *hanp,
    size_t          hlen)

int
dm_obj_ref_query(
    dm_sessid_t     sid,
    dm_token_t      token,
    void           *hanp,
    size_t          hlen)

DESCRIPTION

This set of functions allows the DM application to place and release holds on file system objects. The effect is to prevent the object from being flushed out for the duration of the hold, thus no debut events will occur.

System behavior is undefined if an attempt is made to place multiple holds on the same handle/token pair. For portability, the DM application should issue a single hold/release, and use dm_obj_ref_query() to determine if a hold is already in place.

Creating the hold may cause a debut event to occur and responding to an event releases all holds associated with the event.

dm_sessid_t sid (I)

The identifier for the session of interest.

dm_token_t token (I)

The token referencing access rights for the specified object.

void *hanp (I)

The handle for the file system object for which a hold is being placed, released, or queried.

size_t hlen (I)

The length of the handle in bytes.

RETURN VALUE

dm_obj_ref_hold() and dm_obj_ref_rele() return zero on success. dm_obj_ref_query() returns 1 if there is a hold currently associated with the specified object, session id, and token; it returns 0 if there is no hold. On error, -1 is returned and the global errno is set to one of the following values:

[EACCES]

The access right referenced by the token for the handle is not at least DM_RIGHT_SHARED.

[EBADF]

The file handle does not refer to an existing or accessible object.

[EBUSY]

There is a hold already in place for the specified object/token.

[EFAULT]

The system detected an invalid address in attempting to use an argument.

[EINVAL]

The argument ,I token is not a valid token.

[EINVAL]

The handle is not a file system handle.

[EINVAL]

The session is not valid.

[ENOMEM]

Insufficient memory to complete the call.

[ENOSYS]

Function is not supported by the DM implementation.

[EPERM]

The caller does not hold the appropriate privilege.

NOTES

The dm_obj_ref_hold(), dm_obj_ref_rele() and dm_obj_ref_query() are optional components of the DMAPI.

NAME

dm_path_to_handle - create a file handle from a path name
dm_fd_to_handle - create a file handle from a file descriptor
dm_path_to_fshandle - create a file system handle from a path name
dm_handle_free - free the storage allocated for a handle

SYNOPSIS

int
dm_path_to_handle(
    char       *path,
    void      **hanpp,
    size_t     *hlenp)

int 
dm_fd_to_handle(
    int         fd,
    void      **hanpp,
    size_t     *hlenp)

int
dm_path_to_fshandle(
    char       *path,
    void      **hanpp,
    size_t     *hlenp)

void
dm_handle_free(
    void       *hanp,
    size_t      hlen)

DESCRIPTION

This set of functions deals with file handles, which are opaque to a DM application. File handles uniquely identify an object.

dm_path_to_handle() converts a path name into a file handle. If the final component of the path name is a symbolic link, the file handle returned is for the symbolic link itself, and not for the object that the symbolic link references (if any).

char *path (I)

The path name of the object.

void **hanpp (O)

A pointer that is initialized by the DMAPI to point to a region of memory containing an opaque DM handle. The caller is responsible for freeing the allocated memory.

size_t *hlenp (O)

The length of the handle in bytes.

dm_fd_to_handle() converts a file descriptor into a file handle.

int fd (I)

A file descriptor to the object.

void **hanpp (O)

A pointer that is initialized by the DMAPI to point to a region of memory containing an opaque DM handle. The caller is responsible for freeing the allocated memory.

size_t *hlenp (O)

The length of the handle in bytes.

dm_path_to_fshandle() returns the file system handle given a path name to any file in the file system. If the final component of the path name is a symbolic link, the file handle returned is the file system handle for the file system containing the symbolic link and not the file handle for the file system containing the object that the symbolic link references (if any). The file system handle is used by many DMAPI functions to identify a file system.

char *path (I)

A path name to any file in the file system.

void **hanpp (O)

A pointer that is initialized by the DMAPI to point to a region of memory containing an opaque DM handle that represents the file system meta object. The caller is responsible for freeing the allocat