EvmVarSet, EvmVarSetXxx, EvmVarSetStringI18N, EvmVarSetOpaque,
EvmVarGet, EvmVarGetType, EvmVarGetXxx, EvmVarGetString,
EvmVarGetOpaque, EvmVarRelease, EvmVarListGet,
EvmVarListFree - Manipulate event variables
EvmSize_t size ); EvmStatus_t EvmVarSetXxx(
const evm_type item_value ); EvmStatus_t EvmVarSetStringI18N(
const EvmString_t item_value,
EvmI18NMsgId_t msg_id ); EvmStatus_t EvmVarSetOpaque(
const EvmOpaque_t item_value,
EvmSize_t size ); EvmStatus_t EvmVarGet(
EvmVarStruct_t *var ); EvmStatus_t EvmVarGetType(
EvmVarType_t *type ); EvmStatus_t EvmVarGetXxx(
evm_type *item_value ); EvmStatus_t EvmVarGetString(
EvmI18NMsgId_t *msg_id ); EvmStatus_t EvmVarGetOpaque(
EvmSize_t *size ); EvmStatus_t EvmVarRelease(
EvmVarStruct_t *var ); EvmStatus_t EvmVarListGet(
EvmVarList_t *varList ); EvmStatus_t EvmVarListFree(
EvmVarList_t varlist );
The event to be processed. The name of a variable in the
event for which data is to be set or obtained.
For EvmVarSet(), if the named variable exists, the
associated data is modified. If the variable does
not exist, it is created and added to the event.
The value to be stored is passed in item_value.
The enumeration constant for the type of the
item_value to be stored in the variable indicated
by v_name. Possible values for this field are: EvmTYPE_BOOLEAN,
EvmTYPE_CHAR, EvmTYPE_INT16, EvmTYPE_INT32,
EvmTYPE_INT64, EvmTYPE_UINT8, EvmTYPE_UINT16,
EvmTYPE_UINT32, EvmTYPE_UINT64, EvmTYPE_FLOAT,
EvmTYPE_DOUBLE, EvmTYPE_STRING, EvmTYPE_OPAQUE
For EvmVarGetType(), this operand is a returned
value. The value to be stored in the variable
indicated by v_name. For a string variable being
set in an internationalized event, this argument
may contain an I18N message identifier corresponding
to the value of the variable. The identifier
must refer to a message in the catalog and message
set associated with the event (see the EvmItemSet(3) reference page). This operand is ignored for
variables whose type is not EvmTYPE_STRING. The
size of the associated item_value in bytes. The
caller must specify the correct size when setting a
variable of type EvmTYPE_OPAQUE. For all other
variable types, the size is ignored. For the EvmVarGet()
routine, this is a pointer to the location
where the output data is to be stored.
For the EvmVarRelease() routine, this is a pointer
to the storage space to be released. This is the
number of names in the var_list obtained by EvmVarListGet(),
not including the terminating NULL
pointer. On return from the EvmVarListGet() routine,
this is a list of pointers to the names of
the variables associated with the event. The last
item in the list is a NULL pointer.
For the EvmVarListFree() routine, this is a list of
names of variables for which memory should be
freed. The list must be terminated by a NULL
The EvmVarSet() routine sets the value of a variable data
item, indicated by v_name, in an event. This routine is
used both for adding a variable and for altering its
value. If the v_name variable is not already present in
the event, it is added.
The EvmVarSetXxx(), EvmVarSetStringI18N()(), and EvmVarSetOpaque()
routines offer a simpler means of setting a
variable than the generic EvmVarSet() routine. Using these
routines, you can set a variable of any type with a single
call. To use them, replace the Xxx() in the routine name
with the required type name, and supply a value of the
corresponding type as the item_value operand. The following
types are supported: Boolean, Char, Int16, Int32,
Int64, Uint8, Uint16, Uint32, Uint64, Float, Double,
Use EvmVarSetStringI18N()() to set a string variable with
a non-zero I18N message-ID, and EvmVarSetOpaque() to set
an opaque variable. Each of these routines requires one
more operand than the others in this group.
The EvmVarGet() routine returns the event variable indicated
by v_name in the var variable. The caller must free
any space used by the variable by calling EvmVarRelease().
The EvmVarGetType() routine returns the type of the named
The EvmVarGetXxx(), EvmVarGetString() and EvmVarGetOpaque()
routines offer a simpler means of retrieving a
variable value than the generic EvmVarGet() routine. Using
these routines, you can retrieve a variable of a specific
type with a single call. To use them, replace the Xxx() in
the routine name with the required type name, and supply a
pointer to a location of the corresponding type as the
item_value pointer. Refer to the description of EvmVarSetXxx()
above for details of the supported types.
Use EvmVarGetString() to retrieve a string variable, specifying
NULL for the msg_id operand if you do not want to
receive an I18N message-ID. Use EvmVarGetOpaque() to
retrieve an opaque variable. Each of these routines
requires one more operand than the others in this group.
Note that EvmVarGetString() and EvmVarGetOpaque() return
their variable values in heap memory. You must use free()
to free this space when you have finished with it.
The EvmVarRelease() routine releases any storage space
that was allocated when the specified var was retrieved
from an event using EvmVarGet(). It is important that this
routine is called when the variable is no longer needed,
to ensure that all memory associated with the variable is
released. You must not use this routine to release variables
retrieved with any of the EvmVarGetXxx() routines.
The EvmVarListGet() routine returns, in the varList reference
argument, a pointer to an array of pointers to names
of all the variables contained in the event. The last
entry in the array is a NULL pointer. The var_count argument
receives the number of names in the list, not counting
the terminating null value. The caller must free the
memory used by the list by calling EvmVarListFree().
The EvmVarListFree() routine frees the memory used by a
variable list (varList).
The caller must specify the size when adding an opaque
variable to an event.
To avoid memory leakage, memory that is supplied to the
caller from API routines must be freed with the appropriate
The operation was completed without error. One of the
arguments to the function was invalid. A value in a
structure member is invalid. An operation failed because
an attempt to acquire heap memory failed. A request specified
an item or variable name component in an itemList or
a varList that is not part of the event being processed.
EVM Support Library (libevm.so, libevm.a)
Event Management: EVM(5)
EVM Events: EvmEvent(5)
[ Back ]