Previous section.

Systems Management: Data Storage Management (XDSM) API

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

Event Types

Overview

This chapter enumerates the types of events that can be generated, explains the data sent with the event message, and indicates what rights if any will be conveyed to the receiver of the event message.

Each event message consists of a common portion and an event specific portion. The common portion consists of the event type, a token, a sequence number, and the length of the data.

The common portion will not be shown in the following descriptions of events. For specific information on the layout of event messages, see Event Message Types, Event Message Types .

There are five classes of events:

Events can be either synchronous or asynchronous, as determined by the event type. Synchronous events allow a DM application to take action before an operation is continued by the operating system. For all events, it is not possible for a DM application to implement the operation in user space as though it were part of the operating system.

The DM application can respond to synchronous events in a number of ways. The operation can be continued, or it can be aborted with a specified error code returned back to the originating user process. For the mount event, the DM application can instruct the DMAPI implementation that it is not interested in the event, and the event should be sent to another session - see Setting Event Disposition, Setting Event Disposition for more information. Some DMAPI implementations may also support a retry response to a nospace event. If retry is supported, the operation will be retried by the operating system if the response to nospace is DM_RESP_CONTINUE. Support of a retry is indicated by the DM_CONFIG_WILL_RETRY boolean returned via dm_get_config().

Asynchronous messages inform the DM application of the success or failure of an operation in the Operating System. They are delivered asynchronously with respect to the process performing the operation and offer no opportunity for a DM application to affect the requesting process; thus they are for notification purposes rather than for control.

Due to their asynchronous nature, there is no inherent upper bound on the number of undelivered asynchronous messages that may be queued on a session. Therefore implementations must choose either a reliable or an unreliable model for asynchronous messages.

In the reliable model, no asynchronous messages are ever lost. However, this requires that once the number of undelivered asynchronous messages reaches an implementation-defined maximum, processes attempting to generate additional messages are blocked until previously queued messages are delivered.

In the unreliable model, the implementation may simply drop messages when the undelivered message count exceeds an implementation limit.

A conforming DMAPI implementation shall document which model it provides for asynchronous messages. It is recommended that implementations adopt a reliable model, or failing that, an unreliable model that provides reliable semantics in all but the most unusual cases.

For synchronous messages, tokens identify the message. Each synchronous event message may convey the access rights that are required by the DM application; however, it is not guaranteed. The same message may even convey different access rights, depending on the code path taken in the operating system. DM applications must use the dm_query_right() and dm_request_right() interfaces to obtain the proper access rights for their operations. For asynchronous messages, there is no token.

Implementation Responsibilities

The DMAPI implementation must specify for each event the behavior, in the case that an event needs to be generated but no session has been established to receive the event message. This is different from the case where a session exists but there is no process to receive the event message (for example, the DM application has died). Some implementation alternatives are discussed in Undeliverable Events, Undeliverable Event Messages .

The implementation of the DMAPI will also need to define whether each individual synchronous event is interruptible. Since placement of events in the operating system is not defined by the DMAPI, interruptibility cannot be mandated by this interface specification.

Interruptible Events

If an implementation provides interruptible events, it must guarantee that event messages which convey access rights cannot vanish out from underneath a DM application while a DM operation is in progress.

Figure: Interrupting a Synchronous Message

In Interrupting a Synchronous Message , the user has performed an operation that caused a synchronous event message, sync msg1, to be generated. The message has been received by the DM application, and is being processed. Assume the message conveyed rights to the DM application. If the implementation allows the user to interrupt the operation that caused the event message, the DMAPI implementation must complete any DM operation that is in progress for the associated event token, before processing the user interruption signal and returning control to the user thread. The DMAPI implementation must also clean up any outstanding access rights associated with the token, if the token is about to become invalid.

It is important to note that a DM application that is restartable depends on the existence of event messages to determine the state of the application before it died. Therefore, the DMAPI implementation must always keep the session message queues in an orderly state. If a token is invalidated by a user interruption, all state associated with that token must be cleaned up by the DMAPI implementation.

Asynchronous Namespace Event Delivery

