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

size_t *hlenp (O)

The length of the handle in bytes.

dm_handle_free() frees the storage allocated for a handle that was previously returned by dm_path_to_handle(), dm_fd_to_handle(), dm_path_to_fshandle(), dm_make_handle(), dm_handle_to_fshandle() or dm_make_fshandle().

void *hanp (I)

Pointer to the storage area for the file handle that should be freed.

size_t hlen (I)

The length of the handle in bytes.

RETURN VALUE

dm_handle_free() has no failure indication. The other functions return zero is on success. On error, -1 is returned, and the global errno is set to one of the following values:

[EACCES]

Search permission is denied for a component of path.

[EBADF]

fd is not a valid open file descriptor.

[EFAULT]

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

[ELOOP]

Too many symbolic links were encountered in translating the path name.

[ENAMETOOLONG]

A component of path or the entire length of path exceeded the file system limits.

[ENOENT]

A component of path that must exist does not exist.

[ENOMEM]

Insufficient memory to allocate the file handle.

[ENOTDIR]

A component of the specified path name was not a directory when a directory was expected.

[ENXIO]

The file system containing the file opened on fd or the final component of path does not support the DMAPI.

[EPERM]

The caller does not hold the appropriate privilege.

NAME

dm_pending - notify FS of slow DM application operation

SYNOPSIS

int
dm_pending(
    dm_sessid_t         sid,
    dm_token_t          token,
    dm_timestruct_t    *delay)

DESCRIPTION

The dm_pending() function permits a DM application to notify the DMAPI implementation when it detects that an operation will take an unusually long time.

The function indicates that the response to the event identified by token is delayed for an approximate duration of delay. The value of delay is a hint only.

The dm_pending() function must be sent before dm_respond_event(), and is not a replacement for dm_respond_event().

A DM application is not required to generate dm_pending() notifications, and the DMAPI implementation is free to use or ignore the information as it sees fit. Typical use for dm_pending() is to advise the underlying file system about the delay.

dm_sessid_t sid (I)

The identifier for the session of interest.

dm_token_t token (I)

The token representing the event that is expected to be delayed.

dm_timestruct_t *delay (I)

Expected duration of delay.

RETURN VALUE

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

[ENOSYS]

Function is not supported by the DM implementation.

NOTES

The dm_pending() function is an optional component of the DMAPI.

NAME

dm_punch_hole - create a hole in a file
dm_probe_hole - return the rounded result of the area where a hole is to be punched

SYNOPSIS

int
dm_punch_hole(
    dm_sessid_t    sid,
    void          *hanp,
    size_t         hlen,
    dm_token_t     token,
    dm_off_t       off,
    dm_size_t      len)

int
dm_probe_hole(
    dm_sessid_t    sid,
    void          *hanp,
    size_t         hlen,
    dm_token_t     token,
    dm_off_t       off,
    dm_size_t      len,
    dm_off_t      *roffp,
    dm_size_t     *rlenp)

DESCRIPTION

The dm_punch_hole() function is used to make a hole in a regular file, logically writing zeroes to the designated area while bypassing normal DMAPI event generation. The DMAPI implementation may then optionally free media resources for that area. dm_probe_hole() is used to interrogate the DMAPI implementation for size and offset around the area where the hole is to be punched. The DMAPI implementation can impose boundary and rounding constraints within which the DM application must be willing to work.

The DMAPI guarantees that if the DM_RIGHT_EXCL access right is held across a call to dm_probe_hole(), and then the returned results of the probe call are used to make a dm_punch_hole() call, the function will not fail because of rounding.

dm_punch_hole() takes the following arguments:

dm_sessid_t sid (I)

The identifier for the session of interest.

void *hanp (I)

File handle for the regular file that should have its storage manipulated.

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 DM_RIGHT_EXCL or the token DM_NO_TOKEN may be used and the interface acquires the appropriate rights.

dm_off_t off (I)

The starting offset in the file to begin punching a hole. If the offset does not exactly match what the DMAPI implementation can support, [EAGAIN] is returned.

dm_size_t len (I)

The length of the hole to punch, in bytes. If the length does not exactly match what the DMAPI implementation can support, [EAGAIN] is returned. If zero is specified, hole is punched to the end of file.

dm_probe_hole() takes the following arguments:

