# zx_counter_add

## Summary

Add a value to a counter.

## Declaration

    #include <zircon/syscalls.h>

    zx_status_t zx_counter_add(zx_handle_t handle, int64_t value);

## Description

`zx_counter_add()` adds *value* to the counter referenced by *handle*.

After the result of the addition, if the counter's value is:

- less than or equal to zero - `ZX_COUNTER_NON_POSITIVE` will be asserted and
  `ZX_COUNTER_POSITIVE` will be deasserted.

- greater than zero - `ZX_COUNTER_POSITIVE` will be asserted and
  `ZX_COUNTER_NON_POSITIVE` will be deasserted.

## Rights

*handle* must have both `ZX_RIGHT_READ` and `ZX_RIGHT_WRITE`. Because a
counter's value could be determined by checking for `ZX_ERR_OUT_OF_RANGE` on a
series of carefully crafted `zx_counter_add()` calls, there is no way to create
a counter that cannot be read, but which can be added.

## Return value

`zx_counter_add()` returns `ZX_OK` on success.

On failure, an error value is returned.

## Errors

`ZX_ERR_WRONG_TYPE` if *handle* is not a counter handle.

`ZX_ERR_ACCESS_DENIED` if *handle* does not have `ZX_RIGHT_WRITE`.

`ZX_ERR_OUT_OF_RANGE` if the result of the addition would overflow or underflow.

## See also

- [`zx_object_wait_async()`](https://fuchsia.dev/reference/syscalls/object_wait_async)
- [`zx_object_wait_many()`](https://fuchsia.dev/reference/syscalls/object_wait_many)
- [`zx_object_wait_one()`](https://fuchsia.dev/reference/syscalls/object_wait_one)
- [`zx_counter_create()`](https://fuchsia.dev/reference/syscalls/counter_create)
- [`zx_counter_read()`](https://fuchsia.dev/reference/syscalls/counter_read)
- [`zx_counter_write()`](https://fuchsia.dev/reference/syscalls/counter_write)