NAME

       cmap_track_add - Set tracking function for values in CMAP

SYNOPSIS

       #include <corosync/cmap.h>

       cs_error_t cmap_track_add (cmap_handle_t handle, const char *key_name, int32_t track_type,
       cmap_notify_fn_t notify_fn, void *user_data, cmap_track_handle_t *cmap_track_handle);

DESCRIPTION

       The cmap_track_add function is used to set function which tracks changes in CMAP. One CMAP
       connection can track multiple keys and also it's possible to track one key multiple times.
       The handle argument is connection to CMAP database obtained by calling  cmap_initialize(3)
       function.   key_name  argument  is  ether  exact  key  name or prefix of key name to track
       changes on.  track_type is bitfield which may consist of following values:

       CMAP_TRACK_ADD - track addition of new key (or key added in callback)

       CMAP_TRACK_DELETE - track deletion of key (or key deleted in callback)

       CMAP_TRACK_MODIFY - track modification of key (or key modified in callback)

       CMAP_TRACK_PREFIX - whole prefix is tracked, instead of key  only,  so  "totem."  tracking
       means  that  "totem.nodeid", "totem.version", ... applies (this value is never returned in
       callback)

       notify_fn is pointer to function which is called when value is  changed.  It's  definition
       and  meaning  of  parameters is discussed below.  user_data argument is passed directly to
       notify_fn without any changes.  cmap_track_handle is used for removing of tracking when no
       longer needed by calling cmap_track_delete(3) function.

       Callback function is defined as:

              typedef void (*cmap_notify_fn_t) (
                  cmap_handle_t cmap_handle,
                  cmap_track_handle_t cmap_track_handle,
                  int32_t event,
                  const char *key_name,
                  struct cmap_notify_value new_value,
                  struct cmap_notify_value old_value,
                  void *user_data);

       where  cmap_handle is handle used in registration of track function.  cmap_track_handle is
       handle  returned  by  cmap_track_add  function.    event   is   one   of   CMAP_TRACK_ADD,
       CMAP_TRACK_DELETE  or  CMAP_TRACK_MODIFY.   key_name is name of changed key.  new_value is
       new value of key, or unset if event is CMAP_TRACK_DELETE.  old_value is previous value  of
       key  or unset if event is CMAP_TRACK_ADD or for some special keys set directly by Corosync
       due to speed optimizations.  Both new_value and old_value are structures defined as:

              struct cmap_notify_value {
                  cmap_value_types_t type;
                  size_t len;
                  const void *data;
              };

       If value is unset, all fields are set to 0. Otherwise  type  is  one  of  cmap  types  (as
       described  in cmap_get(3) function), len is length of value in cmap and data is pointer to
       value of item. Data storage is dynamically allocated by caller and  notify  function  must
       not try to free it.

RETURN VALUE

       This  call  returns  the  CS_OK value if successful. It can return CS_ERR_INVALID_PARAM if
       notify_fn is NULL or track_type is invalid value.

NOTES

       Modification tracking of individual keys is supported in the stats map, but not  prefixes.
       Add/Delete  operations  are  supported  on  prefixes  though  so you can track for new ipc
       connections or knet interfaces.  In the icmap map, prefix tracking is fully supported.

SEE ALSO

       cmap_track_delete(3), cmap_initialize(3), cmap_get(3), cmap_dispatch(3), cmap_overview(3)

       CS_ERR_TRY_AGAIN Resource temporarily unavailable

       CS_ERR_INVALID_PARAM Invalid argument

       CS_ERR_ACCESS Permission denied

       CS_ERR_LIBRARY The connection failed

       CS_ERR_INTERRUPT System call interrupted by a signal

       CS_ERR_NOT_SUPPORTED The requested protocol/functionality not supported

       CS_ERR_MESSAGE_ERROR Incorrect auth message received

       CS_ERR_NO_MEMORY Not enough memory to complete the requested task