Metric and Control Arguments

Metric and Control Arguments — Functions for managing argument lists used by metrics and controls

Synopsis


#include <monitor/monitor.h>


            mon_arg;
            mon_arg_list;
int         mon_arg_cmp                     (const mon_arg *arg1,
                                             const mon_arg *arg2);
void        mon_arg_free                    (mon_arg *arg);
mon_arg_list* mon_arg_list_new              (void);
void        mon_arg_list_free               (mon_arg_list *arglist);
int         mon_arg_list_add                (mon_arg_list *arglist,
                                             mon_type *type,
                                             const mon_simple_val *val);
void        mon_arg_list_del                (mon_arg_list *arglist,
                                             const char *name);
int         mon_arg_list_add_simple         (mon_arg_list *arglist,
                                             const char *name,
                                             mon_basic_type type,
                                             const mon_simple_val *val);
int         mon_arg_list_add_string         (mon_arg_list *arglist,
                                             const char *name,
                                             const char *value);
int         mon_arg_list_add_int32          (mon_arg_list *arglist,
                                             const char *name,
                                             int32_t value);
int         mon_arg_list_add_uint32         (mon_arg_list *arglist,
                                             const char *name,
                                             uint32_t value);
int         mon_arg_list_add_int64          (mon_arg_list *arglist,
                                             const char *name,
                                             int64_t value);
int         mon_arg_list_add_uint64         (mon_arg_list *arglist,
                                             const char *name,
                                             uint64_t value);
int         mon_arg_list_add_double         (mon_arg_list *arglist,
                                             const char *name,
                                             double value);
int         mon_arg_list_add_parsed         (mon_arg_list *arglist,
                                             const char *name,
                                             mon_basic_type type,
                                             const char *value);
mon_arg_list* mon_arg_list_copy             (const mon_arg_list *src);
mon_arg*    mon_arg_list_find               (const mon_arg_list *arglist,
                                             const char *name);
mon_simple_val* mon_arg_list_val            (const mon_arg_list *arglist,
                                             const char *name);
int         mon_arg_list_print              (const mon_arg_list *arglist,
                                             char **dst);
int         mon_arg_list_cmp                (const mon_arg_list *args1,
                                             const mon_arg_list *args2);
int         mon_arg_list_encode             (mon_buffer *buf,
                                             const mon_arg_list *arglist);
int         mon_arg_list_decode             (mon_buffer *buf,
                                             mon_arg_list **arglist);

Description

Details

mon_arg

typedef struct {
	/* Argument name and data type. Only simple types are allowed */
	mon_type		*type;
	/* Argument value */
	mon_simple_val		value;
} mon_arg;

The mon_arg structure contains the actual value of a metric parameter.

mon_type *type;a mon_type node containing the name and the data type of the argument.
mon_simple_val value;the value of the argument.

mon_arg_list

typedef struct {
	unsigned int		cnt;
	GList			*list;
} mon_arg_list;

The mon_arg_list structure contains a list of metric arguments.

unsigned int cnt;number of elements in list.
GList *list;list of mon_arg elements.

mon_arg_cmp ()

int         mon_arg_cmp                     (const mon_arg *arg1,
                                             const mon_arg *arg2);

Compares two arguments and decides their lexicographical order by first comparing their names, then their types and finally their values.

arg1 :a mon_arg.
arg2 :a mon_arg.
Returns :less than zero, zero or greater than zero if arg1 is less than, equal to or greater than arg2, respectively.

mon_arg_free ()

void        mon_arg_free                    (mon_arg *arg);

Frees the memory allocated to a mon_arg.

arg :a mon_arg.

mon_arg_list_new ()

mon_arg_list* mon_arg_list_new              (void);

Allocates a new mon_arg_list.

Returns :the allocated mon_arg_list.

mon_arg_list_free ()

void        mon_arg_list_free               (mon_arg_list *arglist);

Frees every element of a mon_arg_list and frees the memory allocated to the list itself.

arglist :a mon_arg_list.

mon_arg_list_add ()

int         mon_arg_list_add                (mon_arg_list *arglist,
                                             mon_type *type,
                                             const mon_simple_val *val);

Add a new argument to a mon_arg_list.

arglist :a mon_arg_list.
type :a mon_type describing the name and data type of the argument.
val :the value of the argument.
Returns :0 if successful, MON_ERR_ARGLIST_TOOLONG if the argument list is too long or ENOMEM when out of memory.

mon_arg_list_del ()

void        mon_arg_list_del                (mon_arg_list *arglist,
                                             const char *name);

Removes a named argument from an argument list. In case of multi-valued arguments, all values are removed.

arglist :a mon_arg_list.
name :the argument name to remove.

mon_arg_list_add_simple ()

int         mon_arg_list_add_simple         (mon_arg_list *arglist,
                                             const char *name,
                                             mon_basic_type type,
                                             const mon_simple_val *val);

Add an argument of a simple type to a mon_arg_list.

arglist :a mon_arg_list.
name :the name of the argument to add.
type :the type of the argument.
val :the value of the argument.
Returns :0 if successful, MON_ERR_ARGLIST_TOOLONG if the argument list is too long, EINVAL if type contains an illegal value or ENOMEM when out of memory.

mon_arg_list_add_string ()

