mas_type(3mas)


mas_type -- MAS type-specific functions for manipulating metadata

Synopsis

   cc [options] file -lmas
   

#include <mas.h> int mas_id_cmp(metid_t *idp, metid_t id); int mas_id_cp(metid_t *idp, metid_t id); int mas_resource_cmp(resource_t *resourcep, resource_t resource); int mas_resource_cp(resource_t *resourcep, resource_t resource); int mas_units_cmp(units_t *unitsp, units_t units); int mas_units_cp(units_t *unitsp, units_t units); int mas_name_cmp(name_t namep1, name_t namep2); int mas_name_size(name_t namep); int mas_name_cp(name_t namep1, name_t namep2); int mas_name_len(name_t namep); int mas_magic_sanity(uint32 magic); int mas_mrt_head_sanity(struct mrt_head *mrt_head); int mas_resource_sanity(int md, resource_t resource); int mas_bpw_sanity(uint32 bpw); int mas_byteorder_sanity(uint32 byte_order); int mas_mas_head_sz_sanity(uint32 mas_head_sz); int mas_id_sanity(metid_t id); int mas_units_sanity(units_t units); int mas_access_sanity(uint32 access_methods); int mas_status_sanity(uint32 status); int mas_set_status(uint32 *status, uint32 flags); int mas_clr_status(uint32 *status, uint32 flags);

Description

The mas_type functions allow the manipulation of metadata objects. Since the format of metadata is system dependent, these functions are kept separately in MAS to allow easy porting and upgrade. For portability, applications that need to process metadata directly should use these functions.

The mas_type functions fall into several classes:


comparative functions:
mas_id_cmp, mas_resource_cmp, mas_units_cmp, mas_name_cmp

copy functions:
mas_id_cp, mas_resource_cp, mas_units_cp, mas_name_cp

size functions:
mas_name_size, mas_name_len

sanity tests:
mas_magic_sanity, mas_mrt_head_sanity, mas_access_sanity, mas_resource_sanity, mas_byteorder_sanity, mas_id_sanity, mas_mas_head_sz_sanity, mas_units_sanity, mas_bpw_sanity, mas_status_sanity

status functions:
mas_set_status, mas_clr_status

The comparative functions compare the value of the second argument to the contents of the location pointed to by the first argument. The comparative functions return if the values are the same and 1 if they differ.

The copy functions copy the value of the second argument to the location pointed to by the first argument.

The size functions return the amount of storage, in bytes, needed to save a string, and the length of the string in characters.

The sanity tests return 0 if the argument passes the sanity check, and -1 on failure, with mas_errno set to identify the error.

The status functions set and clear bits from the MAS header status word and the status words in the metric registration table.

Return values

On success, the mas_type functions return a non-negative value. On failure, the mas_type functions return -1 and set mas_errno to identify the error. The meaning of the return value depends on the function invoked:

Functions Return Values
comparative functions 0 if the objects match
  1 if the objects differ
  -1 on NULL pointer failure
copy functions 0 on successful copy
  -1 on NULL pointer failure
mas_name_size number of bytes needed to store the name
  -1 on NULL pointer failure
mas_name_len length of the name (in bytes)
  -1 on NULL pointer failure
sanity checks 0 if the object is sane
  -1 if the object is invalid
mas_set_status 0 on successful setting of status
  -1 on NULL pointer failure
mas_clr_status 0 on successful clearing of status
  -1 on NULL pointer failure

 Functions               Return Values
 comparative functions   0 if the objects match
                         1 if the objects differ
                         -1 on NULL pointer failure
 copy functions          0 on successful copy
                         -1 on NULL pointer failure
 mas_name_size           number of bytes needed to store the name
                         -1 on NULL pointer failure
 mas_name_len            length of the name (in bytes)
                         -1 on NULL pointer failure
 sanity checks           0 if the object is sane
                         -1 if the object is invalid
 mas_set_status          0 on successful setting of status
                         -1 on NULL pointer failure
 mas_clr_status          0 on successful clearing of status
                         -1 on NULL pointer failure

Errors


MAS_INVALIDARG - NULL pointer passed
A null pointer was passed to a mas_type function.

MAS_SANITY - bad magic
mas_magic_sanity detected an invalid magic number in the metric registration file.

MAS_SANITY - invalid mrt size
mas_mrt_head_sanity detected the size field in the MAS header for the metric registration header does not match the size of the metric registration table header structure.

MAS_SANITY - invalid id size
mas_mrt_head_sanity detected the size field for the size of a metric ID does not match the size of a metric id.

MAS_SANITY - invalid units size
mas_mrt_head_sanity detected the size field for the size of a metric units does not match the size of a units field.

MAS_SANITY - invalid resource size
mas_mrt_head_sanity detected the size field for the size of a resource does not match the size of a resource field.

MAS_SANITY - too many metrics
mas_mrt_head_sanity detected the number of metrics is greater than MAS_MAX_METS. MAS_MAX_METS is currently set to 2048.

MAS_SANITY - bad wordsize
Either mas_mrt_bpw_sanity or mas_mrt_byteorder_sanity detected an unsupported word size.

MAS_SANITY - access methods mismatch
mas_access_sanity detected unsupported access methods.

MAS_SANITY - bad status word
mas_status_sanity detected an invalid status word in either the MAS header or a metric registration table entry.

MAS_SANITY - invalid size word
mas_mas_head_sz_sanity detected the size field for the size of the MAS header does not match the size of the MAS header struct.

MAS_SANITY - id number fails sanity check
mas_id_sanity detected an invalid ID number.

MAS_SANITY - units field fails sanity check
mas_units_sanity detected an invalid units field.

MAS_SANITY - empty metric registration table
mas_resource_sanity detected the metric registration table contains no registered metrics.

MAS_SANITY - resource fails sanity check
mas_resource_sanity detected an invalid resource.

References

Intro(3mas)
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004