mas_get_met(3mas)

mas_get_met, mas_get_met_snap -- get the address of an instance of a metric for consumer use

Synopsis

   cc [options] file -lmas
   
   #include <mas.h>
   caddr_t mas_get_met(int md, metid_t id, uint32 unitnum, ... );
   caddr_t mas_get_met_snap(int md, metid_t id, uint32 unitnum, ... );

Description

The function mas_get_met returns the address of an instance of a metric. The function mas_get_met_snap returns the address of an instance of a metric within the snapshot buffer. The metric must have been previously registered by a provider into a metric registration file with mas_register_met, and the registration file must be opened by the consumer with mas_open prior to calling mas_get_met.

The md argument is a metric descriptor returned from mas_open. The second argument, id, is the metric ID number of the metric whose address will be returned. The remaining arguments are a list of unit numbers, one per resource on which the metric is based. Unit numbers are numbered sequentially from 0 to the value of the resource - 1. If the metric was registered with a resource of MAS_NATIVE or MAS_SYSTEM, unitnum should be set to 0.

If memory mapped access is being used, (mas_open was called with acc set to MAS_MMAP_ACCESS), the metric values are updated in real time at the address returned by mas_get_met. The metric values in the snapshot buffer address returned by mas_get_met_snap are updated only when mas_snap is called.

If read access is being used, (mas_open was called with acc set to MAS_READ_ACCESS), mas_get_met and mas_get_met_snap will return the same address within the snapshot buffer. The metric values in the snapshot buffer reflect their values as of the time of the last call to either mas_open or mas_snap.

Return values

On success, mas_get_met and mas_get_met_snap return an address at which the metric resides in the caller's address space.

On failure, mas_get_met and mas_get_met_snap return NULL and set mas_errno to identify the error.

Errors

MAS_NOMETRIC - id not in mas: The requested metric ID id is not registered in the metric registration file referred to by md.
MAS_INVALID_ARG - invalid metric descriptor: The metric descriptor, md does not correspond to a metric registration file previously opened by mas_open.
MAS_INVALID_ARG - bad unit number: A unit number, unitnum, falls outside of the range of valid values for the resource on which it is based. The unit number is either less than 0 or it is greater than or equal to the value of the resource.
MAS_SANITY - can't find metric for resource determination: A metric listed as a resource is not registered. The metric registration file is corrupted.
MAS_SANITY - metric for resource has more than one element: A metric listed as a resource has more than one element. The metric registration file is corrupted.
MAS_NOSUPPORT - unsupported resource object size: A metric listed as a resource has an object size that is not the same as an elementary type on the system, or is larger than uint32.

References

Intro(3mas)