1# zx_fifo_read
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7fifo_read - read data from 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_read(zx_handle_t handle,
17                         size_t elem_size,
18                         void* data,
19                         size_t count,
20                         size_t* actual_count);
21```
22
23## DESCRIPTION
24
25`zx_fifo_read()` attempts to read up to *count* elements from the fifo
26*handle* into *data*.
27
28Fewer elements may be read than requested if there are insufficient
29elements in the fifo to fulfill the entire request. The number of
30elements actually read is returned via *actual_count*.
31
32The element size specified by *elem_size* must match the element size
33that was passed into [`zx_fifo_create()`].
34
35*data* must have a size of at least `count * elem_size` bytes.
36
37*actual_count* is allowed to be NULL. This is useful when reading
38a single element: if *count* is 1 and `zx_fifo_read()` returns **ZX_OK**,
39*actual_count* is guaranteed to be 1 and thus can be safely ignored.
40
41It is not legal to read zero elements.
42
43## RIGHTS
44
45<!-- Updated by update-docs-from-abigen, do not edit. -->
46
47*handle* must be of type **ZX_OBJ_TYPE_FIFO** and have **ZX_RIGHT_READ**.
48
49## RETURN VALUE
50
51`zx_fifo_read()` returns **ZX_OK** on success, and returns
52the number of elements read (at least one) via *actual_count*.
53
54## ERRORS
55
56**ZX_ERR_BAD_HANDLE**  *handle* is not a valid handle.
57
58**ZX_ERR_WRONG_TYPE**  *handle* is not a fifo handle.
59
60**ZX_ERR_INVALID_ARGS**  *data* is an invalid pointer or *actual_count*
61is an invalid pointer.
62
63**ZX_ERR_OUT_OF_RANGE**  *count* is zero or *elem_size* is not equal
64to the element size of the fifo.
65
66**ZX_ERR_ACCESS_DENIED**  *handle* does not have **ZX_RIGHT_READ**.
67
68**ZX_ERR_PEER_CLOSED**  The other side of the fifo is closed.
69
70**ZX_ERR_SHOULD_WAIT**  The fifo is empty.
71
72
73## SEE ALSO
74
75 - [`zx_fifo_create()`]
76 - [`zx_fifo_write()`]
77
78<!-- References updated by update-docs-from-abigen, do not edit. -->
79
80[`zx_fifo_create()`]: fifo_create.md
81[`zx_fifo_write()`]: fifo_write.md
82