1# zx_socket_share
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7socket_share - send another socket object via a socket
8
9## SYNOPSIS
10
11<!-- Updated by update-docs-from-abigen, do not edit. -->
12
13```
14#include <zircon/syscalls.h>
15
16zx_status_t zx_socket_share(zx_handle_t handle, zx_handle_t socket_to_share);
17```
18
19## DESCRIPTION
20
21`zx_socket_share()` attempts to send a new socket via an existing socket
22connection.  The signal **ZX_SOCKET_SHARE** is asserted when it is possible
23to send a socket.
24
25On success, the *socket_to_share* is placed into the *handle*'s share
26queue, and is no longer accessible to the caller's process. On any
27failure, *socket_to_share* is discarded rather than transferred.
28
29## RIGHTS
30
31<!-- Updated by update-docs-from-abigen, do not edit. -->
32
33*handle* must be of type **ZX_OBJ_TYPE_SOCKET** and have **ZX_RIGHT_WRITE**.
34
35*socket_to_share* must be of type **ZX_OBJ_TYPE_SOCKET** and have **ZX_RIGHT_TRANSFER**.
36
37## RETURN VALUE
38
39`zx_socket_share()` returns **ZX_OK** on success.  In the event of failure,
40one of the following values is returned.
41
42## ERRORS
43
44**ZX_ERR_BAD_HANDLE**  The handle *handle* or *socket_to_share* is invalid.
45
46**ZX_ERR_WRONG_TYPE**  The handle *handle* or *socket_to_share* is not a socket handle.
47
48**ZX_ERR_ACCESS_DENIED**  The handle *handle* lacks **ZX_RIGHT_WRITE** or
49the handle *socket_to_share* lacks **ZX_RIGHT_TRANSFER**.
50
51**ZX_ERR_BAD_STATE**  The *socket_to_share* was a handle to the same socket
52as *handle* or to the other endpoint of *handle* or the *socket_to_share* itself
53is capable of sharing.
54
55**ZX_ERR_SHOULD_WAIT**  There is already a socket in the share queue.
56
57**ZX_ERR_NOT_SUPPORTED**  This socket does not support the transfer of sockets.
58It was not created with the **ZX_SOCKET_HAS_ACCEPT** option.
59
60**ZX_ERR_PEER_CLOSED** The socket endpoint's peer is closed.
61
62## LIMITATIONS
63
64The socket share queue is only one element deep.
65
66## SEE ALSO
67
68 - [`zx_socket_accept()`]
69 - [`zx_socket_create()`]
70 - [`zx_socket_read()`]
71 - [`zx_socket_write()`]
72
73<!-- References updated by update-docs-from-abigen, do not edit. -->
74
75[`zx_socket_accept()`]: socket_accept.md
76[`zx_socket_create()`]: socket_create.md
77[`zx_socket_read()`]: socket_read.md
78[`zx_socket_write()`]: socket_write.md
79