diff options
Diffstat (limited to 'doc/man')
| -rw-r--r-- | doc/man/CMakeLists.txt | 40 | ||||
| -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 |
8 files changed, 301 insertions, 0 deletions
diff --git a/doc/man/CMakeLists.txt b/doc/man/CMakeLists.txt new file mode 100644 index 00000000..c864d756 --- /dev/null +++ b/doc/man/CMakeLists.txt @@ -0,0 +1,40 @@ +set(MAN_NAMES + # Add man page sources here + ap_init.3 + ap_fini.3 + flow_accept.3 + flow_alloc.3 + flow_dealloc.3 + flow_read.3 + flow_write.3 + ) + +macro(INSTALL_MAN __mans) + foreach (_man ${ARGV}) + string(REGEX REPLACE "^.+[.]([1-9]).gz" "\\1" _mansect ${_man}) + install(FILES ${_man} DESTINATION "usr/share/man/man${_mansect}") + endforeach (_man) +endmacro(INSTALL_MAN __mans) + +find_program(GZIP_EXECUTABLE + NAMES gzip + DOC "Will gzip the man pages") + +if (GZIP_EXECUTABLE) + foreach (m ${MAN_NAMES}) + set(md ${CMAKE_CURRENT_BINARY_DIR}/${m}.gz) + + add_custom_command( + OUTPUT ${md} + COMMAND ${GZIP_EXECUTABLE} + ARGS -c ${CMAKE_CURRENT_SOURCE_DIR}/${m} > ${md} + COMMENT "Compressing manpage ${m}" + VERBATIM) + + set(MAN_FILES ${MAN_FILES} ${md}) + endforeach () + + add_custom_target(man ALL DEPENDS ${MAN_FILES}) + + INSTALL_MAN(${MAN_FILES}) +endif () 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 |