From 3ba111f2f93dfe6fa4a7db3d8778234fd287d134 Mon Sep 17 00:00:00 2001 From: dimitri staessens Date: Mon, 10 Apr 2017 15:36:28 +0200 Subject: doc: Add man pages for flow_allocation This commit contains only the sources, correct installation requires gzip and copying the files to /usr/local/man/man3/flow_alloc.3.gz. We need to have a look at integrating this in the build system in an efficient way. --- doc/man/flow_alloc.3 | 116 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 doc/man/flow_alloc.3 (limited to 'doc/man/flow_alloc.3') diff --git a/doc/man/flow_alloc.3 b/doc/man/flow_alloc.3 new file mode 100644 index 00000000..84dd5f57 --- /dev/null +++ b/doc/man/flow_alloc.3 @@ -0,0 +1,116 @@ +.\" Ouroboros man pages (C) 2017 +.\" Dimitri Staessens +.\" Sander Vrijders + +.TH FLOW_ALLOC 3 2017-04-10 GNU "Ouroboros Programmer's Manual" + +.SH NAME + +flow_accept, flow_alloc, flow_dealloc \- allocate and free resources +to support Inter-Process Communication between application process +instances + +.SH SYNOPSIS + +.B #include + +\fBint flow_accept(qosspec_t * \fIqs\fB, +const struct timespec * \fItimeo\fB); + +int flow_alloc(const char * \fIdst_name\fB, qosspec_t * \fIqs\fB, +const struct timespec * \fItimeo\fB); + +\fBint flow_dealloc(int \fIfd\fB);\fR + +Compile and link with \fI-louroboros\fR. + +.SH DESCRIPTION + +These calls are used to allocate and free system and network resources +to support Inter-Process Communication (IPC). Such a collection of +allocated system and network resources is referred to as a flow. A +flow has a certain Quality of Service (QoS) associated with it. + +The \fB flow_accept\fR() function blocks the calling thread waiting +for an incoming request to allocate a flow. If \fBqosspec_t * \fIqs\fR +is not NULL, the value of \fIqs\fR will be updated to reflect the +actual QoS provided by the IPC facility for the accepted flow. Which +flows this application will accept is configured outside of the +program. For an explanation on configuring which flows an application +should accept, see \fBirm\fR(8). + +The \fBflow_alloc\fR() function requests to allocate system and/or +network resources to support Inter-Process Communication between the +calling application and one or more application process instances +accepting flows for \fBchar * \fIdst_name\fR, which cannot be NULL. +The \fBflow_alloc\fR() call can specify a certain minimum \fBqosspec_t +* \fIqs\fR that has to be guaranteed by the IPC facility allocating +the resources. This can be NULL if there is no QoS to be guaranteed +(best effort service). If \fIqs\fR is not NULL, the value of \fIqs\fR +will be updated to reflect the actual QoS provided by the IPC +facility. + +The \fBflow_accept\fR() and \fBflow_alloc\fR() take a \fBconst struct +timespec * \fItimeo\fR to specify a timeout. If \fItimeo\fR is NULL, +the call will block indefinitely or until some error condition occurs. + +The \fBflow_dealloc\fR() function will release any resources +associated with the flow. + +A \fBqosspec_t\fR specifies the following QoS characteristics of a +flow: + +TODO: specify a qosspec_t + +.SH RETURN VALUE + +On success, \fBflow_accept\fR() and \fBflow_alloc\fR() calls return a +non-negative integer, referred to as a flow descriptor. On failure, a +negative value indicating the error will be returned. + +.SH ERRORS + +\fBflow_accept\fR(), \fBflow_alloc\fR() and \fBflow_dealloc\fR() can +return the following errors: + +.B -EINVAL +An invalid argument was passed. + +.B -EIRMD +Failed to contact an IRMd instance. + +\fBflow_accept\fR() and \fBflow_alloc\fR() can also return + +.B -EBADF +No more flow desciptors or port_ids available. + +.B -ENOMEM +Not enough system memory resources available to allocate the flow. + +.B -ETIMEDOUT +Flow allocation timed out. + +.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_accept\fR() & Thread safety & MT-Safe +_ +\fBflow_alloc\fR() & Thread safety & MT-Safe +_ +\fBflow_dealloc\fR() & Thread safety & MT-Safe +.TE + +.SH SEE ALSO + +.BR ap_init "(3), " ap_fini "(3), " flow_read "(3), " flow_write (3) + +.SH COLOPHON +This page is part of the Ouroboros project, found at +https://bitbucket.org/ouroboros-rina/ouroboros -- cgit v1.2.3