---

ResourceMonitor Namespace Reference

API for monitoring system resources .See also /opt/resourcemon/doc/html/en/index.html. ResourceMonitor is the name space client applications use. ResourceMonitor library is designed to give a "C" consumer application access to the RM features. More...

Compounds
class	ResourceMonitor::RMdiscovery
class	ResourceMonitor::RMmonitor
class	ResourceMonitor::RMresource
class	ResourceMonitor::RMsession
class	ResourceMonitor::RMstatistic
class	ResourceMonitor::RMsubsystem
Typedefs
typedef void*	rmSessionHandle
Functions
int	rmGetResourceMonitorVersion ()
	returns the library version to be compared to RESOURCE_MONITOR_VERSION to insure compatiblity. More...
size_t	rmGetSubsystemCount ()
	is usually the first function that is called. It discovers the number of subsystems that are available to the resource monitoring facility. More...
int	rmGetAvailableSubsystems (rmSubsystemInfo *buffer, const size_t size)
	discovers the details about subsystems that are available. More...
int	rmGetActiveResources (const rmUID SubsystemId, rmResourceInfo *buffer, const size_t size)
	discovers the details about resources that are available in a subsystem. More...
int	rmGetAvailableStatistics (const rmUID SubsystemId, rmStatisticInfo *buffer, const size_t size)
	discovers the details about statistics that are available in a subsystem. More...
size_t	rmGetMonitorCount ()
	discovers the number of monitors that are being managed by the resource monitoring facility. More...
int	rmGetMonitors (rmMonitorInfo *buffer, size_t *size)
	discovers the details about monitors created by the caller that are being managed by the resource monitoring facility. More...
int	rmGetSubsystemInfo (const rmUID SubsystemId, rmSubsystemInfo *buffer)
	returns the details about a subsystem. More...
rmString	rmGetSubsystemDescription (const rmUID SubsystemId, const enum rmDescriptions which)
	returns a descriptive string about a subsystem. More...
int	rmGetResourceInfo (const rmUID SubsystemId, const rmID ResourceId, rmResourceInfo *buffer)
	returns the details about a resource in a subsystem. More...
rmString	rmGetResourceDescription (const rmUID SubsystemId, const rmID ResourceId, const enum rmDescriptions which)
	returns a descriptive string about a resource. More...
int	rmGetResourceID (const rmUID SubsystemId, const rmString shortdescription, rmID *id)
	get the resource id assigned by the subsystem from a short description string. More...
int	rmGetStatisticInfo (const rmUID SubsystemId, const rmID statId, rmStatisticInfo *buffer)
	returns the details about a statistic in a subsystem. More...
rmString	rmGetStatisticDescription (const rmUID SubsystemId, const rmID statId, const enum rmDescriptions which)
	returns a descriptive string about a statistic. More...
int	rmGetStatisticID (const rmUID SubsystemId, const rmString shortdescription, rmID *id)
	get the statistic id assigned by the subsystem from a short description string. More...
int	rmGetCurrentValue (const rmStatisticKey id, rmValue *value)
	returns the current statistic value of a resource in a subsystem. More...
int	rmGetUpperBound (const rmStatisticKey id, rmValue *value)
	returns the upper bound of a gauge statistic for a resource in a subsystem. More...
int	rmResetCounterStatistic (const rmStatisticKey id, const rmValue *value)
	sets the current statistic value. More...
rmHandle	rmCreateMonitor (const rmMonitorConfiguration *config, rmMonitorControl *control)
	creates a monitor for a statistic made available through a subsystem. More...
rmHandle	rmAccessMonitor (const rmUID MonitorId)
	returns a rmHandle for an existing monitor. More...
int	rmDeleteMonitor (const rmHandle handle)
	removes a monitor from the system and invalidates the rmHandle. More...
int	rmGetMonitorControl (const rmHandle handle, rmMonitorControl *control)
	returns the control parameters of a monitor to the caller. More...
int	rmSetMonitorControl (const rmHandle handle, const rmMonitorControl *control)
	changes the control parameters of a monitor. More...
int	rmGetMonitorConfiguration (const rmHandle handle, rmMonitorConfiguration *config)
	returns the configuration parameters of a monitor to the caller. More...
int	rmSetMonitorConfiguration (const rmHandle handle, const rmMonitorConfiguration *config)
	changes the configuration parameters of a monitor. More...
int	rmStartMonitor (const rmHandle handle)
	starts the monitor. The monitor is resumed retaining state from previous runs in the case of a stopped monitor. More...
int	rmStopMonitor (const rmHandle handle)
	stops the monitor but retains monitor state. More...
