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:
-
file system administration
-
namespace
-
data
-
metadata
-
pseudo 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:
-
old parent directory
-
new parent directory
-
filesystem handle for the file system containing the object to be renamed.
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.