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.