Summary
Create a counter.
Declaration
#include <zircon/syscalls.h>
zx_status_t zx_counter_create(uint32_t options, zx_handle_t* out);
Description
zx_counter_create() creates a counter, which is an object that encapsulates
a signed 64-bit integer value that can be incremented, decremented, read, or
written.
When the value is greater than zero, the signal ZX_COUNTER_POSITIVE is
asserted. Otherwise ZX_COUNTER_NON_POSITIVE is asserted. Exactly one of
these two signals is always asserted, and never both at once.
Additionally, the signal ZX_COUNTER_SIGNALED may be set or cleared on the
counter using zx_object_signal(). This is independent of the value of the
counter or the state of the other signals.
The newly-created handle will have rights ZX_RIGHTS_BASIC, ZX_RIGHTS_IO, and
ZX_RIGHT_SIGNAL. The value will be zero and the signal
ZX_COUNTER_NON_POSITIVE will be asserted on the newly-created object.
Rights
TODO(https://fxbug.dev/387324141): Add/enforce ZX_POL_NEW_COUNTER policy.
Caller job policy must allow ZX_POL_NEW_COUNTER.
Return value
zx_counter_create() returns ZX_OK and a valid counter handle (via out) on
success.
On failure, an error value is returned.
Errors
ZX_ERR_INVALID_ARGS out is an invalid pointer, or options is non-zero.
ZX_ERR_NO_MEMORY Failure due to lack of memory. There is no good way for
userspace to handle this (unlikely) error. In a future build this error will no
longer occur.