diff options
| -rw-r--r-- | CMakeLists.txt | 1 | ||||
| -rw-r--r-- | doc/CMakeLists.txt | 1 | ||||
| -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 | ||||
| -rw-r--r-- | include/ouroboros/wrap/CMakeLists.txt | 4 | ||||
| -rw-r--r-- | src/ipcpd/shim-eth-llc/CMakeLists.txt | 4 | ||||
| -rw-r--r-- | src/ipcpd/shim-udp/CMakeLists.txt | 8 | ||||
| -rw-r--r-- | src/irmd/main.c | 4 | ||||
| -rw-r--r-- | src/lib/dev.c | 8 |
15 files changed, 317 insertions, 14 deletions
diff --git a/CMakeLists.txt b/CMakeLists.txt index e6c33c16..3c7266eb 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -83,6 +83,7 @@ include_directories(${PROTOBUF_C_INCLUDE_DIRS}) add_subdirectory(src) add_subdirectory(include) +add_subdirectory(doc) # Uninstall target configure_file( diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt new file mode 100644 index 00000000..5cf30050 --- /dev/null +++ b/doc/CMakeLists.txt @@ -0,0 +1 @@ +add_subdirectory(man) 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 diff --git a/include/ouroboros/wrap/CMakeLists.txt b/include/ouroboros/wrap/CMakeLists.txt index fd9368e8..6150fb17 100644 --- a/include/ouroboros/wrap/CMakeLists.txt +++ b/include/ouroboros/wrap/CMakeLists.txt @@ -4,7 +4,7 @@ include_directories(${CMAKE_SOURCE_DIR}/include) include_directories(${CMAKE_BINARY_DIR}/include) if (NOT SWIG_FOUND) - message("-- SWIG not found: Bindings for other languages disabled.") + message(STATUS "SWIG not found: Bindings for other languages disabled.") else () include(${SWIG_USE_FILE}) include_directories(${CMAKE_CURRENT_SOURCE_DIR}) @@ -12,7 +12,7 @@ else () find_package(PythonLibs) if (NOT PYTHONLIBS_FOUND) - message("-- Python not found: Python bindings will not be built.") + message(STATUS "Python not found: Python bindings will not be built.") else () include_directories(${PYTHON_INCLUDE_PATH}) diff --git a/src/ipcpd/shim-eth-llc/CMakeLists.txt b/src/ipcpd/shim-eth-llc/CMakeLists.txt index b3abc052..08f50c04 100644 --- a/src/ipcpd/shim-eth-llc/CMakeLists.txt +++ b/src/ipcpd/shim-eth-llc/CMakeLists.txt @@ -33,9 +33,9 @@ target_link_libraries(ipcpd-shim-eth-llc LINK_PUBLIC ouroboros ${PROTOBUF_C_LIBRARY}) if (${NETMAP_C_INCLUDE_DIR} STREQUAL "NETMAP_C_INCLUDE_DIR-NOTFOUND") - message("-- Could not find netmap. Install for better performance.") + message(STATUS "Could not find netmap. Install for better performance.") else () - message("-- Found netmap headers in ${NETMAP_C_INCLUDE_DIR}") + message(STATUS "Found netmap headers in ${NETMAP_C_INCLUDE_DIR}") include_directories(${NETMAP_C_INCLUDE_DIR}) add_compile_flags(ipcpd-shim-eth-llc -DHAVE_NETMAP) test_and_set_c_compiler_flag_global(-std=c99) diff --git a/src/ipcpd/shim-udp/CMakeLists.txt b/src/ipcpd/shim-udp/CMakeLists.txt index 2560f242..3ff8dd5f 100644 --- a/src/ipcpd/shim-udp/CMakeLists.txt +++ b/src/ipcpd/shim-udp/CMakeLists.txt @@ -42,12 +42,12 @@ find_program(NSLOOKUP_EXECUTABLE include(AddCompileFlags) if (${NSUPDATE_EXECUTABLE} STREQUAL "NSUPDATE_EXECUTABLE-NOTFOUND") - message("-- Could not find nsupdate. Disabling DDNS functionality.") + message(STATUS "Could not find nsupdate. Disabling DDNS functionality.") elseif (${NSLOOKUP_EXECUTABLE} STREQUAL "NSLOOKUP_EXECUTABLE-NOTFOUND") - message("-- Could not find nslookup. Disabling DNS lookups.") + message(STATUS "Could not find nslookup. Disabling DNS lookups.") else () - message("-- Found nsupdate: ${NSUPDATE_EXECUTABLE}") - message("-- Found nslookup: ${NSLOOKUP_EXECUTABLE}") + message(STATUS "Found nsupdate: ${NSUPDATE_EXECUTABLE}") + message(STATUS "Found nslookup: ${NSLOOKUP_EXECUTABLE}") add_compile_flags(ipcpd-shim-udp -DCONFIG_OUROBOROS_ENABLE_DNS) endif () diff --git a/src/irmd/main.c b/src/irmd/main.c index 125061fb..d24c0ba1 100644 --- a/src/irmd/main.c +++ b/src/irmd/main.c @@ -2171,14 +2171,14 @@ int main(int argc, { struct sigaction sig_act; sigset_t sigset; + bool use_stdout = false; + sigemptyset(&sigset); sigaddset(&sigset, SIGINT); sigaddset(&sigset, SIGQUIT); sigaddset(&sigset, SIGHUP); sigaddset(&sigset, SIGPIPE); - bool use_stdout = false; - if (geteuid() != 0) { log_err("IPC Resource Manager must be run as root."); exit(EXIT_FAILURE); diff --git a/src/lib/dev.c b/src/lib/dev.c index a4707dc3..d68fb471 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; } } |