zx_counter_create

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.

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 event 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.