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

.TH FCCNTL 3 2018-10-04 Ouroboros "Ouroboros Programmer's Manual"

.SH NAME

fccntl \- control commands for flows and FRCT connections

.SH SYNOPSIS

.B #include <ouroboros/fccntl.h>

\fBint fccntl(int \fIfd\fB, int \fIcmd\fB, ...);

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

.SH DESCRIPTION

\fBfccntl\fR() is used to control the configuration of flows and
connections.

Supported commands are:

\fBFLOWSSNDTIMEO\fR - set the sender timeout. Takes a \fBstruct
timespec * \fItimeo\fR as third argument. Passing NULL for \fItimeo\fR
disables the timeout.

\fBFLOWGSNDTIMEO\fR - retrieve the current sender timeout. Takes a
\fBstruct timespec * \fItimeo\fR as third argument.

\fBFLOWSRCVTIMEO\fR - set the receiver timeout. Takes a \fBstruct
timespec * \fItimeo\fR as third argument. Passing NULL for \fItimeo\fR
disables the timeout.

\fBFLOWGRCVTIMEO\fR - retrieve the current receiver timeout. Takes a
\fBstruct timespec * \fItimeo\fR as third argument.

\fBFLOWGQOSSPEC\fR  - retrieve the current QoS specification of the
flow. Takes a \fBqosspec_t * \fIqs\fR as third argument.

\fBFLOWSFLAGS\fR - set flow flags. Takes flow \fBuint32_t\fR
\fIflags\fR as third argument. Supported flags are:

.RS 8
\fIFLOWFRDONLY\fR   - set flow to read-only.

\fIFLOWFWRONLY\fR   - set flow_to write-only.

\fIFLOWFRDWR\fR     - set flow to read-write.

\fIFLOWFDOWN\fR     - mark flow as down.

\fIFLOWFRNOBLOCK\fR - set read to non-blocking.

\fIFLOWFWNOBLOCK\fR - set write to non-blocking.

\fIFLOWFNONBLOCK\fR - set I/O to non-blocking read/write.

\fIFLOWFRNOPART\fR  - disable partial reading.

\fIFLOWFWNOPART\fR  - disable partial writing.

\fIFLOWFDEFAULT\fR  - set flow defaults (blocking, read-write,
no partial writes).

.RE

\fBFLOWGFLAGS\fR    - get the current flow flags. Takes an \fBuint32_t *
\fIflags\fR as third argument.

\fBFLOWGRXQLEN\fR   - get the current number of packets in the receive
buffer. Takes a \fBsize_t \fIqlen\fR * as third argument.

\fBFLOWGTXQLEN\fR   - get the current number of packets in the transmit
buffer. Takes a \fBsize_t \fIqlen\fR * as third argument.

\fBFLOWSTXQDLY\fR   - set the target queueing delay for the transmit
occupancy limiter. Takes a \fBstruct timespec * \fItimeo\fR as third
argument. A zero delay leaves the ring unlimited, bounded only by its
slot count. The build-time default is applied when the flow is
created. The delay must be a normalised, non-negative timespec no
longer than the maximum the limiter accepts.

\fBFLOWGTXQDLY\fR   - retrieve the current target queueing delay for
the transmit occupancy limiter. Takes a \fBstruct timespec * \fItimeo\fR
as third argument.

\fBFRCTSFLAGS\fR    - set the current flow flags. Takes an \fBuint16_t
\fIflags\fR as third argument. Supported flags are:

.RS 8
\fIFRCTFRESCNTL\fR - resource control enabled.

\fIFRCTFRTX\fR      - retransmission enabled. Cannot be modified and will
be ignored on set.

\fIFRCTFLINGER\fR   - finish connection on flow deallocation.

.RE

\fBFRCTGFLAGS\fR    - get the current flow flags. Takes an \fBuint16_t *
\fIflags\fR as third argument.

.SH RETURN VALUE

On success, \fBfccntl\fR() returns 0.

.SH ERRORS

\fBfccntl\fR() can return

.B -EINVAL
An invalid argument was passed. This is also returned when the delay
passed to FLOWSTXQDLY is negative, is not normalised, or exceeds the
maximum the transmit occupancy limiter accepts.

.B -EPERM
Operation not permitted. This is returned when requesting the value of
a timeout (FLOWGSNDTIMEO or FLOWGRCVTIMEO) when no such timeout was
set, or when FLOWSTXQDLY/FLOWGTXQDLY is used on a flow with no
transmit occupancy ring.

.B -EBADF
Invalid flow descriptor passed.

.B -ENOTALLOC
Flow is not allocated.

.B -ENOTSUP
The specified command is not supported.

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

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

.SH SEE ALSO

.BR flow_alloc "(3), " flow_read "(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/