Asynchronous namespace event messages are always generated for operations that succeed. It is implementation defined as to whether or not an asynchronous event message is sent for a failed operation.

Invalid Handles

Namespace event messages and mount event can contain invalid handles. For example, a DMAPI implementation may deliver an invalid handle for an object which belongs to a file system type that is not supported by this implementation of DMAPI. Call the dm_handle_is_invalid() function to determine if the handle is valid.

File System Administration Events

mount

This event is generated at the point of a mount operation where the operation will succeed, but access to the file system has not yet been granted. This event allows DM applications to initialize, and provides them with the filesystem handle. This event is synchronous.

The mount event is unlike other events in that it may be sent to multiple sessions; see The "mount" Event for more information. Any DMAPI interface that interacts only with the objects referenced by the handles supplied in the mount event, using the token supplied in the mount event, will work while the mount event token is held. All other DMAPI calls are undefined during mount.

The event message contains the following specific information:

fs handle
filesystem handle.

mountpoint handle
handle for the directory to be mounted over, maybe invalid.

mountpoint path
path name of the directory to be mounted over.

media designator
file system media designator.

mode
0 or DM_MOUNT_RDONLY.

root handle
handle for the root inode of the mounted file system.

preunmount

This event is generated at the point of an unmount operation where the operation is about to check for open files. Events for this file system may still be generated after the preunmount event. This allows the DM application to close any active accesses and "cd" out of the file system so that a DM application itself does not cause an unmount to fail. This event is synchronous.

The event message contains the following specific information:

fs handle
filesystem handle.

rootdir handle
handle to the root directory of the file system.

unmount mode
0 or DM_UNMOUNT_FORCE.

unmount

This event is generated after the operating system has attempted to unmount a file system. A return code of zero indicates the unmount was successful, and the file system is no longer mounted. Once unmounted, the DMAPI will not generate any other events for the file system until it is remounted. A non-zero return code indicates the unmountattempt failed. The reason for failure is given by the value of the return code. The DMAPI will continue to generate events for the file system after a failed unmount. The DMAPI implementation will always continue the operation, ignoring the response code from the DM application. This event is synchronous.

The event message contains the following specific information:

fs handle
filesystem handle.

unmount mode
0 or DM_UNMOUNT_FORCE.

retcode
return code of the operation (0 or errno).

nospace

This event is generated when an operation fails with ENOSPC. If the DMAPI implementation supports operation retry (DM_CONFIG_WILL_RETRY in the dm_get_config() function), a DM_RESP_CONTINUE response will cause the operation that produced the ENOSPC error to be generated to be retried. This event is synchronous.

The event message contains the following specific information:

fs handle
filesystem handle for file system where the ENOSPC error occurred.

debut

If the debut event is specified when a DM application registers via dm_set_disp(), the DMAPI implementation will generate this event at least once before any of the set of other possible events are generated for the object. The debut event provides a mechanism for managing non-persistent attributes. It gives the DM application an opportunity to reset managed regions and event lists each time an object becomes active. If the DMAPI implementation supports persistent managed regions and persistent event lists (DM_CONFIG_PERS_MANAGED_REGIONS and DM_CONFIG_PERS_EVENTS in the dm_get_config() function), this event may not be generated. For DMAPI implementations that do not provide persistent storage of managed regions or event lists, the DM application should set the managed region list and a specific event list for the object. Most likely, the event list will not include the debut event, but instead will only include events that require some action to be performed by the DM application.

DMAPI implementations that do not support persistent non-opaque DM attributes directly are not required to support debut events; they may implement the functionality of the debut event through other internal mechanisms. This event is synchronous and optional.

The event message contains the following specific information:

object handle
object that is being accessed.

Namespace Events

Namespace operations allow a DM application to permit or deny an operation from continuing in the operating system. The synchronous events are generated before the operation has completed; there is no guarantee that the operation will be successful, however. Asynchronous namespace event messages are always generated for operations that succeed. It is implementation defined as to whether or not an asynchronous event message is sent for a failed event.

