Merged in dstaesse/ouroboros/be-man (pull request #475)

doc: Add man pages for flow allocation

8 files changed, 265 insertions, 4 deletions

diff --git a/doc/man/ap_fini.3 b/doc/man/ap_fini.3
new file mode 100644
index 00000000..4aaa723b
--- /dev/null
+++ b/doc/man/ap_fini.3
@@ -0,0 +1 @@
+.so ap_init.3
diff --git a/doc/man/ap_init.3 b/doc/man/ap_init.3
new file mode 100644
index 00000000..c5b93764
--- /dev/null
+++ b/doc/man/ap_init.3
@@ -0,0 +1,67 @@
+.\" Ouroboros man pages (C) 2017
+.\" Dimitri Staessens <dimitri.staessens@ugent.be>
+.\" Sander Vrijders <sander.vrijders@ugent.be>
+
+.TH AP_INIT 3 2017-04-10 GNU "Ouroboros Programmer's Manual"
+
+.SH NAME
+
+ap_init, ap_fini \- initialize and finalize an application for using
+Ouroboros
+
+.SH SYNOPSIS
+
+.B #include <ouroboros/dev.h>
+
+\fBint ap_init(char * \fIapn\fB);\fR
+
+\fBvoid ap_fini(void);\fR
+
+Compile and link with \fI-louroboros\fR.
+
+.SH DESCRIPTION
+
+The \fBap_init\fR() call initializes an application process instance
+for using the Ouroboros IPC infrastructure. If the application is a
+server or peer, a \fBchar * \fIapn\fR has to be provided indicating the
+application process that this instance belongs to. This is usually
+argv[0]. A client application may pass NULL. The \fBap_fini\fR() call
+will release all resources allocated by \fBap_fini\fR().
+
+\fBap_init\fR() and \fBap_fini\fR() should be called only once in the
+application.
+
+.SH RETURN VALUE
+
+On success, \fBap_init\fR() returns 0. On failure, a negative value
+indicating the error will be returned. The \fBap_fini\fR() function
+has no return value.
+
+.SH ERRORS
+
+\fBap_init\fR() can return the following errors:
+
+.B -EIRMD
+Failed to contact an IRMd instance.
+
+.B -ENOMEM
+Insufficient system resources to intialize the application.
+
+.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
+_
+\fBap_init\fR() & Thread safety & MT-Safe
+_
+\fBap_fini\fR() & Thread safety & MT-Safe
+.TE
+
+.SH COLOPHON
+This page is part of the Ouroboros project, found at
+https://bitbucket.org/ouroboros-rina/ouroboros
diff --git a/doc/man/flow_accept.3 b/doc/man/flow_accept.3
new file mode 100644
index 00000000..8b1b6963
--- /dev/null
+++ b/doc/man/flow_accept.3
@@ -0,0 +1 @@
+.so 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 <dimitri.staessens@ugent.be>
+.\" Sander Vrijders <sander.vrijders@ugent.be>
+
+.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 <ouroboros/dev.h>
+
+\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
diff --git a/doc/man/flow_dealloc.3 b/doc/man/flow_dealloc.3
new file mode 100644
index 00000000..8b1b6963
--- /dev/null
+++ b/doc/man/flow_dealloc.3
@@ -0,0 +1 @@
+.so flow_alloc.3
diff --git a/doc/man/flow_read.3 b/doc/man/flow_read.3
new file mode 100644
index 00000000..f4f94e67
--- /dev/null
+++ b/doc/man/flow_read.3
@@ -0,0 +1,74 @@
+.\" Ouroboros man pages (C) 2017
+.\" Dimitri Staessens <dimitri.staessens@ugent.be>
+.\" Sander Vrijders <sander.vrijders@ugent.be>
+
+.TH FLOW_READ 3 2017-04-10 GNU "Ouroboros Programmer's Manual"
+
+.SH NAME
+
+flow_read, flow_write \- read and write from/to a flow
+
+.SH SYNOPSIS
+
+.B #include <ouroboros/dev.h>
+
+\fBint flow_read(int \fIfd\fB, void * \fIbuf\fB, size_t \fIcount\fB);\fR
+
+\fBint flow_write(int \fIfd\fB, const void * \fIbuf\fB, size_t \fIcount\fB);\fR
+
+Compile and link with \fI-louroboros\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.
+
+On success, \fBflow_write\fR() returns 0. 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.
+
+.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 SEE ALSO
+
+.BR flow_alloc "(3), " flow_dealloc (3)
+
+.SH COLOPHON
+This page is part of the Ouroboros project, found at
+https://bitbucket.org/ouroboros-rina/ouroboros
diff --git a/doc/man/flow_write.3 b/doc/man/flow_write.3
new file mode 100644
index 00000000..635e9b0b
--- /dev/null
+++ b/doc/man/flow_write.3
@@ -0,0 +1 @@
+.so flow_read.3
diff --git a/src/lib/dev.c b/src/lib/dev.c
index 433fb93b..18890234 100644
--- a/src/lib/dev.c
+++ b/src/lib/dev.c
@@ -268,7 +268,7 @@ int ap_init(const char * ap_name)
         if (ai.fqset == NULL) {
                 bmp_destroy(ai.fqueues);
                 bmp_destroy(ai.fds);
-                return -1;
+                return -ENOMEM;
         }
 
         ai.rdrb = shm_rdrbuff_open();
@@ -285,7 +285,7 @@ int ap_init(const char * ap_name)
                 shm_flow_set_destroy(ai.fqset);
                 bmp_destroy(ai.fqueues);
                 bmp_destroy(ai.fds);
-                return -1;
+                return -ENOMEM;
         }
 
         for (i = 0; i < AP_MAX_FLOWS; ++i)
@@ -298,7 +298,7 @@ int ap_init(const char * ap_name)
                 shm_flow_set_destroy(ai.fqset);
                 bmp_destroy(ai.fqueues);
                 bmp_destroy(ai.fds);
-                return -1;
+                return -ENOMEM;
         }
 
         if (ap_name != NULL) {
@@ -319,7 +319,7 @@ int ap_init(const char * ap_name)
                         shm_flow_set_destroy(ai.fqset);
                         bmp_destroy(ai.fqueues);
                         bmp_destroy(ai.fds);
-                        return -1;
+                        return -EIRMD;
                 }
         }