mas_get_header(3mas)

mas_get_header -- get information about MAS configuration for consumer use

Synopsis

   cc [options] file -lmas
   
   #include <mas.h>
   uint32 *mas_get_mrt_sz(int md);
   uint32 *mas_get_mrt_hdr_sz(int md);
   uint32 *mas_get_nmrt(int md);
   uint32 *mas_get_id_sz(int md);
   uint32 *mas_get_units_sz(int md);
   uint32 *mas_get_resource_sz(int md);
   uint32 *mas_get_mas_magic(int md);
   uint32 *mas_get_mas_status(int md);
   uint32 *mas_get_bpw(int md);
   uint32 *mas_get_byte_order(int md);
   uint32 *mas_get_head_sz(int md);
   uint32 *mas_get_access_methods(int md);
   caddr_t mas_get_mas_start_addr(int md);
   caddr_t mas_get_mas_end_addr(int md);
   uint32 *mas_get_nseg(int md);
   caddr_t mas_get_metrics_start_addr(int md, int seg);
   caddr_t mas_get_metrics_end_addr(int md, int seg);
   char   *mas_get_metrics_filename(int md, int seg);
   caddr_t mas_get_strings_start_addr(int md);
   caddr_t mas_get_strings_end_addr(int md);
   char   *mas_get_strings_filename(int md);
   caddr_t mas_get_mrt_hdr_start_addr(int md);
   caddr_t mas_get_mrt_hdr_end_addr(int md);
   caddr_t mas_get_mr_tbl_start_addr(int md);
   caddr_t mas_get_mr_tbl_end_addr(int md);
   char   *mas_get_mr_tbl_filename(int md);
   caddr_t mas_get_metadata_start_addr(int md);
   caddr_t mas_get_metadata_end_addr(int md);
   char   *mas_get_metadata_filename(int md);
   char   *mas_get_mas_filename(int md);

Description

The mas_get_header functions return information about the configuration of MAS from the MAS header structure and the metric registration table header structure. There is one function call for each field in the header structures.

In the following functions, the md argument is a metric descriptor returned from mas_open.

In mas_get_metrics calls, the additional argument, seg, refers to the metric data segment number for the segment for which the information is being returned.

The function mas_get_mrt_sz returns the size of a single metric registration table structure entry, (sizeof(struct mrt)).

The function mas_get_mrt_hdr_sz returns the size of the metric registration table header structure, (sizeof(struct mrt_head)).

The function mas_get_nmrt returns the number of entries in the metric registration table. This is the number of metrics, (not instances), that have been registered.

The function mas_get_id_sz returns the size of a metric ID number, (sizeof(metid_t)).

The function mas_get_units_sz returns the size of a metric units field, (sizeof(units_t)).

The function mas_get_resource_sz returns the size of a metric resource id, (sizeof(resource_t)). Normally, this is identical to the size of a metric ID number.

The function mas_magic returns the magic number from the MAS header structure. The magic number can either be MAS_MAGIC_STAT (17), or MAS_MAGIC_DYN (23), for static and dynamic metric registration files, respectively.

The function mas_status returns the status word from the MAS header structure. The status word can be either MAS_AVAILABLE, indicating the metric registration file is fully available and in use, or MAS_UPDATE, indicating one or more metrics are in the process of being registered.

The function mas_get_bpw returns the number of bytes per word on the system on which the provider is executing.

The function mas_get_byte_order returns the byte ordering on the system on which the provider is executing. For 32 bit words, the byte ordering field is set to 0x01020304 by the provider.

The function mas_get_head_sz returns the size of the MAS header structure, (sizeof(struct mas_head)).

The function mas_get_access_methods returns the access methods that are supported by the provider. Currently this field can be either MAS_READ_ACCESS or (MAS_READ_ACCESS|MAS_MMAP_ACCESS).

The function mas_start_addr returns the address of the start of the MAS header structure in the calling process' address space.

The function mas_end_addr returns the address at the end of the MAS header structure in the calling process' address space + 1.

The function mas_get_nseg returns the number of metric data segments registered in this metric registration file. This corresponds to the nsegmnts argument passed to mas_init.

The function mas_get_metrics_start_addr returns the start address of a metric segment within the calling process' address space. The segment number argument, seg is a non-negative number less than nseg that refers to the segments in the order they were listed when mas_init was called.

The function mas_get_metrics_end_addr returns the end address of a metric segment within the calling process' address space + 1. The segment number argument, seg is a non-negative number less than nseg that refers to the segments in the order they were listed when mas_init was called.

The function mas_get_metrics_filename returns the filename of the metric segment identified by seg. The segment number argument, seg is a non-negative number less than nseg that refers to the segments in the order they were listed when mas_init was called. If the internal metric segment is contained within the MAS header file, mas_get_metrics_filename returns the name of the MAS header file.

The function mas_get_strings_start_addr returns the address of the start of the string table in the calling process's address space.

The function mas_get_strings_end_addr returns the address of the end of the string table in the calling process' address space + 1.

The function mas_get_strings_filename returns the name of the file in which the string table resides. If mas_init was called with str_fn set to NULL, mas_get_strings_filename returns the name of the MAS header file.

The function mas_get_mrt_hdr_start_addr returns the address of the start of the metric registration table header in the calling process' address space.

The function mas_get_mrt_hdr_end_addr returns the address of the end of the metric registration table header in the calling process' address space + 1.

The function mas_get_mr_tbl_start_addr returns the address of the start of the metric registration table in the calling process' address space.

The function mas_get_mr_tbl_end_addr returns the address of the end of the metric registration table in the calling process' address space + 1.

The function mas_get_mr_tbl_filename returns the name of the file in which the metric registration table resides. If mas_init was called with mrt_fn set to NULL, mas_get_mr_tbl_filename returns the name of the MAS header file.

The function mas_get_metadata_start_addr returns the address of the start of the metadata area in the calling process' address space.

The function mas_get_metadata_end_addr returns the address of the end of the metadata area in the calling process' address space + 1.

The function mas_get_metadata_tbl_filename returns the name of the file in which the metadata area resides. If mas_init was called with meta_fn set to NULL, mas_get_metadata_filename returns the name of the MAS header file.

The function mas_filename returns the name of the file that was opened by mas_open.

Return values

On success, these functions return a pointer to the data field in the caller's address space.

On failure, these functions return NULL and set mas_errno to identify the error.

Errors

MAS_INVALID_ARG - invalid metric descriptor: The metric descriptor, md does not correspond to a metric registration file previously opened with mas_open.
MAS_INVALID_ARG - invalid segment number: The segment descriptor, seg does not correspond to a valid metric data segment.

References

Intro(3mas)