int	rmResetMonitor (const rmHandle handle)
	stops the monitor if it is running and resets its state as if it was created. For example, it clears current watermark state, zeros the start and stop times, and resets event notification. See also: ResourceMonitor::rmResetNotification. More...
int	rmPauseNotification (const rmHandle handle)
	allows monitoring to continue but disables any event notification that the monitor would do. More...
int	rmResetNotification (const rmHandle handle)
	reenables a monitor's event notification that was paused by a call to rmPauseNotification() or the monitor is a one shot event monitor with a loggingRate of 0. More...
int	rmGetMonitorState (const rmHandle handle, rmMonitorState *state)
	returns monitor state information. More...
int	rmGetMonitorInfo (const rmHandle handle, rmMonitorInfo *info)
	returns detailed monitor information. More...
rmString	rmGetMonitorDescription (const rmHandle handle, const enum rmDescriptions which)
	returns a descriptive string about a monitor. More...
int	rmSetMonitorDescription (const rmHandle handle, const enum rmDescriptions which, const rmString description)
	set a descriptive string about a monitor. More...
rmSessionHandle	rmCreateConsumerSession ()
	creates a new connection to the Resource Monitor daemon. rmCreateConsumerSession allows a threaded application to a create a separate connection to the daemon for each thread avoiding the need to synchronize access to the Resource Monitor daemon among threads. More...
int	rmCloseConsumerSession (const rmSessionHandle handle)
	closes a connection to the Resource Monitor daemon. More...

---

Detailed Description

API for monitoring system resources .See also /opt/resourcemon/doc/html/en/index.html. ResourceMonitor is the name space client applications use. ResourceMonitor library is designed to give a "C" consumer application access to the RM features.

---

Typedef Documentation

typedef void * ResourceMonitor::rmSessionHandle

rmSessionHandle is for the connection to the Resource Monitor daemon. See also: rmCreateConsumerSession

---

Function Documentation

rmHandle ResourceMonitor::rmAccessMonitor ( const rmUID MonitorId )

returns a rmHandle for an existing monitor. Parameters: MonitorId   the unique ID generated by the resource monitoring facility when a monitor is created. Returns: returns a non-NULL value when successful. errno is set if NULL is returned. errno is set to ESRCH if MonitorId does not exist, EPERM if the caller's user id is not the same as the creator of the monitor. The rmHandle is to be used for subsequent access to the monitor.

int ResourceMonitor::rmCloseConsumerSession ( const rmSessionHandle handle )

closes a connection to the Resource Monitor daemon. See also: rmCreateConsumerSession Returns: 0 if successful, errno.

rmSessionHandle ResourceMonitor::rmCreateConsumerSession ( )

creates a new connection to the Resource Monitor daemon. rmCreateConsumerSession allows a threaded application to a create a separate connection to the daemon for each thread avoiding the need to synchronize access to the Resource Monitor daemon among threads. Returns: 0 if unsuccessful and sets errno, else a valid handle. If the daemon is not running, errno is set to ECONNREFUSED.

rmHandle ResourceMonitor::rmCreateMonitor ( const rmMonitorConfiguration * config, rmMonitorControl * control )

creates a monitor for a statistic made available through a subsystem. Parameters: config   pointer to the caller's rmMonitorConfiguration structure control   pointer to the caller's rmMonitorControl structure. The uid field is updated with the uid generated for this monitor. when the creator does not supply a uid. Returns: successful monitor creation returns a non-NULL value. The rmHandle is to be used for subsequent access to the monitor. errno is set if NULL is returned. errno is set to EBUSY if the daemon has exceeded its CPU utilization level, ENXIO if the subsystem, resource, or statistic id in rmMonitorConfiguration is not available, EEXIST if the provided monitor uid exists already, ENOENT if the data capture library is not available, EIO if the subsystem returns invalid statistic attributes, or EINVAL if any other configuration or control data is invalid. ENOSYS if a subsystem's inline monitor implementation does not support a monitor feature. On success, the uid field of the rmMonitorControl structure is updated with the uid generated for this monitor if one is not provided. See also: RM_CommonStatisticLib for inline monitor feature limitations. Note: Monitoring is not started until rmStartMonitor() is called.

int ResourceMonitor::rmDeleteMonitor ( const rmHandle handle )

removes a monitor from the system and invalidates the rmHandle. Parameters: handle   the token returned by rmCreateMonitor() or rmAccessMonitor(). Returns: ESRCH if handle is invalid

int ResourceMonitor::rmGetActiveResources ( const rmUID SubsystemId, rmResourceInfo * buffer, const size_t size )

