mas_open(3mas) mas_open(3mas)
NAME
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.
Copyright 1994 Novell, Inc. Page 1
mas_open(3mas) mas_open(3mas)
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.
mismatch
MAS_SANITY - corrupted metric registration file -
table header size
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.
Copyright 1994 Novell, Inc. Page 2
mas_open(3mas) mas_open(3mas)
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.
Copyright 1994 Novell, Inc. Page 3
mas_open(3mas) mas_open(3mas)
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.
Copyright 1994 Novell, Inc. Page 4
mas_open(3mas) mas_open(3mas)
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), mas(3mas)
Copyright 1994 Novell, Inc. Page 5