The DMAPI guarantees the ordering of paired namespace events. Asynchronous post event messages will always be generated after synchronous before event messages. If there are multiple synchronous events on a directory entry, it is not guaranteed that the associated asynchronous events are properly interleaved.

Namespace event messages are generated based on the directory entry that is being affected. If a DM application wants to receive namespace events for every file in the file system, it should do a dm_set_eventlist() using the filesystem handle.

create

This event is generated before the operating system adds a new entry to a directory. This event is synchronous. There is no guarantee that the operation will be successful.

The event message contains the following specific information:

parent handle
parent directory where entry name will be added.

entry name
name of the new entry.

mode
type of the object to be created and is the same value as st_mode in struct stat and dt_mode in struct dm_stat.

The DM application can either allow the operation to continue (DM_RESP_CONTINUE) or return an error code.

postcreate

This event is generated after the operating system has attempted to add an entry to a directory. This event is asynchronous.

The event message contains the following specific information:

parent handle
parent directory where entry name was added.

entry handle
handle for the new entry.

entry name
entry name that was added to the directory.

mode
type of the object created and is the same value as st_mode in struct stat and dt_mode in struct dm_stat.

retcode
return code of the operation (0 or errno).

remove

This event is generated before the operating system removes an entry from a directory. This event is synchronous. There is no guarantee that the operation will be successful.

The event message contains the following specific information:

parent handle
parent directory where entry name will be removed.

entry name
entry name to be removed from the directory.

mode
type of the object to be removed and is the same value as st_mode in struct stat and dt_mode in struct dm_stat.

The DM application can either allow the operation to continue (DM_RESP_CONTINUE) or return an error code.

postremove

This event is generated after the operating system has attempted to remove an entry from a directory. This event is asynchronous.

The event message contains the following specific information:

parent handle
parent directory where entry name was removed.

entry name
entry name removed from the directory.

mode
type of the object removed and is the same value as st_mode in struct stat and dt_mode in struct dm_stat.

retcode
return code of the operation (0 or errno).

rename

This event is generated before the operating system renames a directory entry in a file system. This event is synchronous. There is no guarantee that the operation will be successful.

The event message contains the following specific information:

old parent handle
original parent directory where old entry name resides.

new parent handle
new parent directory where new entry name is to be added.

old entry name
directory entry to be renamed.

new entry name
new name of directory entry.

The DM application can either allow the operation to continue (DM_RESP_CONTINUE) or return an error code.

postrename

This event is generated after the operating system has attempted to rename an entry in a file system. This event is asynchronous.

The event message contains the following specific information:

old parent handle
original parent directory where old entry name resided.

new parent handle
new parent directory where new entry name was added.

old entry name
original directory entry that was renamed.

new entry name
new name of directory entry.

retcode
return code of the operation (0 or errno).

symlink

This event is generated before the operating system adds a new symbolic link entry in a directory. This event is synchronous. There is no guarantee that the operation will be successful.

The event message contains the following specific information:

parent handle
parent directory where symlink entry name will be added.

symlink entry name
name of symbolic link entry.

symlink contents
contents of symbolic link.

The DM application can either allow the operation to continue (DM_RESP_CONTINUE) or return an error code.

postsymlink

This event is generated after the operating system has attempted to add a symbolic link entry in a directory. This event is asynchronous.

The event message contains the following specific information:

parent handle
parent directory where symlink entry name was added.

entry handle
handle for the new symlink entry.

symlink entry name
entry name of newly added symbolic link.

symlink contents
contents of symbolic link.

retcode
return code of the operation (0 or errno).

link

This event is generated before the operating system adds a new hard link entry in a directory. This event is synchronous. There is no guarantee that the operation will be successful.

The event message contains the following specific information:

parent handle
parent directory where target entry name will be added.

source link handle
handle of entry to be linked to.

target entry name
new link name to be added to the directory.

The DM application can either allow the operation to continue (DM_RESP_CONTINUE) or return an error code.

postlink

This event is generated after the operating system has attempted to add a new hard link entry in a directory. This event is asynchronous.

The event message contains the following specific information:

