FLOW_READ(3)

NAME
flow_read, flow_write - read and write from/to a flow

SYNOPSIS
#include <ouroboros/dev.h> ssize_t flow_read(int fd, void * buf, size_t count); ssize_t flow_write(int fd, const void * buf, size_t count); Compile and link with -louroboros-dev.

DESCRIPTION
The flow_read() function attempts to read at most count bytes from the flow associated with the allocated flow descriptor fd into the buffer pointed to by buf. The flow_write() function attempts to write count bytes from the supplied buffer buf to the flow specified by fd.

RETURN VALUE
On success, flow_read() returns the number of bytes read. On failure, a negative value indicating the error will be returned. Partial reads are enabled by default. If the number of bytes read equals count, a subsequent call to flow_read() should be performed to check if there were more bytes to read. This call to flow_read will return 0 if there was no more data and mark the end of the datagram. On success, flow_write() returns the number of bytes written. On failure, a negative value indicating the error will be returned. Passing a NULL pointer for buf returns 0 with no other effects.

ERRORS
-EINVAL An invalid argument was passed. -EIRMD Failed to contact an IRMd instance. -EBADF Invalid flow descriptor passed. -ENOTALLOC The flow was not allocated. -EFLOWDOWN The flow has been reported down. -EFLOWPEER The flow's peer is unresponsive (flow timed out). -EMSGSIZE The received packet does not fit in the caller's buffer and partial reads are disabled (see fccntl(3), FLOWFRNOPART).

ATTRIBUTES
For an explanation of the terms used in this section, see attributes(7).
Interface | Attribute | Value
flow_read() | Thread safety | MT-Safe race:fd
flow_write() | Thread safety | MT-Safe race:fd

THREAD SAFETY
Only one thread may call flow_read() on a given file descriptor at any time. Partial-read state kept across calls assumes a single logical reader; two threads racing flow_read() on the same fd is undefined behaviour. Likewise, only one thread may call flow_write() on a given fd at a time; two writer threads on the same fd is undefined behaviour.

Combining a writer thread with a reader thread (one thread calling flow_write(), another calling flow_read() or fevent()) is permitted and safe. The writer does not need a dedicated reader thread — when the FRCT send window fills, flow_write() drives its own inbound rx draining internally to process incoming ACKs and reopen the window, clamped by the caller's fccntl(3) send-timeout if any.

Monitoring the same fd via fevent() from a different thread is well-defined but races: events reported by fevent() may already have been consumed by the racing flow_read(), so the second reader may then block. See fevent(3).

TERMINOLOGY
Please see ouroboros-glossary(7).

SEE ALSO
fccntl(3), flow_alloc(3), fqueue(3), fset(3), ouroboros(8)

COLOPHON
This page is part of the Ouroboros project, found at http://ouroboros.rocks These man pages are licensed under the Creative Commons Attribution 4.0 International License. To view a copy of this license, visit http://creativecommons.org/licenses/by/4.0/