---
name: "cmap_track_add"
section: "3"
platform: "linux"
package: "libcmap-dev"
version: "3.1.9-2+deb13u1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/cmap_track_add"
---

# cmap\_track\_add(3)

Set tracking function for values in CMAP

## 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)](/cmap_initialize/3.md)** 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)](/cmap_track_delete/3.md)** 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)](/cmap_get/3.md)** 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_track_delete/3.md), [**cmap\_initialize**(3)](/cmap_initialize/3.md), [**cmap\_get**(3)](/cmap_get/3.md), [**cmap\_dispatch**(3)](/cmap_dispatch/3.md), [**cmap\_overview**(3)](/cmap_overview/3.md)

**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