.\" Ouroboros man pages CC-BY 2017 - 2020
.\" Dimitri Staessens <dimitri.staessens@ugent.be>
.\" Sander Vrijders <sander.vrijders@ugent.be>

.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.
Partial writes needs to be explicitly enabled. 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 -EMSGSIZE
The buffer was too large to be written.

.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
_
\fBflow_write\fR() & Thread safety & MT-Safe
.TE

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