1# zx_fifo_create
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7fifo_create - create a fifo
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_fifo_create(size_t elem_count,
17                           size_t elem_size,
18                           uint32_t options,
19                           zx_handle_t* out0,
20                           zx_handle_t* out1);
21```
22
23## DESCRIPTION
24
25`zx_fifo_create()` creates a fifo, which is actually a pair of fifos
26of *elem_count* entries of *elem_size* bytes.  Two endpoints are
27returned.  Writing to one endpoint enqueues an element into the fifo
28that the opposing endpoint reads from.
29
30Fifos are intended to be the control plane for shared memory transports.
31Their read and write operations are more efficient than *sockets* or
32*channels*, but there are severe restrictions on the size of elements
33and buffers.
34
35The *elem_count* must be a power of two.  The total size of each fifo
36(`elem_count * elem_size`) may not exceed 4096 bytes.
37
38The *options* argument must be 0.
39
40## RIGHTS
41
42<!-- Updated by update-docs-from-abigen, do not edit. -->
43
44TODO(ZX-2399)
45
46## RETURN VALUE
47
48`zx_fifo_create()` returns **ZX_OK** on success. In the event of
49failure, one of the following values is returned.
50
51## ERRORS
52
53**ZX_ERR_INVALID_ARGS**  *out0* or *out1* is an invalid pointer or NULL or
54*options* is any value other than 0.
55
56**ZX_ERR_OUT_OF_RANGE**  *elem_count* or *elem_size* is zero, or *elem_count*
57is not a power of two, or *elem_count* * *elem_size* is greater than 4096.
58
59**ZX_ERR_NO_MEMORY**  Failure due to lack of memory.
60There is no good way for userspace to handle this (unlikely) error.
61In a future build this error will no longer occur.
62
63
64## SEE ALSO
65
66 - [`zx_fifo_read()`]
67 - [`zx_fifo_write()`]
68
69<!-- References updated by update-docs-from-abigen, do not edit. -->
70
71[`zx_fifo_read()`]: fifo_read.md
72[`zx_fifo_write()`]: fifo_write.md
73