discovers the details about resources that are available in a subsystem. Parameters: SubsystemId   the unique ID assigned to a subsystem. buffer   pointer to a caller's buffer that rmGetActiveResources will use to return rmResourceInfo structures and strings. size   the number of bytes in the caller's array. Precondition: A call to rmGetAvailableSubsystems or rmGetSubsystemInfo is use to determine the approximate size of the allocated buffer. Returns: ENXIO if no SubsystemId is found, ENODATA if no resources are available, EAGAIN indicates there are more information structures available. A larger buffer is needed to retrieve them all.

int ResourceMonitor::rmGetAvailableStatistics ( const rmUID SubsystemId, rmStatisticInfo * buffer, const size_t size )

discovers the details about statistics that are available in a subsystem. Parameters: SubsystemId   the unique ID assigned to a subsystem. buffer   pointer to a caller's array of rmStatisticInfo structures. size   the number of rmStatisticInfo structures in the caller's array. Precondition: A call to rmGetAvailableSubsystems or rmGetSubsystemInfo is use to determine the size of the rmStatisticInfo array Returns: ENXIO if no SubsystemId is found, ENODATA if no statistics are available, EAGAIN indicates there are more information structures available. A larger buffer is needed to retrieve them all. See also: rmPsuedoResourceID

int ResourceMonitor::rmGetAvailableSubsystems ( rmSubsystemInfo * buffer, const size_t size )

discovers the details about subsystems that are available. Parameters: buffer   pointer to a caller's arry that rmGetAvailableSubsystems will use to return the rmSubsystemInfo structures. size   the number of rmSubsystemInfo structures in the caller's arry. Precondition: A call to rmGetSubsystemCount is use to determine the size of the rmSubsystemInfo buffer. Returns: EAGAIN if the buffer was not big enough to hold all rmSubsystemInfo structures. A larger buffer is needed to retrieve them all.

int ResourceMonitor::rmGetCurrentValue ( const rmStatisticKey id, rmValue * value )

returns the current statistic value of a resource in a subsystem. Parameters: id   the statistic triplet of subsystem ID, resource ID, and statistic ID. value   pointer to a rmValue union where the value is returned. Returns: ENXIO if any element of rmStatisticKey is not registered with the resource monitoring facility. Note: This method is not intended for polling the statistic. Any action based on the value of a statistic should be triggered an event log notification by setting up a monitor and registering a query with the event log.

int ResourceMonitor::rmGetMonitorConfiguration ( const rmHandle handle, rmMonitorConfiguration * config )

returns the configuration parameters of a monitor to the caller. Parameters: handle   the token returned by rmCreateMonitor() or rmAccessMonitor(). Returns: ESRCH if handle is invalid.

int ResourceMonitor::rmGetMonitorControl ( const rmHandle handle, rmMonitorControl * control )

returns the control parameters of a monitor to the caller. Parameters: handle   the token returned by rmCreateMonitor() or rmAccessMonitor(). Returns: ESRCH if handle is invalid.

size_t ResourceMonitor::rmGetMonitorCount ( )

discovers the number of monitors that are being managed by the resource monitoring facility. Returns: the number of monitors created by the caller through the resource monitoring facility. If return is 0, the daemon may not be running and errno is set to ECONNREFUSED. Note: The count of all monitors is returned to the root user.

rmString ResourceMonitor::rmGetMonitorDescription ( const rmHandle handle, const enum rmDescriptions which )

returns a descriptive string about a monitor. Parameters: handle   the token returned by rmCreateMonitor() or rmAccessMonitor(). which   the string to return. Returns: pointer or if 0 then errno is ESRCH if handle is invalid, ENXIO if which is invalid. Note: the library returns a pointer to a string buffer it allocated. The caller must free the buffer.

int ResourceMonitor::rmGetMonitorInfo ( const rmHandle handle, rmMonitorInfo * info )

returns detailed monitor information. Parameters: handle   the token returned by rmCreateMonitor() or rmAccessMonitor(). info   pointer to caller's rmMonitorInfo structure. Returns: ESRCH if handle is invalid

int ResourceMonitor::rmGetMonitorState ( const rmHandle handle, rmMonitorState * state )

returns monitor state information. Parameters: handle   the token returned by rmCreateMonitor() or rmAccessMonitor(). state   pointer to caller's rmMonitorState structure. Returns: ESRCH if handle is invalid

int ResourceMonitor::rmGetMonitors ( rmMonitorInfo * buffer, size_t * size )

