docs/syscalls/object_signal.md

# zx_object_signal, zx_object_signal_peer

## NAME

object_signal - signal an object

object_signal_peer - signal an object's peer


## SYNOPSIS

```
#include <zircon/syscalls.h>

zx_status_t zx_object_signal(zx_handle_t handle, uint32_t clear_mask, uint32_t set_mask);
zx_status_t zx_object_signal_peer(zx_handle_t handle, uint32_t clear_mask, uint32_t set_mask);

```

## DESCRIPTION

**zx_object_signal**() and **zx_object_signal_peer**() set and clear the userspace-accessible
signal bits on an object or on the object's peer, respectively.  A object peer is the opposite
endpoint of a *channel*, *socket*, *fifo*, or *eventpair*.

Most of the 32 signals are reserved for system use and are assigned to per-object functions, like
*ZX_CHANNEL_READABLE* or *ZX_TASK_TERMINATED*.  8 signals are available for userspace processes
to use as they see fit: *ZX_USER_SIGNAL_0* through *ZX_USER_SIGNAL_7*.

*Event* objects also allow control over the *ZX_EVENT_SIGNALED* bit.

*Eventpair* objects also allow control over the *ZX_EPAIR_SIGNALED* bit.

The *clear_mask* is first used to clear any bits indicated, and then the *set_mask*
is used to set any bits indicated.


## RETURN VALUE

**zx_object_signal**() and **zx_object_signal_peer**() return **ZX_OK** on success.
In the event of failure, a negative error value is returned.


## ERRORS

**ZX_ERR_BAD_HANDLE**  *handle* is not a valid handle.

**ZX_ERR_ACCESS_DENIED**  *handle* lacks the right **ZX_RIGHT_SIGNAL** (for **zx_object_signal**()) or
**ZX_RIGHT_SIGNAL_PEER** (for **zx_object_signal_peer**()).

**ZX_ERR_INVALID_ARGS**  *clear_mask* or *set_mask* contain bits that are not allowed.

**ZX_ERR_NOT_SUPPORTED**  **zx_object_signal_peer**() used on an object lacking a peer.

**ZX_ERR_PEER_CLOSED**  **zx_object_signal_peer**() called on an object with a closed peer.

## NOTE

*ZX_RIGHT_WRITE* is used to gate access to signal bits.  This will likely change.


## SEE ALSO

[event_create](event_create.md),
[eventpair_create](eventpair_create.md).