int         mon_arg_list_add_string         (mon_arg_list *arglist,
                                             const char *name,
                                             const char *value);

Add a string argument to a mon_arg_list.

arglist :a mon_arg_list;
name :the name of the argument.
value :the argument's value.
Returns :0 if successful, MON_ERR_ARGLIST_TOOLONG if the argument list is too long or ENOMEM when out of memory.

mon_arg_list_add_int32 ()

int         mon_arg_list_add_int32          (mon_arg_list *arglist,
                                             const char *name,
                                             int32_t value);

Add a 32-bit signed integer to a mon_arg_list.

arglist :a mon_arg_list;
name :the name of the argument.
value :the argument's value.
Returns :0 if successful, MON_ERR_ARGLIST_TOOLONG if the argument list is too long or ENOMEM when out of memory.

mon_arg_list_add_uint32 ()

int         mon_arg_list_add_uint32         (mon_arg_list *arglist,
                                             const char *name,
                                             uint32_t value);

Add a 32-bit unsigned integer to a mon_arg_list.

arglist :a mon_arg_list;
name :the name of the argument.
value :the argument's value.
Returns :0 if successful, MON_ERR_ARGLIST_TOOLONG if the argument list is too long or ENOMEM when out of memory.

mon_arg_list_add_int64 ()

int         mon_arg_list_add_int64          (mon_arg_list *arglist,
                                             const char *name,
                                             int64_t value);

Add a 64-bit signed integer to a mon_arg_list.

arglist :a mon_arg_list;
name :the name of the argument.
value :the argument's value.
Returns :0 if successful, MON_ERR_ARGLIST_TOOLONG if the argument list is too long or ENOMEM when out of memory.

mon_arg_list_add_uint64 ()

int         mon_arg_list_add_uint64         (mon_arg_list *arglist,
                                             const char *name,
                                             uint64_t value);

Add a 64-bit unsigned integer to a mon_arg_list.

arglist :a mon_arg_list.
name :the name of the argument.
value :the argument's value.
Returns :0 if successful, MON_ERR_ARGLIST_TOOLONG if the argument list is too long or ENOMEM when out of memory.

mon_arg_list_add_double ()

int         mon_arg_list_add_double         (mon_arg_list *arglist,
                                             const char *name,
                                             double value);

Add a 64-bit double precision floating point number to a mon_arg_list.

arglist :a mon_arg_list.
name :the name of the argument.
value :the argument's value.
Returns :0 if successful, MON_ERR_ARGLIST_TOOLONG if the argument list is too long or ENOMEM when out of memory.

mon_arg_list_add_parsed ()

int         mon_arg_list_add_parsed         (mon_arg_list *arglist,
                                             const char *name,
                                             mon_basic_type type,
                                             const char *value);

Parse an argument given as a string and append it to arglist.

This function is useful when the user specifies an argument in a textual format (e.g. command line).

arglist :a mon_arg_list.
name :the name of the argument.
type :the type of the argument.
value :the argument's value.
Returns :0 if successful, ENOMEM when out of memory, EINVAL if the supplied value could not be parsed.

mon_arg_list_copy ()

mon_arg_list* mon_arg_list_copy             (const mon_arg_list *src);

Makes a deep copy of a mon_arg_list.

src :a mon_arg_list.
Returns :a deep copy of src or NULL if there were not enough memory.

mon_arg_list_find ()

mon_arg*    mon_arg_list_find               (const mon_arg_list *arglist,
                                             const char *name);

Find a named argument in a mon_arg_list.

arglist :a mon_arg_list.
name :the name of the argument.
Returns :the first mon_arg with the given name or NULL if the list contains no arguments with this name.

mon_arg_list_val ()

mon_simple_val* mon_arg_list_val            (const mon_arg_list *arglist,
                                             const char *name);

Like mon_arg_list_find(), but returns the argument's value instead of the mon_arg structure.

arglist :a mon_arg list.
name :the name of the argument.
Returns :pointer to the argument's value or NULL if it could not be found.

mon_arg_list_print ()

int         mon_arg_list_print              (const mon_arg_list *arglist,
                                             char **dst);

Convert an argument list to a string (mainly for debugging).

arglist :a mon_arg_list.
dst :address where to store the strigified argument list when successful. It must be freed by the caller using g_free().
Returns :0 if successful or an error code.

mon_arg_list_cmp ()

int         mon_arg_list_cmp                (const mon_arg_list *args1,
                                             const mon_arg_list *args2);

Compares two argument lists according to a lexicographical ordering.

args1 :a mon_arg_list.
args2 :a mon_arg_list.
Returns :less than zero, zero or greater than zero if args1 is less than, equal to or greater than args2, respectively.

mon_arg_list_encode ()

int         mon_arg_list_encode             (mon_buffer *buf,
                                             const mon_arg_list *arglist);

Encodes a mon_arg_list according to the monp:// protocol binding.

buf :a buffer to hold the encoded list.
arglist :a mon_arg_list.
Returns :0 if successful or an error code.

mon_arg_list_decode ()

int         mon_arg_list_decode             (mon_buffer *buf,
                                             mon_arg_list **arglist);

Decodes a mon_arg_list encoded by mon_arg_list_encode().

buf :a buffer holding an encoded mon_arg_list.
arglist :where to store the pointer for the decoded mon_arg_list.
Returns :0 if successful or an error code.