discovers the details about monitors created by the caller that are being managed by the resource monitoring facility. Parameters: buffer   pointer to a caller's array of rmMonitorInfo structures. size   the number of rmMonitorInfo structures in the caller's array as input, the actual number of rmMonitorInfo structures written to buffer on return. Precondition: A call to rmGetMonitorCount is use to determine the size of the rmMonitorInfo array. Returns: EAGAIN indicates there are more information structures available. A larger buffer is needed to retrieve them all. Note: All monitors are returned to the root user.

rmString ResourceMonitor::rmGetResourceDescription ( const rmUID SubsystemId, const rmID ResourceId, const enum rmDescriptions which )

returns a descriptive string about a resource. Parameters: SubsystemId   the unique ID assigned to a subsystem. ResourceId   the resource ID assigned by the subsystem. The ID can be discovered by calling rmGetActiveResources. which   the string to return. Returns: pointer or if 0 then errno is ENXIO if SubsystemId or ResourceId is not registered with the resource monitoring facility. Note: the library returns a pointer to a string buffer it allocated. The caller must free the buffer.

int ResourceMonitor::rmGetResourceID ( const rmUID SubsystemId, const rmString shortdescription, rmID * id )

get the resource id assigned by the subsystem from a short description string. Parameters: SubsystemId   the unique ID assigned to a subsystem. shortdescription   the null-terminated string of the resource. id   the pointer to the rmID to be set. Returns: ESRCH if SubsystemId is invalid or shortdescription is not found. See also: rmDescriptions

int ResourceMonitor::rmGetResourceInfo ( const rmUID SubsystemId, const rmID ResourceId, rmResourceInfo * buffer )

returns the details about a resource in a subsystem. Parameters: SubsystemId   the unique ID assigned to a subsystem. ResourceId   the resource ID assigned by the subsystem. The ID can be discovered by calling rmGetActiveResources. buffer   pointer to a rmResourceInfo structure. Returns: ENXIO if SubsystemId or ResourceId is not registered with the resource monitoring facility.

int ResourceMonitor::rmGetResourceMonitorVersion ( )

returns the library version to be compared to RESOURCE_MONITOR_VERSION to insure compatiblity.

rmString ResourceMonitor::rmGetStatisticDescription ( const rmUID SubsystemId, const rmID statId, const enum rmDescriptions which )

returns a descriptive string about a statistic. Parameters: SubsystemId   the unique ID assigned to a subsystem. statId   the statistic ID assigned by the subsystem. The ID can be discovered by calling rmGetAvailableStatistics. which   the string to return. Returns: pointer or if 0 then errno is ENXIO if SubsystemId or ResourceId is not registered with the resource monitoring facility. Note: the library returns a pointer to a string buffer it allocated. The caller must free the buffer.

int ResourceMonitor::rmGetStatisticID ( const rmUID SubsystemId, const rmString shortdescription, rmID * id )

get the statistic id assigned by the subsystem from a short description string. Parameters: SubsystemId   the unique ID assigned to a subsystem. shortdescription   the null-terminated string of the statistic. id   the pointer to the rmID to be set. Returns: ESRCH if SubsystemId is invalid or shortdescription is not found. See also: rmDescriptions

int ResourceMonitor::rmGetStatisticInfo ( const rmUID SubsystemId, const rmID statId, rmStatisticInfo * buffer )

returns the details about a statistic in a subsystem. Parameters: SubsystemId   the unique ID assigned to a subsystem. statId   the statistic ID assigned by the subsystem. The ID can be discovered by calling rmGetAvailableStatistics. buffer   pointer to a rmStatisticInfo structure. Returns: ENXIO if SubsystemId or statId is not registered with the resource monitoring facility.

size_t ResourceMonitor::rmGetSubsystemCount ( )

is usually the first function that is called. It discovers the number of subsystems that are available to the resource monitoring facility. Returns: the number of subsystems registered with the resource monitoring facility. If return is 0, the daemon may not be running and errno is set to ECONNREFUSED.

rmString ResourceMonitor::rmGetSubsystemDescription ( const rmUID SubsystemId, const enum rmDescriptions which )

returns a descriptive string about a subsystem. Parameters: SubsystemId   the unique ID assigned to a subsystem. which   the string to return. Returns: pointer or if 0 then errno is ENXIO if SubsystemId is not registered with the resource monitoring facility. Note: the library returns a pointer to a string buffer it allocated. The caller must free the buffer.

int ResourceMonitor::rmGetSubsystemInfo ( const rmUID SubsystemId, rmSubsystemInfo * buffer )