parent handle
parent directory where target entry name was added.

source link handle
handle of entry that was linked to.

target entry name
new link name added to the directory.

retcode
return code of the operation (0 or errno).

Data Events

Data events are triggered by interactions with managed regions. They are synchronous, and allow the DM application to take some action before the operation is continued in the operating system. Data events only occur on regular files.

read

This event is generated when a read of a file overlaps one or more managed regions that have the event set in the managed region flags field. This event is synchronous.

The event message contains the following specific information:

file handle
handle for file being read.

offset
starting offset of read operation.

length
length in bytes of read request.

write

This event is generated when a write to a file overlaps one or more managed regions that have the event set in the managed region flags field. This event is synchronous.

The event message contains the following specific information:

file handle
handle for file being written.

offset
starting offset for write operation.

length
length in bytes of write request.

truncate

This event is generated when the operating system attempts a truncation of a file that overlaps one or more managed regions that has the event set in the managed region flags field. This event can be generated directly in response to a truncate request by the user, as from truncate(2), or indirectly as when an existing file is truncated via open(2) with the appropriate flags. This event is synchronous.

The event message contains the following specific information:

file handle
handle for file being truncated.

offset
starting offset for truncation operation.

Metadata Events

attribute

This event is generated when an object is changed in a way that affects the change time (dt_ctime) value returned by dm_get_bulkattr(), dm_get_dirattrs or dm_get_fileattr(). This event is asynchronous.

The event message contains the following specific information:

object handle
object that was affected.

cancel

This event may be generated when the implementation determines that an earlier request is no longer of interest (for example, if a user terminated an application program). The method of determining that a request is no longer of interest is implementation-dependent. The DM application may react to this event according to its preference; however, the original event, the one being cancelled, must still receive a response such as DM_RESP_ABORT or DM_RESP_CONTINUE. This event is asynchronous.

The intent of this event message is that in advising a DM application that a given result is no longer of interest, the DM application might be better able to schedule resources that might otherwise have been devoted to providing that given result. This scheduling may be particularly advisable if long-latency resources were required to satisfy a request.

The data associated with the cancel event is in the dm_cancel_event_t format. The event message contains the following specific information:

sequence
the value of the ev_sequence field for the event being canceled.

token
the token of the original event.

This event is optional.

close

This event is generated on the close of a file system object. (The definition of "close" is implementation-dependent. Typically, it will be on the last close.) This notification is a hint only, and is not guaranteed to be reliable. This event is asynchronous and optional.

The event message contains the following specific information:

object handle
object that is being closed.

destroy

This event is generated when the Operating System has destroyed an object. If the destroyed object had the attribute specified by dm_set_return_on_destroy(), a copy of its attribute data will be returned with the event message. The attribute data may be truncated if it was longer than the maximum supported length for the implementation (returned by dm_get_config() with the DM_CONFIG_MAX_ATTR_ON_DESTROY flag). This event is asynchronous.

The destroy event message contains the following specific information:

object handle
object that was destroyed.

attribute name
attribute name being returned.

attribute copy
copy of attribute data for the object.

Pseudo Events

Pseudo events are events that do not correspond to any operation in the Operating System. Currently, the only defined pseudo event is the user event that is generated by both dm_create_userevent() and dm_send_msg().

user event format

This event structure is used in the dm_create_userevent() and dm_send_msg() functions for both synchronous and asynchronous events. All dm_create_userevent() functions create synchronous event messages. The dm_send_msg() function can be either synchronous or asynchronous. Only synchronous events will associate a token with the event message. Asynchronous events can be indicated by a value of DM_INVALID_TOKEN in the token field. DM applications can use this event type to store information that is associated with the message that is to be created. The message data is not interpreted by the DMAPI implementation.

For more information see the Tokens Tokens and the Events Events .

Since this is not a generated event, the entire event message will be shown, and is as follows:

event type
set to DM_EVENT_USER.

token
token that will be returned or DM_INVALID_TOKEN.

message length
length of the data to follow.

data
private data that the DM application wants to have associated with a message.

Event Summary

