**libgnunetstatistics** is the library containing the API for the STATISTICS subsystem. Any process requiring to use STATISTICS should use this API by to open a connection to the STATISTICS service. This is done by calling the function `GNUNET_STATISTICS_create()`

. This function takes the subsystem's name which is trying to use STATISTICS and a configuration. All values written to STATISTICS with this connection will be placed in the section corresponding to the given subsystem's name. The connection to STATISTICS can be destroyed with the function GNUNET_STATISTICS_destroy(). This function allows for the connection to be destroyed immediately or upon transferring all pending write requests to the service.

*Note:* STATISTICS subsystem can be disabled by setting `DISABLE = YES`

under the `[STATISTICS]`

section in the configuration. With such a configuration all calls to `GNUNET_STATISTICS_create()`

return `NULL`

as the STATISTICS subsystem is unavailable and no other functions from the API can be used.

Once a connection to the statistics service is obtained, information about any other system which uses statistics can be retrieved with the function GNUNET_STATISTICS_get(). This function takes the connection handle, the name of the subsystem whose information we are interested in (a `NULL`

value will retrieve information of all available subsystems using STATISTICS), the name of the statistic we are interested in (a `NULL`

value will retrieve all available statistics), a continuation callback which is called when all of requested information is retrieved, an iterator callback which is called for each parameter in the retrieved information and a closure for the aforementioned callbacks. The library then invokes the iterator callback for each value matching the request.

Call to `GNUNET_STATISTICS_get()`

is asynchronous and can be canceled with the function `GNUNET_STATISTICS_get_cancel()`

. This is helpful when retrieving statistics takes too long and especially when we want to shutdown and cleanup everything.

So far we have seen how to retrieve statistics, here we will learn how we can set statistics and update them so that other subsystems can retrieve them.

A new statistic can be set using the function `GNUNET_STATISTICS_set()`

. This function takes the name of the statistic and its value and a flag to make the statistic persistent. The value of the statistic should be of the type `uint64_t`

. The function does not take the name of the subsystem; it is determined from the previous `GNUNET_STATISTICS_create()`

invocation. If the given statistic is already present, its value is overwritten.

An existing statistics can be updated, i.e its value can be increased or decreased by an amount with the function `GNUNET_STATISTICS_update()`

. The parameters to this function are similar to `GNUNET_STATISTICS_set()`

, except that it takes the amount to be changed as a type `int64_t`

instead of the value.

The library will combine multiple set or update operations into one message if the client performs requests at a rate that is faster than the available IPC with the STATISTICS service. Thus, the client does not have to worry about sending requests too quickly.

As interesting feature of STATISTICS lies in serving notifications whenever a statistic of our interest is modified. This is achieved by registering a watch through the function `GNUNET_STATISTICS_watch()`

. The parameters of this function are similar to those of `GNUNET_STATISTICS_get()`

. Changes to the respective statistic's value will then cause the given iterator callback to be called. *Note:* A watch can only be registered for a specific statistic. Hence the subsystem name and the parameter name cannot be `NULL`

in a call to `GNUNET_STATISTICS_watch()`

.

A registered watch will keep notifying any value changes until `GNUNET_STATISTICS_watch_cancel()`

is called with the same parameters that are used for registering the watch.