returns the details about a subsystem. Parameters: SubsystemId   the unique ID assigned to a subsystem. buffer   pointer to a rmSubsystemInfo structure. Returns: ENXIO if SubsystemId is not registered with the resource monitoring facility.

int ResourceMonitor::rmGetUpperBound ( const rmStatisticKey id, rmValue * value )

returns the upper bound of a gauge statistic for a resource in a subsystem. Parameters: id   the statistic triplet of subsystem ID, resource ID, and statistic ID. value   pointer to a rmValue union where the value is returned. Returns: ENXIO if any element of rmStatisticKey is not registered with the resource monitoring facility. ENOSYS if the statistic has no upper bound or the function is not implemented by the subsystem.

int ResourceMonitor::rmPauseNotification ( const rmHandle handle )

allows monitoring to continue but disables any event notification that the monitor would do. Parameters: handle   the token returned by rmCreateMonitor() or rmAccessMonitor(). Returns: ESRCH if handle is invalid See also: rmResetNotification

int ResourceMonitor::rmResetCounterStatistic ( const rmStatisticKey id, const rmValue * value )

sets the current statistic value. Parameters: id   the statistic triplet of subsystem ID, resource ID, and statistic ID. value   pointer to a rmValue union containing the new statistic value. Returns: ENXIO if any element of rmStatisticKey is not registered with the resource monitoring facility. Note: Some subsystems can not take an arbitrary reset value. For example, in the case of hardware maintained statistics the only value that a statistic can be reset to is zero. See subsystem documentation.

int ResourceMonitor::rmResetMonitor ( const rmHandle handle )

stops the monitor if it is running and resets its state as if it was created. For example, it clears current watermark state, zeros the start and stop times, and resets event notification. See also: ResourceMonitor::rmResetNotification. Parameters: handle   the token returned by rmCreateMonitor() or rmAccessMonitor(). Returns: ESRCH if handle is invalid

int ResourceMonitor::rmResetNotification ( const rmHandle handle )

reenables a monitor's event notification that was paused by a call to rmPauseNotification() or the monitor is a one shot event monitor with a loggingRate of 0. Parameters: handle   the token returned by rmCreateMonitor() or rmAccessMonitor(). Returns: ESRCH if handle is invalid See also: rmPauseNotification rmThresholdControl rmLeakyBucketControl

int ResourceMonitor::rmSetMonitorConfiguration ( const rmHandle handle, const rmMonitorConfiguration * config )

changes the configuration parameters of a monitor. Parameters: handle   the token returned by rmCreateMonitor() or rmAccessMonitor(). Returns: ESRCH if handle is invalid, EINVAL if any configuration parameter is invalid. ENXIO if the subsystem, resource, or statistic id in rmMonitorConfiguration is not the same the rmStatisticKey for this monitor. See also: RM_CommonStatisticLib for inline monitor feature limitations. Note: Most monitor configuration parameters can't be changed once the monitor has been created. The typeConfiguration.threshold parameters can be changed except for its type field. All other parameters changes are invalid.

int ResourceMonitor::rmSetMonitorControl ( const rmHandle handle, const rmMonitorControl * control )

changes the control parameters of a monitor. Parameters: handle   the token returned by rmCreateMonitor() or rmAccessMonitor(). Returns: ESRCH if handle is invalid, ENXIO if uid or monitorId are different from current values, EINVAL for all other invalid control parameter settings. See also: RM_CommonStatisticLib for inline monitor feature limitations. Note: Only the monitoringInterval, monitoringRate, and typeControl.threshold parameters can be changed. monitoringRate can not be set to zero for daemon monitors. All other parameters changes are invalid because they can't be changed once the monitor has been created.

int ResourceMonitor::rmSetMonitorDescription ( const rmHandle handle, const enum rmDescriptions which, const rmString description )

set a descriptive string about a monitor. Parameters: handle   the token returned by rmCreateMonitor() or rmAccessMonitor(). which   the monitor description to set. description   the null-terminated string for the new monitor description. Returns: ESRCH if handle is invalid, ENXIO if which is invalid.

int ResourceMonitor::rmStartMonitor ( const rmHandle handle )

starts the monitor. The monitor is resumed retaining state from previous runs in the case of a stopped monitor. Parameters: handle   the token returned by rmCreateMonitor() or rmAccessMonitor(). Returns: ESRCH if handle is invalid, EBUSY if the daemon process has exceeded its CPU usage limit.

int ResourceMonitor::rmStopMonitor ( const rmHandle handle )

stops the monitor but retains monitor state. Parameters: handle   the token returned by rmCreateMonitor() or rmAccessMonitor(). Returns: ESRCH if handle is invalid

---