diff options
| -rw-r--r-- | doc/man/ap_fini.3 | 1 | ||||
| -rw-r--r-- | doc/man/ap_init.3 | 67 | ||||
| -rw-r--r-- | doc/man/flow_accept.3 | 1 | ||||
| -rw-r--r-- | doc/man/flow_alloc.3 | 116 | ||||
| -rw-r--r-- | doc/man/flow_dealloc.3 | 1 | ||||
| -rw-r--r-- | doc/man/flow_read.3 | 74 | ||||
| -rw-r--r-- | doc/man/flow_write.3 | 1 | ||||
| -rw-r--r-- | src/lib/dev.c | 8 |
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 <[email protected]> +.\" Sander Vrijders <[email protected]> + +.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 <[email protected]> +.\" Sander Vrijders <[email protected]> + +.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 <[email protected]> +.\" Sander Vrijders <[email protected]> + +.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; } } |