A summary of events, the type of objects they are delivered on, and how they are enabled, is given in Event Summary .

Event Sync/Async Enabled By Enabled On
mount sync always enabled global
preunmount sync dm_set_eventlist fs
unmount sync dm_set_eventlist fs
nospace sync dm_set_eventlist fs
debut sync always enabled file, dir or fs
   
create sync dm_set_eventlist dir or fs
postcreate async dm_set_eventlist dir or fs
remove sync dm_set_eventlist dir or fs
postremove async dm_set_eventlist dir or fs
rename sync dm_set_eventlist dir or fs
postrename async dm_set_eventlist dir or fs
symlink sync dm_set_eventlist dir or fs
postsymlink async dm_set_eventlist dir or fs
link sync dm_set_eventlist dir or fs
postlink async dm_set_eventlist dir or fs
   
read sync dm_set_region managed region
write sync dm_set_region managed region
truncate sync dm_set_region managed region
   
attribute async dm_set_eventlist file, dir or fs
cancel async dm_set_eventlist file, dir or fs
close async dm_set_eventlist file, dir or fs
destroy async dm_set_eventlist file, dir or fs
   
user either created by dm_create_userevent and dm_send_msg not applicable

Table: Event Summary

Event Generation Objects lists the objects that the DMAPI implementation will consult to determine if an event should be generated. For example, the rename event will be generated if a rename() occurs where one of the following objects has that event enabled:

Event Controlling Object Handle
mount global
preunmount fs
unmount fs
nospace fs
debut file, dir or fs
 
create parent dir or fs
postcreate parent dir or fs
remove parent dir or fs
postremove parent dir or fs
rename old parent, new parent, or fs
postrename old parent, new parent, or fs
symlink parent dir or fs
postsymlink parent dir or fs
link parent dir or fs
postlink parent dir or fs
 
read file
write file
truncate file
 
attribute file, dir or fs
cancel file, dir or fs
close file, dir or fs
destroy file, dir or fs
 
user n/a

Table: Event Generation Objects

Events are defined via a number of different data structures. Event Data Structures summarizes the event structures that are used to deliver each event.

Event Data structure
mount dm_mount_event
preunmount dm_namesp_event
unmount dm_namesp_event
nospace dm_namesp_event
debut dm_namesp_event
 
create dm_namesp_event
postcreate dm_namesp_event
remove dm_namesp_event
postremove dm_namesp_event
rename dm_namesp_event
postrename dm_namesp_event
symlink dm_namesp_event
postsymlink dm_namesp_event
link dm_namesp_event
postlink dm_namesp_event
 
read dm_data_event
write dm_data_event
truncate dm_data_event
 
attribute dm_namesp_event
cancel dm_cancel_event
close dm_namesp_event
destroy dm_destroy_event
 
user opaque to DMAPI implementation

Table: Event Data Structures

A number of different events use the dm_namesp_event structure. Field Use in the dm_namesp_event Structure lists which fields are valid, and their contents, for each event message that uses this structure.

Event handle1 handle2 name1 name2 mode retcode
preunmount fs rootdir - - unmount mode -
unmount fs - - - unmount mode r/c
nospace fs - - - - -
debut object - - - - -
      
create parent - name - st_mode -
postcreate parent new name - st_mode r/c
remove parent - name - st_mode -
postremove parent - name - st_mode r/c
rename old parent new parent old name new name - -
postrename old parent new parent old name new name - r/c
symlink parent - name contents - -
postsymlink parent new name contents - r/c
link parent source name - - -
postlink parent source name - - r/c
      
attribute object - - - - -
close object - - - - -

- not applicable
r/c return code

Table: Field Use in the dm_namesp_event Structure

The following table describes the fields of the dm_mount_event.

mode mount options
handle1 file system handle
handle2 mounted-on directory handle, may be invalid
name1 mount path
name2 file system media
roothandle root inode handle

Table: Field Use in the dm_mount_event Structure

Why not acquire a nicely bound hard copy?
Click here to return to the publication details or order a copy of this publication.

Contents Next section Index