mas_init(3mas) mas_init(3mas)
NAME
mas_init - initialize metric access support for provider use
SYNOPSIS
cc [options] file -lmas
#include <fcntl.h>
#include <mas.h>
int mas_init(uint32 mode, char *mas_fn, uint32 nsegmnts,
char **met_fn, caddr_t *metaddr, uint32 *metsz,
uint32 *metoff, char *mrt_fn, char *meta_fn,
char *str_fn);
DESCRIPTION
The function mas_init initializes metric access support (MAS)
for use by a provider so that metrics may be registered.
The first two arguments are the name and permissions of the
registration file, mas_fn and mode. In the future, mas_init
may be expanded to include the ability to re-open an existing
metric registration file and register additional metrics, but
for now, the metric registration file, mas_fn, must not exist
prior to calling mas_init. The file mas_fn is not created
until mas_put is called.
The next five arguments specify metric segment information. A
metric segment is a set of contiguous pages in memory that
contain metrics. Most provider applications will want to
control the addresses of their metrics, and hence will pre-
allocate their own metric segments. If a metric segment is
set correspond to a memory mapped file, then the metrics can
be updated (and accessed by consumer applications) in real
time. The following arguments allow providers to identify
their metric segments. nsegmnts specifies the number of
metric segments to be registered. met_fn points to a list of
metric segment file names. metaddr points to a list of
addresses where the metric segments reside in the caller.
metsz points to a list of sizes of the metric segments.
metoff points to a list of offsets of the metric segments
within their respective files.
The last three arguments to mas_init are optional file names
for dynamic metric registration, the ability to add metrics to
a registration file that is already in use. Provider
applications that do not need dynamic metric registration
should request static metric registration by setting these
arguments to NULL, which places the data areas associated with
Copyright 1994 Novell, Inc. Page 1
mas_init(3mas) mas_init(3mas)
these arguments within the metric registration header file,
mas_fn. Provider applications using static metric
registration should not register any additional metrics after
calling mas_put.
Dynamic registration is supported from the time the metric
registration files are created until the time the caller
exits. Currently, only the addition of new metrics is
supported, there is no provision for unregistering metrics,
and there is no facility for notification of active consumer
applications that the registration information has been
updated.
Because consumer applications will either read or privately
memory map the registration data, they will see a static view
of the registration file as of the time it was opened with
mas_open, and they will not be able to determine the
registration information has changed. However, in the future,
dynamic metric registration may be expanded to notify consumer
applications of updates to the metric registration
information, and to offer support of shared memory mapping of
the registration data between provider and consumer
applications.
To allow for this expansion, dynamic metric registration
requires separate file names for the metric registration
table, metadata, and strings table, since these data areas
increase in size as new metrics are registered. These file
names are specified in mrt_fn, meta_fn, and str_fn,
respectively.
For the present, dynamic registration will work with these
arguments set to NULL, and their associated data areas
residing in the MAS header file, but to guarantee applications
will work with future releases of MAS, providers must specify
separate file name for these arguments.
Until a notification facility is supported, consumer
applications interested in gathering new metrics as they
become available must check to see if the registration file
has changed since they last opened it with mas_open. To
obtain the updated registration information, consumer
applications should reopen the registration files with
mas_open. Metric providers can assist consumers in
determining a change has occurred in the registration
information by registering and maintaining a metric that is
Copyright 1994 Novell, Inc. Page 2
mas_init(3mas) mas_init(3mas)
set to the time of the last call to mas_put.
For simple user level provider applications that do not need
memory mapped access to update metrics, do not care to pre-
allocate a metric segment, and do not need dynamic metric
registration, mas_init internally allocates a static metric
segment. The internal segment is specified by setting the
metric segment address, size and offset (metaddr, metsz and
metoff) all to 0. Only one internal segment is allowed. The
location of metrics within the internal segment are assigned
during registration and are returned by mas_register_met.
mas_init allocates MAS_MAX_METRICS bytes of space for the
internal metric segment, however only the portion of the
metric segment that is actually in use is written to the MAS
header file. MAS_MAX_METRICS is currently set to 128K. If a
NULL file name is specified for the internally allocated
segment in the met_fn list, the segment is placed within the
MAS header file. Otherwise it is written to the file named in
the met_fn list. When using the internal metric segment,
metrics must be updated with the mas_write_mets call. If the
internal segment is set to reside in the MAS header file,
mas_fn, dynamic metric registration should not be used, and
mas_put should not be called more than once.
Return Values
On success, mas_init returns 0.
On failure mas_init returns -1 and sets mas_errno to identify
the error.
Errors
MAS_USAGE - mas already initialized
mas_init was called more than once.
MAS_INVALIDARG - NULL mas file name
mas_init was called with a NULL mas_fn.
MAS_INVALIDARG - need at least one metric segment
mas_init was called with nsegmnts set to 0.
MAS_INVALIDARG - metric address given with no file name
mas_init was called with a non-zero address in metaddr
and a corresponding NULL metric segment filename in
met_fn.
Copyright 1994 Novell, Inc. Page 3
mas_init(3mas) mas_init(3mas)
MAS_INVALIDARG - metric address given with no size
mas_init was called with a non-zero address in metaddr
and a corresponding metric segment size of 0 in metsz.
MAS_INVALIDARG - multiple non-preallocated segments found
mas_init was called requesting more than one internally
allocated segment. (More than one NULL address was
found in the metaddr list.)
MAS_NOFILEACCESS - mas file already exists
The MAS file, mas_fn, already exists.
MAS_SYSERR - cannot malloc space for strings
The malloc library call failed.
MAS_SYSERR - cannot malloc space for metadata
The malloc library call failed.
MAS_SYSERR - cannot malloc space for metric segment pointers
The malloc library call failed.
MAS_SYSERR - cannot malloc space for segment structs
The malloc library call failed.
MAS_SYSERR - can't allocate metric space
The malloc library call failed.
MAS_SYSERR - cannot malloc space for file name
The malloc library call failed.
MAS_SYSERR - can't malloc table
The malloc library call failed.
REFERENCES
mas(3mas)
Copyright 1994 Novell, Inc. Page 4