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)
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004