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