.\" Ouroboros man pages CC-BY 2017 - 2024
.\" Dimitri Staessens <dimitri@ouroboros.rocks>
.\" Sander Vrijders <sander@ouroboros.rocks>

.TH FLOW_READ 3 2017-04-10 Ouroboros "Ouroboros Programmer's Manual"

.SH NAME

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

.SH SYNOPSIS

.B #include <ouroboros/dev.h>

\fBssize_t flow_read(int \fIfd\fB, void * \fIbuf\fB, size_t \fIcount\fB);\fR

\fBssize_t flow_write(int \fIfd\fB, const void * \fIbuf\fB, size_t \fIcount\fB);\fR

Compile and link with \fI-louroboros-dev\fR.

.SH DESCRIPTION

The \fBflow_read\fR() function attempts to read at most \fIcount\fR
bytes from the flow associated with the allocated flow descriptor
\fIfd\fR into the buffer pointed to by buf.

The \fBflow_write\fR() function attempts to write \fIcount\fR bytes
from the supplied buffer \fIbuf\fR to the flow specified by \fIfd\fR.

.SH RETURN VALUE

On success, \fBflow_read\fR() 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 \fBflow_read\fR() should be
performed to check if there were more bytes to read. This call to
\fBflow_read\fR will return 0 if there was no more data and mark the
end of the datagram.

On success, \fBflow_write\fR() returns the number of bytes written. On
failure, a negative value indicating the error will be returned.
Passing a NULL pointer for \fIbuf\fR returns 0 with no other effects.

.SH ERRORS
.B -EINVAL
An invalid argument was passed.

.B -EIRMD
Failed to contact an IRMd instance.

.B -EBADF
Invalid flow descriptor passed.

.B -ENOTALLOC
The flow was not allocated.

.B -EFLOWDOWN
The flow has been reported down.

.B -EFLOWPEER
The flow's peer is unresponsive (flow timed out).

.B -EMSGSIZE
The received packet does not fit in the caller's buffer and partial
reads are disabled (see \fBfccntl\fR(3), \fBFLOWFRNOPART\fR).

.SH ATTRIBUTES

For an explanation of the terms used in this section, see \fBattributes\fR(7).

.TS
box, tab(&);
LB|LB|LB
L|L|L.
Interface & Attribute & Value
_
\fBflow_read\fR() & Thread safety & MT-Safe race:fd
_
\fBflow_write\fR() & Thread safety & MT-Safe race:fd
.TE

.SH THREAD SAFETY
Only one thread may call
.BR flow_read ()
on a given file descriptor at any time. Partial-read state kept
across calls assumes a single logical reader; two threads racing
.BR flow_read ()
on the same fd is undefined behaviour. Likewise, only one thread
may call
.BR flow_write ()
on a given fd at a time; two writer threads on the same fd is
undefined behaviour.
.PP
Combining a writer thread with a reader thread (one thread calling
.BR flow_write (),
another calling
.BR flow_read ()
or
.BR fevent ())
is permitted and safe. The writer does not need a dedicated reader
thread \(em when the FRCT send window fills,
.BR flow_write ()
drives its own inbound rx draining internally to process incoming
ACKs and reopen the window, clamped by the caller's
.BR fccntl (3)
send-timeout if any.
.PP
Monitoring the same fd via
.BR fevent ()
from a different thread is well-defined but races: events reported
by
.BR fevent ()
may already have been consumed by the racing
.BR flow_read (),
so the second reader may then block. See
.BR fevent (3).

.SH TERMINOLOGY
Please see \fBouroboros-glossary\fR(7).

.SH SEE ALSO

.BR fccntl "(3), " flow_alloc "(3), " fqueue "(3), " fset "(3), " \
ouroboros (8)

.SH 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/