1# Channel 2 3## NAME 4 5channel - Bidirectional interprocess communication 6 7## SYNOPSIS 8 9A channel is a bidirectional transport of messages consisting of some 10amount of byte data and some number of handles. 11 12## DESCRIPTION 13 14Channels maintain an ordered queue of messages to be delivered in either 15direction. A message consists of some amount of data and some number of handles. 16A call to *zx_channel_write()* enqueues one message, and a call to 17*zx_channel_read()* dequeues one message (if any are queued). A thread can block 18until messages are pending via *zx_object_wait_one()* or other waiting 19mechanisms. 20 21Alternatively, a call to *zx_channel_call()* enqueues a message in one 22direction of the channel, waits for a corresponding response, and 23dequeues the response message. In call mode, corresponding responses 24are identified via the first 4 bytes of the message, called the 25transaction ID. The kernel supplies distinct transaction IDs (always with the 26high bit set) for messages written with *zx_channel_call()*. 27 28The process of sending a message via a channel has two steps. The first is to 29atomically write the data into the channel and move ownership of all handles in 30the message into this channel. This operation always consumes the handles: at 31the end of the call, all handles either are all in the channel or are all 32discarded. The second operation is similar: after a channel read, all the 33handles in the next message to read are either atomically moved into the 34process's handle table, all remain in the channel, or are discarded (only when 35the **ZX_CHANNEL_READ_MAY_DISCARD** option is given). 36 37Unlike many other kernel object types, channels are not duplicatable. Thus there 38is only ever one handle associated to a handle endpoint and the process holding 39that handle is considered the owner. Only the owner can write messages or send 40the channel endpoint to another process. 41 42Furthermore, when ownership of a channel endpoint goes from one process to 43another, even if a write was in progress, the ordering of messages is guaranteed 44to be parsimonious; packets before the transfer event originate from the 45previous owner and packets after the transfer belong to the new owner. The same 46applies if a read was in progress when the endpoint was transferred. 47 48The above sequential guarantee is not provided for other kernel objects, even if 49the last remaining handle is stripped of the **ZX_RIGHT_DUPLICATE** right. 50 51## SYSCALLS 52 53+ [channel_call](../syscalls/channel_call.md) - synchronously send a message and receive a reply 54+ [channel_create](../syscalls/channel_create.md) - create a new channel 55+ [channel_read](../syscalls/channel_read.md) - receive a message from a channel 56+ [channel_write](../syscalls/channel_write.md) - write a message to a channel 57 58<br> 59 60+ [object_wait_one](../syscalls/object_wait_one.md) - wait for signals on one object 61 62## SEE ALSO 63 64+ [Zircon concepts](../concepts.md) 65+ [Handles](../handles.md) 66