dm_sessid_t sid (I)

The identifier for the session of interest.

void *hanp (I)

File handle for the regular file that should have its storage manipulated.

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 off (I)

The desired starting offset in the file for the hole.

dm_size_t len (I)

The desired length of the hole to punch, in bytes. A length of zero corresponds to the end of the file.

dm_off_t *roffp (O)

The rounded starting offset of the hole that the DMAPI implementation supports.

dm_size_t *rlenp (O)

The rounded length of the hole, in bytes, that the DMAPI implementation supports.

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 argument off in dm_probe_hole() is larger then file size or the sum of off and len is beyond the end of the file.

[EACCES]

For dm_probe_hole(), the access right referenced by the token for the handle is not at least DM_RIGHT_SHARED.

[EACCES]

For dm_punch_hole(), the access right referenced by the token for the handle is not DM_RIGHT_EXCL.

[EAGAIN]

Rounding of the offset and length is required for a punch operation.

[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 file handle does not refer to a regular file.

[EINVAL]

The session is not valid.

[EIO]

I/O error resulted in failure of operation.

[ENOSYS]

The DMAPI implementation does not support this optional function.

[EPERM]

The caller does not hold the appropriate privilege.

[EROFS]

The operation is not allowed on a read-only file system.

SEE ALSO

dm_get_allocinfo().

NOTES

The dm_punch_hole() and dm_probe_hole() functions are an optional component of the DMAPI.

NAME

dm_query_right - determine the set of access rights to an object

SYNOPSIS

int
dm_query_right(
    dm_sessid_t    sid,
    void          *hanp,
    size_t         hlen,
    dm_token_t     token,
    dm_right_t    *rightp)

DESCRIPTION

The dm_query_right() function determines the access rights to the specified object referenced by the token.

dm_sessid_t sid (I)

The identifier for the session of interest.

void *hanp (I)

The handle that is being queried for access rights.

size_t hlen (I)

The length of the handle in bytes.

dm_token_t token (I)

The token that references the access rights.

dm_right_t *rightp (O)

The location where the access rights should be 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:

[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 session or token is not valid.

[ENOENT]

The token does not reference any access rights for the handle.

[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_create_userevent(), dm_request_right(), dm_respond_event().

NAME

dm_query_session - query a session for information

SYNOPSIS

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

DESCRIPTION

DM applications can associate up to DM_SESSION_INFO_LEN bytes of information with a session via the dm_create_session() function. To retrieve this information during recovery, a DM application must use dm_query_session().

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 the session information.

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 obtain the required resources to complete the call.

[EPERM]

The caller does not hold the appropriate privilege.

SEE ALSO

dm_getall_sessions().

NAME

dm_read_invis - reads a file bypassing DMAPI events
dm_write_invis - writes to a file bypassing DMAPI events

SYNOPSIS

dm_ssize_t
dm_read_invis(
    dm_sessid_t    sid,
    void          *hanp,
    size_t         hlen,
    dm_token_t     token,
    dm_off_t       off,
    dm_size_t      len,
    void          *bufp)

dm_ssize_t
dm_write_invis(
    dm_sessid_t    sid,
    void          *hanp,
    size_t         hlen,
    dm_token_t     token,
    int            flags,
    dm_off_t       off,
    dm_size_t      len,
    void          *bufp)

DESCRIPTION

The dm_read_invis() and dm_write_invis() functions read and write files respectively bypassing normal DMAPI event processing. Neither function updates a file's access or modified time stamps. The semantics of the function are the same as in read() or write() functions. Writes are either synchronous or asynchronous depending on the value of flags. The default is asynchronous. If DM_WRITE_SYNC is specified in flags, the dm_write_invis() function has the same semantics as a standard write followed by an fsync(2) call.

dm_sessid_t sid (I)

The identifier for the session of interest.

void *hanp (I)

File handle for the regular file that is read to or written from.

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. The access right must be DM_RIGHT_EXCL on writes, and at least DM_RIGHT_SHARED on reads or the token DM_NO_TOKEN may be used and the interface acquires the appropriate rights.

int flags (I)

Flags modifying the behavior of dm_write_invis(). Currently the only flag defined is DM_WRITE_SYNC, which causes a write to be synchronous.

dm_off_t off (I)

The starting offset in the file to begin reading or writing.

dm_size_t len (I)

The length to read or write.

void *bufp (I/O)

When reading, this is an output parameter, and is filled in with the data from the file. When writing, it is an input parameter, and contains the data that is written to the file.

RETURN VALUE

Number of bytes read or written on success, -1 on failure and global errno is set to one of the following or other implementation specific values:

[EACCES]

For dm_read_invis(), the access right referenced by the token for the handle is not at least DM_RIGHT_SHARED.

[EACCES]

For dm_write_invis(), the access right referenced by the token for the handle is not DM_RIGHT_EXCL.

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

[EFBIG]

For dm_write_invis(), the sum of off and len is larger than the maximum file size.

[EINTR]

The operation was interrupted by a signal and should be re-tried. On dm_write_invis(), no data was written to the file.

[EINVAL]

The argument len is too large and will overflow if placed into a dm_ssize_t value.

[EINVAL]

The argument off is larger than the file size for read.

[EINVAL]

The argument token is not a valid token.

[EINVAL]

The file handle does not refer to a regular file.

[EINVAL]

The session is not valid.

[EIO]

I/O error resulted in failure of operation.

[ENOSPC]

No space left in the file system.

[EPERM]

The caller does not hold the appropriate privilege.

[EROFS]

The operation is not allowed on a read-only file system.

NAME

dm_release_right - release all access rights to an object

SYNOPSIS

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

DESCRIPTION

The access rights referenced by the token for the specified object are released. If the access rights cannot be immediately relinquished, [EAGAIN] is returned.

dm_sessid_t sid (I)

The identifier for the session of interest.

void *hanp (I)

The handle for the file system object for which the access rights are being released.

size_t hlen (I)

The length of the handle in bytes.

dm_token_t token (I)

The token referencing the access rights for the specified object.

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 token does not have rights to the object.

[EAGAIN]

The right could not be immediately released.

[EBADF]

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

[EBUSY]

The DMAPI implementation does not support releasing this type of right.

[EFAULT]

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

[EINVAL]

The session is not valid.

[EINVAL]

The 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_request_right(), dm_query_right(), dm_create_userevent().

NAME

dm_remove_dmattr - remove a data management attribute

SYNOPSIS

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

DESCRIPTION

The dm_remove_dmattr() function removes the attribute specified by attrname. When a file is removed, the associated attributes are also removed automatically.

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

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 DM_RIGHT_EXCL or the token DM_NO_TOKEN may be used and the interface acquires the appropriate rights.

int setdtime (I)

The file's attribute time stamp is updated if setdtime is non-zero.

dm_attrname_t *attrnamep (I)

The attribute to be removed.

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

I/O error resulted in failure of operation.

[ENOSYS]

The DMAPI implementation does not support this optional function.

[EPERM]

The caller does not hold the appropriate privilege.

[EROFS]

The operation is not allowed on a read-only file system.

SEE ALSO

dm_set_dmattr().

NOTES

dm_remove_dmattr() is an optional component of the DMAPI.

NAME

dm_request_right - request a specific access right to an object

SYNOPSIS

int
dm_request_right(
    dm_sessid_t    sid,
    void          *hanp,
    size_t         hlen,
    dm_token_t     token,
    u_int          flags,
    dm_right_t     right)

DESCRIPTION

Add the requested right to the access rights referenced by the token for the object specified by the handle. This is the mechanism by which DM applications can gain specific access rights to an object.

There are two access rights that can be requested: DM_RIGHT_SHARED and DM_RIGHT_EXCL. The dm_request_right() function does not block and fails with [EAGAIN] when the requested right cannot be obtained. If a DM application needs to block interruptibly until the requested right is available, then the DM_RR_WAIT flag should be set in the flags argument.

If a process holds a shared access right (DM_RIGHT_SHARED) to an object and requests an exclusive right (DM_RIGHT_EXCL) in a non-blocking mode (the DM_RR_WAIT flag is not set in the flags argument), then the request fails immediately with [EACCES] and the shared lock is not released.

If a process attempts to upgrade from a DM_RIGHT_SHARED to an DM_RIGHT_EXCL lock in a non-blocking mode (the DM_RR_WAIT flag is not set in the flags argument), then the request may work. If the request fails, [EBUSY] is returned, but the shared lock is not released. If the request succeeds, the shared lock may have been released before the exclusive lock was obtained.

When requesting access rights to an object via dm_request_right(), the requested right may not be immediately available. If the DM application has specified that it wants to block until the right becomes available, the DM application may or may not be blocked interruptibly. The implementation of the DMAPI specifes the semantics that apply for interrupting blocked processes. When interrupts are allowed and occur, the call fails with [EINTR].

dm_sessid_t sid (I)

The identifier for the session of interest.

void *hanp (I)

The handle for the file system object for which access rights are being requested.

size_t hlen (I)

The length of the handle in bytes.

dm_token_t token (I)

The token that references the access rights for the object to be manipulated. DM_NO_TOKEN cannot be used with dm_request_right().

u_int flags (I)

If the DM_RR_WAIT flag is not set and the requested right is not available, the calling process fails with [EAGAIN]. If DM_RR_WAIT is set and the requested right is not available, the calling process blocks interruptibly, waiting for the requested right to become available.

dm_right_t right (I)

The requested access right.

USAGE NOTES

See Access Rights for more information about how dm_request_right() should be used.

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 process attempted to upgrade a lock in blocking mode.

[EAGAIN]

The flags parameter did not have the DM_RR_WAIT flag set, and the process would be blocked in requesting the right.

[EBADF]

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

[EBUSY]

The upgrade from DM_RIGHT_SHARED to DM_RIGHT_EXCL cannot be granted.

[EFAULT]

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

[EINTR]

The DMAPI implementation allows interruption and the process was interrupted.

[EINVAL]

The requested right is not valid.

[EINVAL]

The session or token is not valid or token was DM_NO_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_create_userevent(), dm_respond_event(), dm_release_right(), dm_get_fileattr(), dm_query_right().

NAME

dm_respond_event - respond to an event

SYNOPSIS

int 
dm_respond_event(
    dm_sessid_t     sid, 
    dm_token_t      token,
    dm_response_t   response,
    int             reterror,
    size_t          buflen,
    void           *respbufp)

DESCRIPTION

Once a synchronous message has been received via dm_get_events(), it must be responded to. Otherwise, the application that caused the event to be generated is blocked, system resources is tied up, and so forth.

The token identifies the message. Once this call has returned, the token is no longer valid.

Some DMAPI implementations may provide extensions to the basic event facility, such as the ability to return attribute information when responding to an event. These extensions will utilize the respbufp parameter. Normal event responses will only make use of the response code and corresponding reterror value.

dm_sessid_t sid (I)

The identifier for the session of interest.

dm_token_t token (I)

The token identifying the message.

dm_response_t response (I)

The action to be taken by the operating system. Valid actions are DM_RESP_CONTINUE, which continues the operation, or DM_RESP_ABORT, which aborts the operation and sets the errno of the calling process to reterror. DM_RESP_DONTCARE is also valid when responding to the mount event.

int reterror (I)

If the operation is to be aborted (response is set to DM_RESP_ABORT), return errno to the application that caused the event. reterror is returned to the user, even if it is set to zero.

size_t buflen (I)

The length of the response buffer in bytes. Only used by implementations that provide extensions to the DMAPI.

void *respbufp (I)

Buffer for DMAPI implementation extensions. The format of this buffer is not defined 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]

buflen is larger than the implementation defined limit. The limit can be determined by calling the dm_get_config() function using DM_CONFIG_MAX_ATTRIBUTE_SIZE.

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

[ESRCH]

The token does not reference a valid message.

SEE ALSO

dm_get_events().

NAME

dm_send_msg - send a message to the indicated session

SYNOPSIS

int
dm_send_msg(
    dm_sessid_t    targetsid,
    dm_msgtype_t   msgtype,
    size_t         buflen,
    void          *bufp)

DESCRIPTION

The dm_send_msg() function allows an event message of type user to be enqueued on the indicated session. The contents of the message data are opaque to the DMAPI. The message remains enqueued until the indicated target session receives it with dm_get_events().

dm_send_msg() can send both synchronous and asynchronous messages. If the type is DM_MSGTYPE_SYNC, then a synchronous message is created, and the calling process blocks until a response is returned. The DMAPI generates a token that references no access rights. If the type is DM_MSGTYPE_ASYNC, then an asynchronous event message is created, and the calling process is not blocked. The DMAPI does not generate a token for asynchronous messages. The lack of a valid token is identified to the receiver of the event by a value of DM_INVALID_TOKEN in the token field of the event message.

dm_sessid_t targetsid (I)

The session the message should be enqueued upon.

dm_msgtype_t msgtype (I)

The type of message to be enqueued: DM_MSGTYPE_SYNC or DM_MSGTYPE_ASYNC.

size_t buflen (I)

The length of the data buffer in bytes.

void *bufp (I)

The data that is to be incorporated into the generated message. If buflen is zero, this parameter is ignored.

RETURN VALUE

Upon successful completion, the function dm_send_msg() returns zero for asynchronous messages. The return value for synchronous messages is dependent on the return code from the event servicing. Otherwise a value of -1 is returned and errno is set to one of the following values:

[E2BIG]

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

[EFAULT]

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

[EINTR]

Interrupted. The event was not delivered.

[EINVAL]

The session is not valid.

[EINVAL]

The type is not DM_MSGTYPE_SYNC or DM_MSGTYPE_ASYNC.

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

NAME

dm_set_disp - set the disposition of events on a file system for a session

SYNOPSIS

int
dm_set_disp(
    dm_sessid_t     sid,
    void           *hanp,
    size_t          hlen,
    dm_token_t      token,
    dm_eventset_t  *eventsetp,
    u_int           maxevent)

DESCRIPTION

After establishing a session, a DM application must indicate which events to deliver to the session. The event set is the complete set of all events, including managed region events, that the DM application is monitoring during the life of this session. This event set is not persistent across reboots.

The dm_set_disp() function establishes a (event, file system, session) binding that lets the DMAPI implementation know which session to send events to. Until it has completed, the DMAPI implementation has no way of knowing what session should receive events that are generated on a file system. Once dm_set_disp() has returned to the calling DM application, the session starts receiving events as they are generated by the DMAPI implementation.

If a specific event in eventsetp already has been established for the file system indicated by hanp, then the prior (event, file system, session) binding is replaced by the one specified by the eventsetp parameter. It is not possible to target the same event to multiple sessions simultaneously (except for the special case of the mount event).

DM applications must register the event list and session binding using a file system handle; it is not possible to use arbitrary file system objects (such as regular files). Since the file system handle can only be obtained after the file system has been mounted, it is not possible to specify the mount event using the file system handle. The global handle must be used. If the mount event is specified using the file system handle, the behavior is undefined. If events other than the mount event are specified for the global handle, the behavior is also undefined.

dm_sessid_t sid (I)

The identifier for the session of interest.

void *hanp (I)

The handle for the file system or the global 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 DM_RIGHT_EXCL or the token DM_NO_TOKEN may be used and the interface acquires the appropriate rights.

dm_eventset_t *eventsetp (I)

The list of default events to be monitored for this session.

u_int maxevent (I)

The number of events to be checked for dispositions in the event set. The events from 0 to maxevent-1 are examined.

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 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 is not a file system handle.

[EINVAL]

The session is not valid.

[EINVAL]

The token is not valid.

[ENOMEM]

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

[ENXIO]

The implementation of the DMAPI does not support registering for events on the specified handle.

[EPERM]

The caller does not hold the appropriate privilege.

SEE ALSO

dm_create_session(), dm_set_eventlist(), dm_getall_disp().

NAME

dm_set_dmattr - create or replace a data management attribute

SYNOPSIS

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

DESCRIPTION

The dm_set_dmattr() function creates or replaces the value of the named attribute with the specified data.

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 created or replaced.

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 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 to be created or replaced.

int setdtime (I)

The file's attribute time stamp is updated if setdtime is non-zero.

size_t buflen (I)

The size of the buffer in bytes.

void *bufp (I)

The buffer containing the attribute data.

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 attribute value exceeds one of the implementation definied storage limits.

[E2BIG]

buflen is larger than the implementation defined limit. The limit can be determined by calling the dm_get_config() function.

[EACCES]

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

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

[EIO]

An attempt to write the new or updated attribute resulted in an I/O error.

[EINVAL]

The argument token is not a valid token.

[EINVAL]

The session is not valid.

[ENOMEM]

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

[ENOSPC]

An attempt to write the new or updated attribute resulted in an error due to no free space being available on the device.

[ENOSYS]

The DMAPI implementation does not support this optional function.

[EPERM]

The caller does not hold the appropriate privilege.

[EROFS]

The operation is not allowed on a read-only file system.

SEE ALSO

dm_get_dmattr(), dm_remove_dmattr(), dm_getall_dmattr().

NOTES

dm_set_dmattr() is an optional component of the DMAPI.

NAME

dm_set_eventlist - set the list of events to be enabled for an object

SYNOPSIS

int
dm_set_eventlist(
    dm_sessid_t      sid,
    void            *hanp,
    size_t           hlen,
    dm_token_t       token,
    dm_eventset_t   *eventsetp,
    u_int            maxevent)

DESCRIPTION

To receive events on an object, a DM application must bind a set of events to an object, indicating to the DMAPI that the application is monitoring the object. The dm_set_eventlist() function establishes a binding of events on the indicated object that may be persistent. Persistence of event bindings is implementation defined, and can be determined via the dm_get_config() function.

The two functions dm_set_disp() and dm_set_eventlist() work together to enable DM applications to receive events. dm_set_eventlist() controls the generation of events on an object, by specifying which file system operations should generate a DMAPI event. dm_set_disp() controls the delivery of events by specifying which session should receive the generated event.

Events can be enabled on any file system object, including regular files. The managed region events cannot be specified via dm_set_eventlist() since they are specific to each managed region. The mount event cannot be specified, since it is generated by all file system types that support the DMAPI.

dm_sessid_t sid (I)

The identifier for the session of interest.

void *hanp (I)

The handle for the object. The handle can be either the file system handle or a file 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 DM_RIGHT_EXCL or the token DM_NO_TOKEN may be used and the interface acquires the appropriate rights.

dm_eventset_t *eventsetp (I)

The list of events to be enabled for the object.

u_int maxevent (I)

The number of events to be checked for dispositions in the event set. The events from 0 to maxevent-1 are examined.

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

[EINVAL]

Tried to set event on a global handle.

[ENOMEM]

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

[ENXIO]

The implementation of the DMAPI does not support enabling event delivery on the specified handle.

[EPERM]

The caller does not hold the appropriate privilege.

[EROFS]

The operation is not allowed on a read-only file system.

SEE ALSO

dm_get_eventlist(), dm_set_disp(), dm_set_region(), macro DMEV_SET .

NAME

dm_set_fileattr - set file time stamps, ownership and mode

SYNOPSIS

int
dm_set_fileattr(
    dm_sessid_t     sid,
    void           *hanp,
    size_t          hlen,
    dm_token_t      token,
    u_int           mask,
    dm_fileattr_t  *attrp)

DESCRIPTION

The dm_set_fileattr() function allows DM applications to set various file attributes as defined by the dm_fileattr structure.

Each field corresponding to a bit in the mask is used to set the corresponding attribute in the file. For fields that are not specified to be set, the current value is not modified. For example, if DM_AT_CTIME is not set, the file's ctime field is not modified.

If the call to dm_set_fileattr() requests updates of both dm_ctime and dm_dtime, and the DMAPI implementation overloads dm_ctime and dm_dtime, then dm_ctime is used.

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

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 DM_RIGHT_EXCL 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_fileattr structure to set. The mask is constructed by OR-ing together one or more of the following flags:

DM_AT_ATIME

The file's access time stamp.

DM_AT_MTIME

The file's data modification time stamp.

DM_AT_CTIME

The file's status change time stamp.

DM_AT_DTIME

The time stamp of the persistent attributes if associated with the file. The value is ignored if no DM attributes exist.

DM_AT_UID

User ID of the file's owner.

DM_AT_GID

Group ID of the file's owner.

DM_AT_MODE

The mode of the file as described by the mknod(2) system call.

DM_AT_SIZE

The size of the file. May cause a system dependent error to occur, possibly a ENOSPC.

dm_fileattr_t *attrp (I)

The dm_fileattr structure with the appropriate fields defined. For fields that are not set, the corresponding fields of the dm_fileattr structure are not used.

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

I/O error resulted in failure of operation.

[ENOMEM]

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

[EPERM]

The caller does not hold the appropriate privilege.

[EROFS]

The operation is not allowed on a read-only file system.

SEE ALSO

dm_fileattr_t().

NAME

dm_set_inherit - mark an attribute inheritable

SYNOPSIS

int
dm_set_inherit(
    dm_sessid_t     sid,
    void           *hanp,
    size_t          hlen,
    dm_toke n_t     token,
    dm_attrname_t  *attrnamep,
    mode_t          mode)

DESCRIPTION

The function dm_set_inherit() marks the attribute specified by attrnamep as an inheritable attribute for the file system specified by the handle. An attribute is inherited from the parent directory during file creation. The inheritability property of attributes is not persistent across reboots. The access right referenced by the token for the object must be DM_RIGHT_EXCL.

dm_sessid_t sid (I)

The identifier for the session of interest.

void *hanp (I)

The file system handle for which the inheritable attributes should be set.

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 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 to be marked as inheritable.

mode_t mode (I)

The argument mode limits the scope of inheritance to file objects created of specified values. mode is taken from Single UNIX Specification values.

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 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 hanp does not refer to a file system handle.

[EINVAL]

The argument mode does not contain valid file types.

[EINVAL]

The session or token is not valid.

[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_clear_inherit(), dm_getall_inherit().

NOTES

dm_set_inherit() is an optional component of the DMAPI.

NAME

dm_set_region - set the managed regions for a file

SYNOPSIS

int
dm_set_region(
    dm_sessid_t     sid,
    void           *hanp,
    size_t          hlen,
    dm_token_t      token,
    u_int           nelem,
    dm_region_t    *regbufp,
    dm_boolean_t   *exactflagp)

DESCRIPTION

The dm_set_region() function replaces the set of managed regions for a regular file. The implementation has the right to round the boundaries or change the number of managed regions. The final set of managed regions must cover the requested regions. Overlapping managed regions are not permitted.

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. A region may extend to the end of a file and allow control on files that are appended to, by setting rg_size to zero. 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.

The implementation is free to reorder the managed region set. A subsequent call to dm_get_region() may return the managed regions in a different order than they were provided to dm_set_region(). The DMAPI implementation is also permitted to coalesce contiguous or noncontiguous regions with identical rg_flags. The exactflagp is set to DM_TRUE if the file system did not alter the managed region set.

For operations involving multiple managed regions within a file, only one region event is generated for the operation. It is up to the DM application to respond appropriately to all managed regions that are affected by an operation.

dm_sessid_t sid (I)

The identifier for the session of interest.

void *hanp (I)

Handle for the regular file to be affected.

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 DM_RIGHT_EXCL or the token DM_NO_TOKEN may be used and the interface acquires the appropriate rights.

u_int nelem (I)

The number of input regions in regbufp. If nelem is 0, then all existing managed regions are cleared.

dm_region_t *regbufp (I)

A pointer to the structure defining the regions to be set. May be NULL if nelem is zero.

dm_boolean_t *exactflagp (O)

If DM_TRUE, the file system did not alter the requested managed region set.

Valid values for the rg_flags field of the region structure are created by OR'ing together one or more of the following values:

DM_REGION_READ

Enable synchronous event for read operations that overlap this managed region.

DM_REGION_WRITE

Enable synchronous event for write operations that overlap this managed region.

DM_REGION_TRUNCATE

Enable synchronous event for truncate operations that overlap this managed region.

DM_REGION_NOEVENT

Do not generate any events for this managed region.

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 number of regions specified by nelem exceeded the implementation capacity.

[EACCES]

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

[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 refer to a regular file.

[EINVAL]

The regions passed in are not valid because they overlap or some other problem.

[EINVAL]

The session is not valid.

[EIO]

An I/O error resulted in failure of operation.

[ENOMEM]

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

[EPERM]

The caller does not hold the appropriate privilege.

[EROFS]

The operation is not allowed on a read-only file system.

SEE ALSO

dm_get_region(), dm_get_eventlist().

NAME

dm_set_return_on_destroy - specify a DM attribute to return with destroy events

SYNOPSIS

int
dm_set_return_on_destroy(
    dm_sessid_t      sid,
    void            *hanp,
    size_t           hlen,
    dm_token_t       token,
    dm_attrname_t   *attrnamep,
    dm_boolean_t     enable)

DESCRIPTION

The dm_set_return_on_destroy() function allows a DM application to specify one data management attribute whose data is returned with destroy events generated for the specified file system. The implementation, if it supports persistent attributes, delivers a copy of the attribute data with destroy events generated after this function returns successfully.

The data may be truncated if it was greater than the maximum number of bytes that the implementation can return (returned by dm_get_config() for the DM_MAX_ATTR_BYTES_ON_DESTROY flag). If a destroyed object on the file system did not have the specified attribute set, then no data is returned with the corresponding destroy events.

This binding does not persist after unmounting of the file system.

dm_sessid_t sid (I)

The identifier for the session of interest.

void *hanp (I)

The handle for the file system of interest.

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 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 to be returned with destroy events.

dm_boolean_t enable (I)

Set to DM_TRUE to enable returning attributes. Set to DM_FALSE to disable returning attributes.

Return Values

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 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 does not refer to a file system.

[EINVAL]

The session is not valid.

[EINVAL]

The attribute name 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_eventlist().

NOTES

dm_set_return_on_destroy() is an optional component of the DMAPI.

NAME

dm_symlink_by_handle - create a symbolic link using a DM handle

SYNOPSIS

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

DESCRIPTION

The dm_symlink_by_handle() function allows applications the ability to create a symbolic link 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 file system object for which it still has the data and attributes stored on alternate media.

This function creates the link with the specified path as its value (that is, the new object created will be a symbolic link pointing to path)

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

size_t hlen (I)

The length of the file handle in bytes.

char *cname (I)

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

char *path (I)

The path to which the symbolic link points.

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 directory 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_create_by_handle(), dm_mkdir_by_handle().

NOTES

dm_symlink_by_handle() is an optional component of the DMAPI.

NAME

dm_sync_by_handle - synchronize a file's in-memory state with that on the physical medium

SYNOPSIS

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

DESCRIPTION

The dm_sync_by_handle() function causes all modified data and attributes of the object referred to by hanp to be written to its physical media. When dm_sync_by_handle() returns, the state of the object referred to by hanp is captured on physical medium. This is the equivalent of fsync(2), except that the object is referenced by the handle.

dm_sessid_t sid (I)

The identifier for the session of interest.

void *hanp (I)

A handle to any file in the file system.

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 DM_RIGHT_EXCL or the token DM_NO_TOKEN may be used and the interface acquires the appropriate rights.

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]

hanp 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]

The DMAPI implementation does not support this optional function.

[EPERM]

The caller does not hold the appropriate privilege.

NOTES

dm_sync_by_handle() is an optional component of the DMAPI.

NAME

dm_upgrade_right - upgrade a currently held access right to an exclusive right

SYNOPSIS

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

DESCRIPTION

Upgrade the access right currently held for the object specified by the handle and referenced by the token. The upgrade operation does not drop the access right currently held for the object and attempts to upgrade without blocking the process requesting to upgrade.

The minimum right to hold when making this request is DM_RIGHT_SHARED. If a process requests to upgrade while holding an exclusive right, the request succeeds with no attempt to upgrade. Otherwise the attempt to upgrade is tried without blocking the process. If the requested right cannot be obtained without blocking, the request fails.

On DMAPI implementations that do not support non-blocking right upgrades, this call fails with [ENOSYS].

dm_sessid_t sid (I)

The identifier for the session of interest.

void *hanp (I)

The handle for the file system object for which upgrading access right is being requested and with which an access right is already associated. See also dm_downgrade_right .

size_t hlen (I)

The length of the handle in bytes.

dm_token_t token (I)

The token referencing the access right for the object.

IMPLEMENTATION NOTE

A DM application may retry upgrading an access right if dm_upgrade_right() fails with [EBUSY]. This is an indication that there is at least one other process holding a shared access right to the same object. Note that the request to upgrade can only be granted if the requesting process is the only holder of a shared or exclusive right to the object. In the case of another process holding a shared right to the same object, the requesting process must be aware of possible deadlock that can be caused when at least one other process tries to upgrade its access right.

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.

[EBUSY]

Could not upgrade access right.

[EFAULT]

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

[EINVAL]

The token does not grant a DM_RIGHT_SHARED or DM_RIGHT_EXCL 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_SHARED nor DM_RIGHT_EXCL.

SEE ALSO

dm_downgrade_right(), dm_release_right(),() dm_request_right().

NOTES

dm_upgrade_right() is an optional component of the DMAPI.