mas_open(3mas)

mas_open -- open a metric registration file for consumer use

Synopsis

   cc [options] file -lmas
   
   #include <mas.h>
   int mas_open(char *path, uint32 acc);

Description

The function mas_open opens path and initializes metric access support with an access method of acc. mas_open returns a descriptor associated with path that can be passed to other metric access support functions.

path must refer to a file that was previously created by a metric provider with the mas_init, mas_register_met, and mas_put calls.

acc can be either MAS_READ_ACCESS or MAS_MMAP_ACCESS. If acc is MAS_READ_ACCESS, metrics can be accessed from a snapshot buffer with the mas_snap call. If acc is MAS_MMAP_ACCESS, metrics are memory mapped into the caller's address space. Calling mas_snap when acc is set to MAS_MMAP_ACCESS copies the metrics from the mapped space into the snapshot buffer.

Return values

On success, mas_open returns a non-negative metric descriptor.

On failure, mas_open returns -1 and sets mas_errno to identify the error.

Errors

MAS_LIMIT - too many open metric tables: There are more than MAX_MET MAS files open. MAX_MET is currently set to 20.
MAS_ACCESS - unknown access method requested: An access method other than MAS_MMAP_ACCESS and MAS_READ_ACCESS was requested in acc, or MAS_MMAP_ACCESS was requested from a system that does not support memory mapping.
MAS_SANITY - mas header file corrupted, too small: A sanity check of the size of path against the size of the MAS header structure failed.
MAS_NOSUPPORT - mas provider doesn't support mmap: The system providing the metrics does not support memory mapping.
MAS_SANITY - mas header file corrupted - size mismatch: The size field within the MAS header in path does not match the size of path.
MAS_SANITY - corrupted metric registration file - table header size mismatch: The size field within the MAS header for the metric registration table header does not match the actual size of the metric registration table header.
MAS_SANITY - mas header file corrupted - no metric segments: path does not have any registered metrics.
MAS_SANITY - metric pointer out of bounds: A metric pointer was found to point outside of the address range of all of the metric segments.
MAS_SANITY - mrt has negative size: The size field in the metric registration table header for the number of entries in the metric registration table is negative.
MAS_SANITY - mrt extends beyond allocated space: The actual size of the metric registration table extends beyond the size indicated within the metric registration table header.
MAS_SANITY - id out of bounds: The address of an ID number is outside the bounds of the metadata table.
MAS_SANITY - units out of bounds: The address of an units number is outside the bounds of the metadata table.
MAS_SANITY - mas header file corrupted - string out of bounds: The address of a string is outside the bounds of the string table.
MAS_SANITY - metric name out of bounds: The address of a string is outside the bounds of the string table.
MAS_SANITY - metric units name out of bounds: The address of a string is outside the bounds of the string table.
MAS_SANITY - resource out of bounds: The address of a resource ID number is outside the bounds of the metadata table.
MAS_SANITY - nlocs corrupted: The number of total possible instances for a metric is corrupted, probably as a result of using a non-constant metric as a resource.
MAS_SANITY - resource list corrupted: A resource was registered that has more than one element.
MAS_SANITY - nlocs not initialized: The field for the total possible instances was not initialized.
MAS_SANITY - segment pointer not initialized: The field for the total possible instances was not initialized.
MAS_SANITY - segment pointer out of bounds: The offset of a metric segment was not initialized.
MAS_SANITY - metric pointer not initialized: The offset of a metric was not initialized.
MAS_SANITY - metric pointer out of bounds: The offset of a metric fell outside of the range of valid addresses of all the registered metrics segments.
MAS_SANITY - invalid segment number: A metric was registered with a segment number for which there is no corresponding segment.
MAS_SANITY - metric address out of bounds: The offset of a metric fell outside of the range of valid addresses of the metrics segments.
MAS_SANITY - mas header file corrupted - offset not on word boundary: An invalid offset to metadata was discovered.
MAS_SANITY - mas header file corrupted - table out of bounds: A static registration table address fell outside the size of path.
MAS_SANITY - mas header file corrupted - file name out of bounds: A metric segment or other registration table file name fell outside the size of path.
MAS_SANITY - table file corrupted, too small: A metric registration table file size did not match the size contained in the MAS header file.
MAS_SYSERR - can't open mas header file: The open system call failed to open path.
MAS_SYSERR - can't read mas header: The read system call failed while trying to read path.
MAS_SYSERR - can't map mas header file: The mmap system call failed while trying to map path.
MAS_SYSERR - can't open table file: The open system call failed to open an associated metric registration table file or a metric segment.
MAS_SYSERR - can't mmap table file: The mmap system call failed to map an associated metric registration table file or a metric segment.
MAS_SYSERR - can't lseek to table: The lseek system call failed to seek in an associated metric registration table file or a metric segment.
MAS_SYSERR - can't read table: The read system call failed to read an associated metric registration table file or a metric segment.
MAS_SYSERR - can't malloc space to keep filename: The malloc library call failed.
MAS_SYSERR - can't malloc space for mas header: The malloc library call failed.
MAS_SYSERR - cannot malloc space for metric segment pointers: The malloc library call failed.
MAS_SYSERR - cannot allocate space for snap buffer: The malloc library call failed.
MAS_SYSERR - can't malloc table: The malloc library call failed.

Usage

If memory mapped access is being used, care should be taken to not call mas_open more than once with the same path. Otherwise, the metric registration information and metric segments are mapped to the same addresses as in the first call, overlaying the previous mapping and destroying it. This is transparent to the caller until the mappings are subsequently destroyed by calling mas_close, at which time the unmapped address space is no longer present in the calling process. After that, any attempted access generates a segmentation violation.

References

mas_close(3mas), Intro(3mas), metreg(4)