From abb4dcaf84b4224788c1d343fe557079e053ee5b Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 24 Mar 2024 13:36:51 -0700 Subject: subdir for compmat --- docs/man/nng_aio_abort.3.adoc | 55 -------------- docs/man/nng_aio_alloc.3.adoc | 88 ---------------------- docs/man/nng_aio_begin.3.adoc | 64 ---------------- docs/man/nng_aio_busy.3.adoc | 56 -------------- docs/man/nng_aio_cancel.3.adoc | 58 -------------- docs/man/nng_aio_count.3.adoc | 61 --------------- docs/man/nng_aio_defer.3.adoc | 78 ------------------- docs/man/nng_aio_finish.3.adoc | 60 --------------- docs/man/nng_aio_free.3.adoc | 54 ------------- docs/man/nng_aio_get_input.3.adoc | 53 ------------- docs/man/nng_aio_get_msg.3.adoc | 49 ------------ docs/man/nng_aio_get_output.3.adoc | 56 -------------- docs/man/nng_aio_result.3.adoc | 59 --------------- docs/man/nng_aio_set_input.3.adoc | 63 ---------------- docs/man/nng_aio_set_iov.3.adoc | 67 ----------------- docs/man/nng_aio_set_msg.3.adoc | 47 ------------ docs/man/nng_aio_set_output.3.adoc | 60 --------------- docs/man/nng_aio_set_timeout.3.adoc | 74 ------------------ docs/man/nng_aio_stop.3.adoc | 60 --------------- docs/man/nng_aio_wait.3.adoc | 54 ------------- docs/man/nng_alloc.3.adoc | 56 -------------- docs/man/nng_bus.7.adoc | 84 --------------------- docs/man/nng_bus_open.3.adoc | 52 ------------- docs/man/nng_ctx_close.3.adoc | 54 ------------- docs/man/nng_ctx_get.3.adoc | 131 -------------------------------- docs/man/nng_ctx_getopt.3.adoc | 134 --------------------------------- docs/man/nng_ctx_id.3.adoc | 51 ------------- docs/man/nng_ctx_open.3.adoc | 71 ----------------- docs/man/nng_ctx_recv.3.adoc | 74 ------------------ docs/man/nng_ctx_recvmsg.3.adoc | 63 ---------------- docs/man/nng_ctx_send.3.adoc | 88 ---------------------- docs/man/nng_ctx_sendmsg.3.adoc | 84 --------------------- docs/man/nng_ctx_set.3.adoc | 113 --------------------------- docs/man/nng_ctx_setopt.3.adoc | 114 ---------------------------- docs/reference/src/SUMMARY.md | 2 +- docs/reference/src/api/compat.md | 120 ----------------------------- docs/reference/src/api/compat/index.md | 120 +++++++++++++++++++++++++++++ 37 files changed, 121 insertions(+), 2506 deletions(-) delete mode 100644 docs/man/nng_aio_abort.3.adoc delete mode 100644 docs/man/nng_aio_alloc.3.adoc delete mode 100644 docs/man/nng_aio_begin.3.adoc delete mode 100644 docs/man/nng_aio_busy.3.adoc delete mode 100644 docs/man/nng_aio_cancel.3.adoc delete mode 100644 docs/man/nng_aio_count.3.adoc delete mode 100644 docs/man/nng_aio_defer.3.adoc delete mode 100644 docs/man/nng_aio_finish.3.adoc delete mode 100644 docs/man/nng_aio_free.3.adoc delete mode 100644 docs/man/nng_aio_get_input.3.adoc delete mode 100644 docs/man/nng_aio_get_msg.3.adoc delete mode 100644 docs/man/nng_aio_get_output.3.adoc delete mode 100644 docs/man/nng_aio_result.3.adoc delete mode 100644 docs/man/nng_aio_set_input.3.adoc delete mode 100644 docs/man/nng_aio_set_iov.3.adoc delete mode 100644 docs/man/nng_aio_set_msg.3.adoc delete mode 100644 docs/man/nng_aio_set_output.3.adoc delete mode 100644 docs/man/nng_aio_set_timeout.3.adoc delete mode 100644 docs/man/nng_aio_stop.3.adoc delete mode 100644 docs/man/nng_aio_wait.3.adoc delete mode 100644 docs/man/nng_alloc.3.adoc delete mode 100644 docs/man/nng_bus.7.adoc delete mode 100644 docs/man/nng_bus_open.3.adoc delete mode 100644 docs/man/nng_ctx_close.3.adoc delete mode 100644 docs/man/nng_ctx_get.3.adoc delete mode 100644 docs/man/nng_ctx_getopt.3.adoc delete mode 100644 docs/man/nng_ctx_id.3.adoc delete mode 100644 docs/man/nng_ctx_open.3.adoc delete mode 100644 docs/man/nng_ctx_recv.3.adoc delete mode 100644 docs/man/nng_ctx_recvmsg.3.adoc delete mode 100644 docs/man/nng_ctx_send.3.adoc delete mode 100644 docs/man/nng_ctx_sendmsg.3.adoc delete mode 100644 docs/man/nng_ctx_set.3.adoc delete mode 100644 docs/man/nng_ctx_setopt.3.adoc delete mode 100644 docs/reference/src/api/compat.md create mode 100644 docs/reference/src/api/compat/index.md (limited to 'docs') diff --git a/docs/man/nng_aio_abort.3.adoc b/docs/man/nng_aio_abort.3.adoc deleted file mode 100644 index 8d4e904b..00000000 --- a/docs/man/nng_aio_abort.3.adoc +++ /dev/null @@ -1,55 +0,0 @@ -= nng_aio_abort(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_aio_abort - abort asynchronous I/O operation - -== SYNOPSIS - -[source, c] ----- -#include - -void nng_aio_abort(nng_aio *aio, int err); ----- - -== DESCRIPTION - -The `nng_aio_abort()` function aborts an operation previously started -with the handle _aio_. -If the operation is aborted, then the callback -for the handle will be called, and the function -xref:nng_aio_result.3.adoc[`nng_aio_result()`] will return the error _err_. - -This function does not wait for the operation to be fully aborted, but -returns immediately. - -If no operation is currently in progress (either because it has already -finished, or no operation has been started yet), then this function -has no effect. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], -xref:nng_aio_cancel.3.adoc[nng_aio_cancel(3)], -xref:nng_aio_result.3.adoc[nng_aio_result(3)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_aio_alloc.3.adoc b/docs/man/nng_aio_alloc.3.adoc deleted file mode 100644 index 6a424e3b..00000000 --- a/docs/man/nng_aio_alloc.3.adoc +++ /dev/null @@ -1,88 +0,0 @@ -= nng_aio_alloc(3) -// -// Copyright 2022 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_aio_alloc - allocate asynchronous I/O handle - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_aio_alloc(nng_aio **aiop, void (*callb)(void *), void *arg); ----- - -== DESCRIPTION - -The `nng_aio_alloc()` function allocates a handle for ((asynchronous I/O)) -operations, and stores a pointer to it in __aiop__. -The handle is initialized with a completion ((callback)) of _callb_, -which will be executed when an associated asynchronous operation finishes. -It will be called with the argument _arg_. - -NOTE: The callback _callb_ must not perform any blocking operations, and -must complete its execution quickly. If _callb_ does block, this can -lead ultimately to an apparent "hang" or deadlock in the application. -This also means you should avoid operations such as allocating new objects, -which also means opening or closing sockets, dialers, and so forth. - -TIP: If more complex or blocking work needs to be performed by _callb_, a separate -thread can be used, along with a xref:nng_cv_alloc.3supp.adoc[condition variable] -which can be signaled by the callback. - -Asynchronous I/O operations all take an xref:nng_aio.5.adoc[`nng_aio`] -handle such as allocated by this function. -Such operations are usually started by a function that returns immediately. -The operation is then run asynchronously, and completes sometime later. -When that operation is complete, the callback supplied here is called, -and that callback is able to determine the result of the operation using -xref:nng_aio_result.3.adoc[`nng_aio_result()`], -xref:nng_aio_count.3.adoc[`nng_aio_count()`], -and xref:nng_aio_get_output.3.adoc[`nng_aio_get_output()`]. - -It is possible to wait synchronously for an otherwise asynchronous operation -by using the function xref:nng_aio_wait.3.adoc[`nng_aio_wait()`]. -In that case, it is permissible for _callb_ and _arg_ to both be `NULL`. -Note that if these are `NULL`, then it will not be possible to determine when the -operation is complete except by calling the aforementioned -xref:nng_aio_wait.3.adoc[`nng_aio_wait()`]. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient free memory to perform the operation. - -== SEE ALSO - -[.text-left] -xref:nng_aio_abort.3.adoc[nng_aio_abort(3)], -xref:nng_aio_cancel.3.adoc[nng_aio_cancel(3)], -xref:nng_aio_count.3.adoc[nng_aio_count(3)], -xref:nng_aio_free.3.adoc[nng_aio_free(3)], -xref:nng_aio_get_input.3.adoc[nng_aio_get_input(3)], -xref:nng_aio_get_msg.3.adoc[nng_aio_get_msg(3)], -xref:nng_aio_get_output.3.adoc[nng_aio_get_output(3)], -xref:nng_aio_result.3.adoc[nng_aio_result(3)], -xref:nng_aio_set_input.3.adoc[nng_aio_set_input(3)], -xref:nng_aio_set_iov.3.adoc[nng_aio_set_iov(3)], -xref:nng_aio_set_msg.3.adoc[nng_aio_set_msg(3)], -xref:nng_aio_set_timeout.3.adoc[nng_aio_set_timeout(3)], -xref:nng_aio_stop.3.adoc[nng_aio_stop(3)], -xref:nng_aio_wait.3.adoc[nng_aio_wait(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_aio_begin.3.adoc b/docs/man/nng_aio_begin.3.adoc deleted file mode 100644 index 30a73648..00000000 --- a/docs/man/nng_aio_begin.3.adoc +++ /dev/null @@ -1,64 +0,0 @@ -= nng_aio_begin(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_aio_begin - begin asynchronous I/O operation - -== SYNOPSIS - -[source, c] ----- -#include - -bool nng_aio_begin(nng_aio *aio); ----- - -== DESCRIPTION - -The `nng_aio_begin()` function is called by the I/O provider to indicate that -it is going to process the operation. - -The function may return `false`, indicating that the _aio_ has been closed -by the caller asynchronously. -In this case the provider should abandon the operation and do nothing else. - -This operation should be called at the start of any I/O operation, and must -be called not more than once for a given I/O operation on a given _aio_. - -Once this function is called, if `true` is returned, then the provider MUST -guarantee that xref:nng_aio_finish.3.adoc[`nng_aio_finish()`] is called for the _aio_ -exactly once, when the operation is complete or canceled. - -NOTE: This function is only for I/O providers (those actually performing -the operation such as HTTP handler functions or transport providers); ordinary -users of the _aio_ should not call this function. - -== RETURN VALUES - -[horizontal] -`true`:: The operation has been started. -`false`:: The operation cannot be started. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], -xref:nng_aio_cancel.3.adoc[nng_aio_cancel(3)], -xref:nng_aio_defer.3.adoc[nng_aio_defer(3)], -xref:nng_aio_finish.3.adoc[nng_aio_finish(3)], -xref:nng_aio_result.3.adoc[nng_aio_result(3)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_aio_busy.3.adoc b/docs/man/nng_aio_busy.3.adoc deleted file mode 100644 index 4aaf09b5..00000000 --- a/docs/man/nng_aio_busy.3.adoc +++ /dev/null @@ -1,56 +0,0 @@ -= nng_aio_busy(3) -// -// Copyright 2022 Staysail Systems, Inc. -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_aio_busy - test if asynchronous I/O is busy - -== SYNOPSIS - -[source, c] ----- -#include - -bool nng_aio_busy(nng_aio *aio); ----- - -== DESCRIPTION - -The `nng_aio_busy()` function returns true if the -_aio_ is currently busy performing an asynchronous I/O -operation or is executing a completion callback. - -If no operation has been started, or the operation has -been completed or canceled, and any callback has been -executed, then it returns false. - -This is the same test used internally by -xref:nng_aio_wait.3.adoc[`nng_aio_wait()`] - -NOTE: Care should be taken to ensure that the _aio_ object is not -freed when using this function. The caller is responsible for -coordinating any use of this with any reuse of the _aio_. - -== RETURN VALUES - -True if the _aio_ is busy, false otherwise. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_aio_abort.3.adoc[nng_aio_abort(3)], -xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], -xref:nng_aio_wait.3.adoc[nng_aio_wait(3)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_aio_cancel.3.adoc b/docs/man/nng_aio_cancel.3.adoc deleted file mode 100644 index 3b32c827..00000000 --- a/docs/man/nng_aio_cancel.3.adoc +++ /dev/null @@ -1,58 +0,0 @@ -= nng_aio_cancel(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_aio_cancel - cancel asynchronous I/O operation - -== SYNOPSIS - -[source, c] ----- -#include - -void nng_aio_cancel(nng_aio *aio); ----- - -== DESCRIPTION - -The `nng_aio_cancel()` function aborts an operation previously started -with the handle _aio_. -If the operation is aborted, then the callback -for the handle will be called, and the function -xref:nng_aio_result.3.adoc[`nng_aio_result()`] will return the error `NNG_ECANCELED`. - -This function does not wait for the operation to be fully aborted, but -returns immediately. - -If no operation is currently in progress (either because it has already -finished, or no operation has been started yet), then this function -has no effect. - -NOTE: This function is the same as calling -xref:nng_aio_abort.3.adoc[`nng_aio_abort()`] with the error `NNG_ECANCELED`. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_aio_abort.3.adoc[nng_aio_abort(3)], -xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], -xref:nng_aio_result.3.adoc[nng_aio_result(3)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_aio_count.3.adoc b/docs/man/nng_aio_count.3.adoc deleted file mode 100644 index daf97710..00000000 --- a/docs/man/nng_aio_count.3.adoc +++ /dev/null @@ -1,61 +0,0 @@ -= nng_aio_count(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_aio_count - return number of bytes transferred - -== SYNOPSIS - -[source, c] ----- -#include - -size_t nng_aio_count(nng_aio *aio); ----- - -== DESCRIPTION - -The `nng_aio_count()` returns the number of bytes transferred by the -asynchronous operation associated with the handle _aio_. - -Some asynchronous operations do not provide meaningful data for this -function; for example operations that establish connections do not -transfer user data (they may transfer protocol data though) -- in this case -this function will generally return zero. - -This function is most useful when used with operations that make use of -of a scatter/gather vector (set by xref:nng_aio_set_iov.3.adoc[`nng_aio_set_iov()`]). - -NOTE: The return value from this function is undefined if the operation -has not completed yet. -Either call this from the handle's completion callback, -or after waiting for the operation to complete with -xref:nng_aio_wait.3.adoc[`nng_aio_wait()`]. - -== RETURN VALUES - -The number of bytes transferred by the operation. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], -xref:nng_aio_result.3.adoc[nng_aio_result(3)], -xref:nng_aio_set_iov.3.adoc[nng_aio_set_iov(3)], -xref:nng_aio_wait.3.adoc[nng_aio_wait(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_aio_defer.3.adoc b/docs/man/nng_aio_defer.3.adoc deleted file mode 100644 index 5664a6df..00000000 --- a/docs/man/nng_aio_defer.3.adoc +++ /dev/null @@ -1,78 +0,0 @@ -= nng_aio_defer(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_aio_defer - defer asynchronous I/O operation - -== SYNOPSIS - -[source, c] ----- -#include - -typedef void (*nng_aio_cancelfn)(nng_aio *aio, void *arg, int err); - -void nng_aio_defer(nng_aio *aio, nng_aio_cancelfn fn, void *arg); ----- - -== DESCRIPTION - -The `nng_aio_defer()` function marks operation associated with _aio_ as -being deferred for asynchronous completion, and also registers a cancellation -function _fn_ and associated argument _arg_, thereby -permitting the operation to be canceled. - -If the _aio_ is being canceled, the cancellation routine _fn_ will be called -with the _aio_, the _arg_ specified by `nng_aio_defer()`, and an error -value in _err_, which is the reason that the operation is being canceled. - -The operation may not be cancelable; for example it may have already been -completed, or be in a state where it is no longer possible to unschedule it. -In this case, the _cancelfn_ should just return without making any changes. - -If the cancellation routine successfully canceled the operation, it should -ensure that xref:nng_aio_finish.3.adoc[`nng_aio_finish()`] is called, with the -error code specified by _err_. - -IMPORTANT: It is mandatory that I/O providers call -xref:nng_aio_finish.3.adoc[`nng_aio_finish()`] -*EXACTLY ONCE* when they are finished with the operation. - -NOTE: This function is only for I/O providers (those actually performing -the operation such as HTTP handler functions or transport providers); ordinary -users of the _aio_ should not call this function. - -NOTE: Care must be taken to ensure that cancellation and completion of -the routine are multi-thread safe; this will usually involve the use -of locks or other synchronization primitives. - -TIP: For operations that complete synchronously, without any need to be -deferred, the provider should not bother to call `nng_aio_defer()`, -although it is harmless if it does. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], -xref:nng_aio_cancel.3.adoc[nng_aio_cancel(3)], -xref:nng_aio_finish.3.adoc[nng_aio_finish(3)], -xref:nng_aio_result.3.adoc[nng_aio_result(3)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_aio_finish.3.adoc b/docs/man/nng_aio_finish.3.adoc deleted file mode 100644 index 91ad188e..00000000 --- a/docs/man/nng_aio_finish.3.adoc +++ /dev/null @@ -1,60 +0,0 @@ -= nng_aio_finish(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_aio_finish - finish asynchronous I/O operation - -== SYNOPSIS - -[source, c] ----- -#include - -void nng_aio_finish(nng_aio *aio, int err); ----- - -== DESCRIPTION - -The `nng_aio_finish()` function marks operation associated with _aio_ as -complete, with the status _err_. -This will be the result returned by -xref:nng_aio_result.3.adoc[`nng_aio_result()`]. - -This function causes the callback associated with the _aio_ to called. - -IMPORTANT: It is mandatory that operation providers call this function -*exactly once* when they are finished with the operation. -After calling this function they *must not* perform any further accesses -to the _aio_. - -NOTE: This function is only for I/O providers (those actually performing -the operation such as HTTP handler functions or transport providers); ordinary -users of the _aio_ should not have any need for this function. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], -xref:nng_aio_begin.3.adoc[nng_aio_begin(3)], -xref:nng_aio_cancel.3.adoc[nng_aio_cancel(3)], -xref:nng_aio_defer.3.adoc[nng_aio_defer(3)], -xref:nng_aio_result.3.adoc[nng_aio_result(3)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_aio_free.3.adoc b/docs/man/nng_aio_free.3.adoc deleted file mode 100644 index c2528633..00000000 --- a/docs/man/nng_aio_free.3.adoc +++ /dev/null @@ -1,54 +0,0 @@ -= nng_aio_free(3) -// -// Copyright 2020 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_aio_free - free asynchronous I/O handle - -== SYNOPSIS - -[source, c] ----- -#include - -void nng_aio_free(nng_aio *aio); -void nng_aio_reap(nng_aio *aio); ----- - -== DESCRIPTION - -The `nng_aio_free()` function frees an allocated asynchronous I/O handle. -If any operation is in progress, the operation is canceled, and the -caller is blocked until the operation is completely canceled, to ensure -that it is safe to deallocate the handle and any associated resources. -(This is done by implicitly calling xref:nng_aio_stop.3.adoc[`nng_aio_stop()`].) - -The `nng_aio_reap()` function is the same as `nng_aio_free()`, but does -its work in a background thread. -This can be useful to discard the _aio_ object from within the callback for the _aio_. - -IMPORTANT: Once either of these functions are called, the _aio_ object is invalid and must not be used again. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], -xref:nng_aio_stop.3.adoc[nng_aio_stop(3)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_aio_get_input.3.adoc b/docs/man/nng_aio_get_input.3.adoc deleted file mode 100644 index 204ec435..00000000 --- a/docs/man/nng_aio_get_input.3.adoc +++ /dev/null @@ -1,53 +0,0 @@ -= nng_aio_get_input(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_aio_get_input - return input parameter - -== SYNOPSIS - -[source, c] ----- -#include - -void *nng_aio_get_input(nng_aio *aio, unsigned int index); ----- - -== DESCRIPTION - -The `nng_aio_get_input()` function returns the value of the input parameter -previously set at _index_ on _aio_ with the -xref:nng_aio_set_input.3.adoc[`nng_aio_set_input()`] function. - -The valid values of _index_ range from zero (0) to three (3), as no operation -currently defined can accept more than four parameters. -(This limit could increase in the future.) -If the index supplied is outside of this range, -or of the input parameter was not previously set, then `NULL` is returned. - -== RETURN VALUES - -Value previously set, or `NULL`. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], -xref:nng_aio_get_output.3.adoc[nng_aio_get_output(3)], -xref:nng_aio_set_input.3.adoc[nng_aio_set_input(3)], -xref:nng_aio_result.3.adoc[nng_aio_result(3)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_aio_get_msg.3.adoc b/docs/man/nng_aio_get_msg.3.adoc deleted file mode 100644 index c4205658..00000000 --- a/docs/man/nng_aio_get_msg.3.adoc +++ /dev/null @@ -1,49 +0,0 @@ -= nng_aio_get_msg(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_aio_get_msg - get message from asynchronous receive - -== SYNOPSIS - -[source, c] ----- -#include - -nng_msg *nng_aio_get_msg(nng_aio *aio); ----- - -== DESCRIPTION - -The `nng_aio_get_msg()` function gets any message stored in _aio_ as -either a result of a successful receive -(see xref:nng_recv_aio.3.adoc[`nng_recv_aio()`]) -or that was previously stored with xref:nng_aio_set_msg.3.adoc[`nng_aio_set_msg()`]. - -IMPORTANT: The xref:nng_aio.5.adoc[`nng_aio`] must not have an operation in progress. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_aio_set_msg.3.adoc[nng_aio_set_msg(3)], -xref:nng_recv_aio.3.adoc[nng_recv_aio(3)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng_msg.5.adoc[nng_msg(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_aio_get_output.3.adoc b/docs/man/nng_aio_get_output.3.adoc deleted file mode 100644 index 4dfd67c3..00000000 --- a/docs/man/nng_aio_get_output.3.adoc +++ /dev/null @@ -1,56 +0,0 @@ -= nng_aio_get_output(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_aio_get_output - return output result - -== SYNOPSIS - -[source, c] ----- -#include - -void *nng_aio_get_output(nng_aio *aio, unsigned int index); ----- - -== DESCRIPTION - -The `nng_aio_get_output()` function returns the output result at _index_ -resulting from the asynchronous operation associated with _aio_. - -The type and semantics of output parameters are determined by specific -operations. - -NOTE: If the _index_ does not correspond to a defined output for the operation, -or the operation did not succeed, then the return value will be `NULL`. - -IMPORTANT: It is an error to call this function while the _aio_ is currently -in use by an active asynchronous operation, or if no operation has been -performed using the _aio_ yet. - -== RETURN VALUES - -The __index__th result of the operation, or `NULL`. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], -xref:nng_aio_get_output.3.adoc[nng_aio_get_output(3)], -xref:nng_aio_set_input.3.adoc[nng_aio_set_input(3)], -xref:nng_aio_result.3.adoc[nng_aio_result(3)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_aio_result.3.adoc b/docs/man/nng_aio_result.3.adoc deleted file mode 100644 index e1886a6e..00000000 --- a/docs/man/nng_aio_result.3.adoc +++ /dev/null @@ -1,59 +0,0 @@ -= nng_aio_result(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_aio_result - return result of asynchronous operation - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_aio_result(nng_aio *aio); ----- - -== DESCRIPTION - -The `nng_aio_result()` returns the result of the operation associated -with the handle _aio_. -If the operation was successful, then 0 is returned. -Otherwise a non-zero error code is returned. - -NOTE: The return value from this function is undefined if the operation -has not completed yet. -Either call this from the handle's completion -callback, or after waiting for the operation to complete with -xref:nng_aio_wait.3.adoc[`nng_aio_wait()`]. - -== RETURN VALUES - -The result of the operation, either zero on success, or an error -number on failure. - -== ERRORS - -[horizontal] -`NNG_ETIMEDOUT`:: The operation timed out. -`NNG_ECANCELED`:: The operation was canceled. - -Various other return values are possible depending on the operation. - -== SEE ALSO - -[.text-left] -xref:nng_aio_abort.3.adoc[nng_aio_abort(3)], -xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], -xref:nng_aio_wait.3.adoc[nng_aio_wait(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_aio_set_input.3.adoc b/docs/man/nng_aio_set_input.3.adoc deleted file mode 100644 index 37cf3cdd..00000000 --- a/docs/man/nng_aio_set_input.3.adoc +++ /dev/null @@ -1,63 +0,0 @@ -= nng_aio_set_input(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_aio_set_input - set input parameter - -== SYNOPSIS - -[source, c] ----- -#include - -void nng_aio_set_input(nng_aio *aio, unsigned int index, void *param); ----- - -== DESCRIPTION - -The `nng_aio_set_input()` function sets the input parameter at _index_ -to _param_ for the asynchronous operation associated with _aio_. - -The type and semantics of input parameters are determined by specific -operations; the caller must supply appropriate inputs for the operation -to be performed. - -The valid values of _index_ range from zero (0) to three (3), as no operation -currently defined can accept more than four parameters. -(This limit could increase in the future.) - -NOTE: If the _index_ does not correspond to a defined input for the operation, -then this function will have no effect. - -IMPORTANT: It is an error to call this function while the _aio_ is currently -in use by an active asynchronous operation. - -An input parameter set with this function may be retrieved later with -the xref:nng_aio_get_input.3.adoc[`nng_aio_get_input()`] function. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], -xref:nng_aio_get_input.3.adoc[nng_aio_get_input(3)], -xref:nng_aio_get_output.3.adoc[nng_aio_get_output(3)], -xref:nng_aio_result.3.adoc[nng_aio_result(3)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_aio_set_iov.3.adoc b/docs/man/nng_aio_set_iov.3.adoc deleted file mode 100644 index 83128011..00000000 --- a/docs/man/nng_aio_set_iov.3.adoc +++ /dev/null @@ -1,67 +0,0 @@ -= nng_aio_set_iov(3) -// -// Copyright 2021 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_aio_set_iov - set scatter/gather vector - -== SYNOPSIS - -[source,c] ----- -#include - -int nng_aio_set_iov(nng_aio *aio, unsigned int niov, nng_iov *iov); ----- - -== DESCRIPTION - -The `nng_aio_set_iov()` function sets a ((scatter/gather)) vector _iov_ on the handle _aio_. - -The _iov_ is a pointer to an array of _niov_ xref:nng_iov.5.adoc[`nng_iov`] -structures, which have the following definition: - -[source,c] ----- - typedef struct nng_iov { - void * iov_buf; - size_t iov_len; - }; ----- - -The _iov_ is copied into storage in the _aio_ itself, so that callers may use stack allocated `nng_iov` structures. -The values pointed to by the `iov_buf` members are *not* copied by this function though. - -A maximum of four (4) `nng_iov` members may be supplied. - -NOTE: Earlier versions of the library could accept longer scatter-gather lists. -However, no known consumers have ever needed a scatter-gather list longer than 4 vectors. -As a result, the implementation limit was reduced, and heap allocations which could fail were removed. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_EINVAL`:: Value of specified _niov_ is too large. - -== SEE ALSO - -[.text-left] -xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], -xref:nng_aio_cancel.3.adoc[nng_aio_cancel(3)], -xref:nng_aio_count.3.adoc[nng_aio_count(3)], -xref:nng_aio_result.3.adoc[nng_aio_result(3)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng_iov.5.adoc[nng_iov(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_aio_set_msg.3.adoc b/docs/man/nng_aio_set_msg.3.adoc deleted file mode 100644 index e0ea3e46..00000000 --- a/docs/man/nng_aio_set_msg.3.adoc +++ /dev/null @@ -1,47 +0,0 @@ -= nng_aio_set_msg(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_aio_set_msg - set message for asynchronous send - -== SYNOPSIS - -[source, c] ----- -#include - -void nng_aio_set_msg(nng_aio *aio, nng_msg *msg); ----- - -== DESCRIPTION - -The `nng_aio_set_msg()` function sets the message that will be used -for an asynchronous send operation (see xref:nng_send_aio.3.adoc[`nng_send_aio()`]). - -IMPORTANT: The xref:nng_aio.5.adoc[`nng_aio`] must not have an operation in progress. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_aio_get_msg.3.adoc[nng_aio_get_msg(3)], -xref:nng_send_aio.3.adoc[nng_send_aio(3)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng_msg.5.adoc[nng_msg(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_aio_set_output.3.adoc b/docs/man/nng_aio_set_output.3.adoc deleted file mode 100644 index 67f8ac66..00000000 --- a/docs/man/nng_aio_set_output.3.adoc +++ /dev/null @@ -1,60 +0,0 @@ -= nng_aio_set_output(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_aio_set_output - set output result - -== SYNOPSIS - -[source, c] ----- -#include - -void nng_aio_set_output(nng_aio *aio, unsigned int index, void *result); ----- - -== DESCRIPTION - -The `nng_aio_set_output()` function sets the output result at _index_ -to _result_ for the asynchronous operation associated with _aio_. - -The type and semantics of output results are determined by specific -operations; the operation must supply appropriate output results when -the operation completes successfully. - -The valid values of _index_ range from zero (0) to three (3), as no operation -currently defined can return more than four results. -(This limit could increase in the future.) - -NOTE: Note that attempts to set results with an _index_ greater than -three (3) will be ignored. - -An output result set with this function may be retrieved later with -the xref:nng_aio_get_output.3.adoc[`nng_aio_get_output()`] function. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], -xref:nng_aio_finish.3.adoc[nng_aio_finish(3)], -xref:nng_aio_get_output.3.adoc[nng_aio_get_output(3)], -xref:nng_aio_result.3.adoc[nng_aio_result(3)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_aio_set_timeout.3.adoc b/docs/man/nng_aio_set_timeout.3.adoc deleted file mode 100644 index a82b0c83..00000000 --- a/docs/man/nng_aio_set_timeout.3.adoc +++ /dev/null @@ -1,74 +0,0 @@ -= nng_aio_set_timeout(3) -// -// Copyright 2023 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_aio_set_timeout - set asynchronous I/O timeout - -== SYNOPSIS - -[source, c] ----- -#include - -typedef int nng_duration; -void nng_aio_set_timeout(nng_aio *aio, nng_duration timeout); - -typedef uint64_t nng_time; -void nng_aio_set_expire(nng_aio *aio, nng_time expiration); ----- - -== DESCRIPTION - -The `nng_aio_set_timeout()` function sets a _timeout_(((timeout))) -for the asynchronous operation associated with _aio_. -This causes a timer to be started when the operation is actually started. -If the timer expires before the operation is completed, then it is -aborted with an error of `NNG_ETIMEDOUT`. -The _timeout_ is specified as a relative number of milliseconds. - -If the timeout is `NNG_DURATION_INFINITE`, then no timeout is used. -If the timeout is `NNG_DURATION_DEFAULT`, then a "default" or socket-specific -timeout is used. -(This is frequently the same as `NNG_DURATION_INFINITE`.) - -The `nng_aio_set_expire()` function is similar to `nng_aio_set_timeout()`, but sets -an absolute expiration time based on the system clock. The _expiration_ -is expressed as a number of milliseconds since some point in the past. -The xref:nng_clock.3supp.adoc[`nng_clock()`] function can be used to determine -the current value of the clock. - -TIP: As most operations involve some context switching, it is usually a good -idea to allow at least a few tens of milliseconds before timing them out -- -a too small timeout might not allow the operation to properly begin before -giving up! - -The value of _timeout_ set for the _aio_ is persistent, so that if the -handle is reused for multiple operations, they will have the same relative -timeout. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], -xref:nng_aio_cancel.3.adoc[nng_aio_cancel(3)], -xref:nng_aio_result.3.adoc[nng_aio_result(3)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng_duration.5.adoc[nng_duration(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_aio_stop.3.adoc b/docs/man/nng_aio_stop.3.adoc deleted file mode 100644 index d5037c51..00000000 --- a/docs/man/nng_aio_stop.3.adoc +++ /dev/null @@ -1,60 +0,0 @@ -= nng_aio_stop(3) -// -// Copyright 2024 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_aio_stop - stop asynchronous I/O operation - -== SYNOPSIS - -[source, c] ----- -#include - -void nng_aio_stop(nng_aio *aio); ----- - -== DESCRIPTION - -The `nng_aio_stop()` function stops the asynchronous I/O operation -associated with _aio_ by aborting with `NNG_ECANCELED`, and then waits -for it to complete or to be completely aborted, and for the -callback associated with the _aio_ to have completed executing. - -Further calls to -xref:nng_aio_begin.3.adoc[`nng_aio_begin()`] using this _aio_ will return false. - -It is safe to call this for an _aio_, even when no operation is currently -pending for it. - -TIP: When multiple asynchronous I/O handles are in use and need to be -shut down, it is safest to stop all of them, before deallocating any of -them with xref:nng_aio_free.3.adoc[`nng_aio_free()`], particularly if the callbacks -might attempt to reschedule additional operations. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], -xref:nng_aio_cancel.3.adoc[nng_aio_cancel(3)], -xref:nng_aio_free.3.adoc[nng_aio_free(3)], -xref:nng_aio_begin.3.adoc[nng_aio_begin(3)], -xref:nng_aio_wait.3.adoc[nng_aio_wait(3)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_aio_wait.3.adoc b/docs/man/nng_aio_wait.3.adoc deleted file mode 100644 index acac6fdf..00000000 --- a/docs/man/nng_aio_wait.3.adoc +++ /dev/null @@ -1,54 +0,0 @@ -= nng_aio_wait(3) -// -// Copyright 2023 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_aio_wait - wait for asynchronous I/O operation - -== SYNOPSIS - -[source, c] ----- -#include - -void nng_aio_wait(nng_aio *aio); ----- - -== DESCRIPTION - -The `nng_aio_wait()` function waits for an asynchronous I/O operation -to complete. -If the operation has not been started, or has already -completed, then it returns immediately. - -If a callback was set with _aio_ when it was allocated, then this -function will not be called until the callback has completed. - -IMPORTANT: This function should never be called from a function that itself -is a callback of an xref:nng_aio.5.adoc[`aio`], either this one or any other. -Doing so may result in a deadlock. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_aio_abort.3.adoc[nng_aio_abort(3)], -xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], -xref:nng_aio_busy.3.adoc[nng_aio_busy(3)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_alloc.3.adoc b/docs/man/nng_alloc.3.adoc deleted file mode 100644 index 93c03111..00000000 --- a/docs/man/nng_alloc.3.adoc +++ /dev/null @@ -1,56 +0,0 @@ -= nng_alloc(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_alloc - allocate memory - -== SYNOPSIS - -[source, c] ----- -#include - -void *nng_alloc(size_t size); ----- - -== DESCRIPTION - -The `nng_alloc()` function allocates a contiguous memory region of -at least _size_ bytes. -The memory will be 64-bit aligned. - -The returned memory can be used to hold message buffers, in which -case it can be directly passed to xref:nng_send.3.adoc[`nng_send()`] using -the flag `NNG_FLAG_ALLOC`. Alternatively, it can be freed when no -longer needed using xref:nng_free.3.adoc[`nng_free()`]. - -IMPORTANT: Do not use the system `free()` function to release this memory. -On some platforms this may work, but it is not guaranteed and may lead -to a crash or other undesirable and unpredictable behavior. - -== RETURN VALUES - -This function returns a pointer to the allocated memory on success, -and `NULL` otherwise. - -== ERRORS - -No errors are returned, but a `NULL` return value should be -treated the same as `NNG_ENOMEM`. - -== SEE ALSO - -[.text-left] -xref:nng_free.3.adoc[nng_free(3)], -xref:nng_send.3.adoc[nng_send(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_bus.7.adoc b/docs/man/nng_bus.7.adoc deleted file mode 100644 index 67b3d974..00000000 --- a/docs/man/nng_bus.7.adoc +++ /dev/null @@ -1,84 +0,0 @@ -= nng_bus(7) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_bus - bus protocol - -== SYNOPSIS - -[source,c] ----- -#include ----- - -== DESCRIPTION - -(((protocol, _bus_))) -The ((_bus_ protocol)) provides for building mesh networks where -every peer is connected to every other peer. -In this protocol, each message sent by a node is sent to every one of -its directly connected peers. - -TIP: Messages are only sent to directly connected peers. -This means that in the event that a peer is connected indirectly, it will not -receive messages. -When using this protocol to build mesh networks, it -is therefore important that a _fully-connected_ mesh network be constructed. - -All message delivery in this pattern is ((best-effort)), which means that -peers may not receive messages. -Furthermore, delivery may occur to some, -all, or none of the directly connected peers. -(Messages are not delivered when peer nodes are unable to receive.) -Hence, send operations will never block; instead if the -message cannot be delivered for any reason it is discarded. - -TIP: In order to minimize the likelihood of message loss, this protocol -should not be used for high throughput communications. -Furthermore, the more traffic _in aggregate_ that occurs across the topology, -the more likely that message loss is to occur. - -=== Socket Operations - -The xref:nng_bus_open.3.adoc[`nng_bus0_open()`] functions create a bus socket. -This socket may be used to send and receive messages. -Sending messages will attempt to deliver to each directly connected peer. - -=== Protocol Versions - -Only version 0 of this protocol is supported. -(At the time of writing, no other versions of this protocol have been defined.) - -=== Protocol Options - -The _bus_ protocol has no protocol-specific options. - -=== Protocol Headers - -When using a _bus_ socket in xref:nng.7.adoc#raw_mode[raw mode], received messages will -contain the incoming xref:nng_pipe.5.adoc[pipe] ID as the sole element in the header. -If a message containing such a header is sent using a raw _bus_ socket, then, -the message will be delivered to all connected pipes _except_ the one -identified in the header. -This behavior is intended for use with xref:nng_device.3.adoc[device] -configurations consisting of just a single socket. -Such configurations are useful in the creation of rebroadcasters, and this -capability prevents a message from being routed back to its source. -If no header is present, then a message is sent to all connected pipes. - -When using normal (cooked mode) _bus_ sockets, no message headers are present. - -== SEE ALSO - -[.text-left] -xref:nng_bus_open.3.adoc[nng_bus_open(3)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_bus_open.3.adoc b/docs/man/nng_bus_open.3.adoc deleted file mode 100644 index 3477a903..00000000 --- a/docs/man/nng_bus_open.3.adoc +++ /dev/null @@ -1,52 +0,0 @@ -= nng_bus_open(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_bus_open - create bus socket - -== SYNOPSIS - -[source,c] ----- -#include -#include - -int nng_bus0_open(nng_socket *s); - -int nng_bus0_open_raw(nng_socket *s); ----- - -== DESCRIPTION - -The `nng_bus0_open()` function creates a xref:nng_bus.7.adoc[_bus_] version 0 -xref:nng_socket.5.adoc[socket] and returns it at the location pointed to by _s_. - -The `nng_bus0_open_raw()` function creates a xref:nng_bus.7.adoc[_bus_] version 0 -xref:nng_socket.5.adoc[socket] in -xref:nng.7.adoc#raw_mode[raw] mode, and returns it at the location pointed to by _s_. - -== RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory is available. -`NNG_ENOTSUP`:: The protocol is not supported. - -== SEE ALSO - -[.text-left] -xref:nng_socket.5.adoc[nng_socket(5)], -xref:nng_bus.7.adoc[nng_bus(7)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_ctx_close.3.adoc b/docs/man/nng_ctx_close.3.adoc deleted file mode 100644 index cfc51bfa..00000000 --- a/docs/man/nng_ctx_close.3.adoc +++ /dev/null @@ -1,54 +0,0 @@ -= nng_ctx_close(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_ctx_close - close context - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_ctx_close(nng_ctx ctx); ----- - -== DESCRIPTION - -The `nng_ctx_close()` function closes the context _ctx_. -Messages that have been submitted for sending may be flushed or delivered, -depending upon the transport. - -Further attempts to use the context after this call returns will result -in `NNG_ECLOSED`. -Threads waiting for operations on the context when this -call is executed may also return with an `NNG_ECLOSED` result. - -NOTE: Closing the socket associated with _ctx_ -(using xref:nng_close.3.adoc[`nng_close()`]) also closes this context. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ECLOSED`:: The context _ctx_ is already closed or was never opened. - -== SEE ALSO - -[.text-left] -xref:nng_ctx_open.3.adoc[nng_ctx_open(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_ctx.5.adoc[nng_ctx(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_ctx_get.3.adoc b/docs/man/nng_ctx_get.3.adoc deleted file mode 100644 index 48237b23..00000000 --- a/docs/man/nng_ctx_get.3.adoc +++ /dev/null @@ -1,131 +0,0 @@ -= nng_ctx_get(3) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_ctx_get - get context option - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_ctx_get(nng_ctx ctx, const char *opt, void *val, size_t *valszp); - -int nng_ctx_get_bool(nng_ctx ctx, const char *opt, bool *bvalp); - -int nng_ctx_get_int(nng_ctx ctx, const char *opt, int *ivalp); - -int nng_ctx_get_ms(nng_ctx ctx, const char *opt, nng_duration *durp); - -int nng_ctx_get_size(nng_ctx ctx, const char *opt, size_t *zp); - -int nng_ctx_get_string(nng_ctx ctx, const char *opt, char **strp); - -int nng_ctx_get_uint64(nng_ctx ctx, const char *opt, uint64_t *u64p); - ----- - -== DESCRIPTION - -(((options, context))) -The `nng_ctx_get()` functions are used to retrieve option values for -the xref:nng_ctx.5.adoc[context] _ctx_. -The actual options that may be retrieved in this way vary. -A number of them are documented in xref:nng_options.5.adoc[nng_options(5)]. - -NOTE: Context options are protocol specific. -The details will be documented with the protocol. - -=== Forms - -In all of these forms, the option _opt_ is retrieved from the context _ctx_. -The forms vary based on the type of the option they take. - -The details of the type, size, and semantics of the option will depend -on the actual option, and will be documented with the option itself. - -`nng_ctx_get()`:: -This function is untyped and can be used to retrieve the value of any option. -The caller must store a pointer to a buffer to receive the value in _val_, -and the size of the buffer shall be stored at the location referenced by -_valszp_. + - + -When the function returns, the actual size of the data copied (or that -would have been copied if sufficient space were present) is stored at -the location referenced by _valszp_. -If the caller's buffer is not large enough to hold the entire object, -then the copy is truncated. -Therefore the caller should check for truncation by verifying that the -returned size in _valszp_ does not exceed the original buffer size. + - + -It is acceptable to pass `NULL` for _val_ if the value in _valszp_ is zero. -This can be used to determine the size of the buffer needed to receive -the object. - -TIP: It may be easier to use one of the typed forms of this function. - -`nng_ctx_get_bool()`:: -This function is for options which take a Boolean (`bool`). -The value will be stored at _ivalp_. - -`nng_ctx_get_int()`:: -This function is for options which take an integer (`int`). -The value will be stored at _ivalp_. - -`nng_ctx_get_ms()`:: -This function is used to retrieve time xref:nng_duration.5.adoc[durations] -(such as timeouts), stored in _durp_ as a number of milliseconds. -(The special value ((`NNG_DURATION_INFINITE`)) means an infinite amount of time, and -the special value ((`NNG_DURATION_DEFAULT`)) means a context-specific default.) - -`nng_ctx_get_size()`:: -This function is used to retrieve a size into the pointer _zp_, -typically for buffer sizes, message maximum sizes, and similar options. - -`nng_ctx_get_string()`:: -This function is used to retrieve a string into _strp_. -This string is created from the source using xref:nng_strdup.3.adoc[`nng_strdup()`] -and consequently must be freed by the caller using -xref:nng_strfree.3.adoc[`nng_strfree()`] when it is no longer needed. - -`nng_ctx_get_uint64()`:: -This function is used to retrieve a 64-bit unsigned value into the value -referenced by _u64p_. -This is typically used for options related to identifiers, network -numbers, and similar. - -== RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_EBADTYPE`:: Incorrect type for option. -`NNG_ECLOSED`:: Parameter _s_ does not refer to an open socket. -`NNG_EINVAL`:: Size of destination _val_ too small for object. -`NNG_ENOMEM`:: Insufficient memory exists. -`NNG_ENOTSUP`:: The option _opt_ is not supported. -`NNG_EWRITEONLY`:: The option _opt_ is write-only. - -== SEE ALSO - -[.text-left] -xref:nng_ctx_set.3.adoc[nng_ctx_set(3)], -xref:nng_strdup.3.adoc[nng_strdup(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_strfree.3.adoc[nng_strfree(3)], -xref:nng_duration.5.adoc[nng_duration(5)], -xref:nng_ctx.5.adoc[nng_ctx(5)], -xref:nng_options.5.adoc[nng_options(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_ctx_getopt.3.adoc b/docs/man/nng_ctx_getopt.3.adoc deleted file mode 100644 index 2214a3eb..00000000 --- a/docs/man/nng_ctx_getopt.3.adoc +++ /dev/null @@ -1,134 +0,0 @@ -= nng_ctx_getopt(3) -// -// Copyright 2020 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_ctx_getopt - get context option - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_ctx_getopt(nng_ctx ctx, const char *opt, void *val, size_t *valszp); - -int nng_ctx_getopt_bool(nng_ctx ctx, const char *opt, bool *bvalp); - -int nng_ctx_getopt_int(nng_ctx ctx, const char *opt, int *ivalp); - -int nng_ctx_getopt_ms(nng_ctx ctx, const char *opt, nng_duration *durp); - -int nng_ctx_getopt_size(nng_ctx ctx, const char *opt, size_t *zp); - -int nng_ctx_getopt_string(nng_ctx ctx, const char *opt, char **strp); - -int nng_ctx_getopt_uint64(nng_ctx ctx, const char *opt, uint64_t *u64p); - ----- - -== DESCRIPTION - -IMPORTANT: These functions are deprecated. Please see xref:nng_ctx_get.3.adoc[nng_ctx_get]. -They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`. - -(((options, context))) -The `nng_ctx_getopt()` functions are used to retrieve option values for -the xref:nng_ctx.5.adoc[context] _ctx_. -The actual options that may be retrieved in this way vary. -A number of them are documented in xref:nng_options.5.adoc[nng_options(5)]. - -NOTE: Context options are protocol specific. -The details will be documented with the protocol. - -=== Forms - -In all of these forms, the option _opt_ is retrieved from the context _ctx_. -The forms vary based on the type of the option they take. - -The details of the type, size, and semantics of the option will depend -on the actual option, and will be documented with the option itself. - -`nng_ctx_getopt()`:: -This function is untyped and can be used to retrieve the value of any option. -The caller must store a pointer to a buffer to receive the value in _val_, -and the size of the buffer shall be stored at the location referenced by -_valszp_. + - + -When the function returns, the actual size of the data copied (or that -would have been copied if sufficient space were present) is stored at -the location referenced by _valszp_. -If the caller's buffer is not large enough to hold the entire object, -then the copy is truncated. -Therefore the caller should check for truncation by verifying that the -returned size in _valszp_ does not exceed the original buffer size. + - + -It is acceptable to pass `NULL` for _val_ if the value in _valszp_ is zero. -This can be used to determine the size of the buffer needed to receive -the object. - -TIP: It may be easier to use one of the typed forms of this function. - -`nng_ctx_getopt_bool()`:: -This function is for options which take a Boolean (`bool`). -The value will be stored at _ivalp_. - -`nng_ctx_getopt_int()`:: -This function is for options which take an integer (`int`). -The value will be stored at _ivalp_. - -`nng_ctx_getopt_ms()`:: -This function is used to retrieve time xref:nng_duration.5.adoc[durations] -(such as timeouts), stored in _durp_ as a number of milliseconds. -(The special value ((`NNG_DURATION_INFINITE`)) means an infinite amount of time, and -the special value ((`NNG_DURATION_DEFAULT`)) means a context-specific default.) - -`nng_ctx_getopt_size()`:: -This function is used to retrieve a size into the pointer _zp_, -typically for buffer sizes, message maximum sizes, and similar options. - -`nng_ctx_getopt_string()`:: -This function is used to retrieve a string into _strp_. -This string is created from the source using xref:nng_strdup.3.adoc[`nng_strdup()`] -and consequently must be freed by the caller using -xref:nng_strfree.3.adoc[`nng_strfree()`] when it is no longer needed. - -`nng_ctx_getopt_uint64()`:: -This function is used to retrieve a 64-bit unsigned value into the value -referenced by _u64p_. -This is typically used for options related to identifiers, network -numbers, and similar. - -== RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_EBADTYPE`:: Incorrect type for option. -`NNG_ECLOSED`:: Parameter _s_ does not refer to an open socket. -`NNG_EINVAL`:: Size of destination _val_ too small for object. -`NNG_ENOMEM`:: Insufficient memory exists. -`NNG_ENOTSUP`:: The option _opt_ is not supported. -`NNG_EWRITEONLY`:: The option _opt_ is write-only. - -== SEE ALSO - -[.text-left] -xref:nng_ctx_setopt.3.adoc[nng_ctx_setopt(3)], -xref:nng_strdup.3.adoc[nng_strdup(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_strfree.3.adoc[nng_strfree(3)], -xref:nng_duration.5.adoc[nng_duration(5)], -xref:nng_ctx.5.adoc[nng_ctx(5)], -xref:nng_options.5.adoc[nng_options(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_ctx_id.3.adoc b/docs/man/nng_ctx_id.3.adoc deleted file mode 100644 index 51b833a8..00000000 --- a/docs/man/nng_ctx_id.3.adoc +++ /dev/null @@ -1,51 +0,0 @@ -= nng_ctx_id(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_ctx_id - return numeric context identifier - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_ctx_id(nng_ctx c); ----- - -== DESCRIPTION - -The `nng_ctx_id()` function returns a positive identifier for the context _c_, -if it is valid. -Otherwise it returns `-1`. - -NOTE: A context is considered valid if it was ever opened with -xref:nng_ctx_open.3.adoc[`nng_ctx_open()`] function. -Contexts that are allocated on the stack or statically should be -initialized with the macro -xref:nng_ctx.5.adoc#NNG_CTX_INITIALIZER[`NNG_CTX_INITIALIZER`] to ensure that -they cannot be confused with a valid context before they are opened. - -== RETURN VALUES - -This function returns the positive value for the context identifier, or -`-1` if the context is invalid. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_ctx.5.adoc[nng_ctx(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_ctx_open.3.adoc b/docs/man/nng_ctx_open.3.adoc deleted file mode 100644 index 76842b7e..00000000 --- a/docs/man/nng_ctx_open.3.adoc +++ /dev/null @@ -1,71 +0,0 @@ -= nng_ctx_open(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_ctx_open - create context - -== SYNOPSIS - -[source,c] ----- -#include - -int nng_ctx_open(nng_ctx *ctxp, nng_socket s); ----- - -== DESCRIPTION - -The `nng_ctx_open()` function creates a separate ((context)) to be used with -the socket _s_, -and returns it at the location pointed by _ctxp_. - -NOTE: Not every protocol supports creation of separate contexts. - -Contexts allow the independent and concurrent use of stateful operations -using the same socket. -For example, two different contexts created on a xref:nng_rep.7.adoc[_rep_] -socket can each receive requests, and send replies to them, without any -regard to or interference with each other. - -(((raw mode))) -TIP: Using contexts is an excellent way to write simpler concurrent -applications, while retaining the benefits of the protocol-specific -advanced processing, avoiding the need to bypass that with -xref:nng.7.adoc#raw_mode[raw mode] sockets. - -NOTE: Use of contexts with xref:nng.7.adoc#raw_mode[raw mode] sockets is -nonsensical, and not supported. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory is available. -`NNG_ENOTSUP`:: The protocol does not support separate contexts, or the socket was opened in raw mode. - -== SEE ALSO - -[.text-left] -xref:nng_ctx_close.3.adoc[nng_ctx_close(3)], -xref:nng_ctx_getopt.3.adoc[nng_ctx_getopt(3)], -xref:nng_ctx_recv.3.adoc[nng_ctx_recv(3)], -xref:nng_ctx_send.3.adoc[nng_ctx_send(3)], -xref:nng_ctx_setopt.3.adoc[nng_ctx_setopt(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_ctx.5.adoc[nng_ctx(5)], -xref:nng_socket.5.adoc[nng_socket(5)], -xref:nng_rep.7.adoc[nng_rep(7)], -xref:nng_req.7.adoc[nng_req(7)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_ctx_recv.3.adoc b/docs/man/nng_ctx_recv.3.adoc deleted file mode 100644 index bb3d7cf6..00000000 --- a/docs/man/nng_ctx_recv.3.adoc +++ /dev/null @@ -1,74 +0,0 @@ -= nng_ctx_recv(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_ctx_recv - receive message using context asynchronously - -== SYNOPSIS - -[source, c] ----- -#include - -void nng_ctx_recv(nng_ctx ctx, nng_aio *aio); ----- - -== DESCRIPTION - -The `nng_ctx_recv()` receives a xref:nng_msg.5.adoc[message] using the -xref:nng_ctx.5.adoc[context] _s_ asynchronously. - -When a message is successfully received by the context, it is -stored in the _aio_ by an internal call equivalent to -xref:nng_aio_set_msg.3.adoc[`nng_aio_set_msg()`], then the completion -callback on the _aio_ is executed. -In this case, xref:nng_aio_result.3.adoc[`nng_aio_result()`] will -return zero. -The callback function is responsible for retrieving the message -and disposing of it appropriately. - -IMPORTANT: Failing to accept and dispose of messages in this -case can lead to memory leaks. - -If for some reason the asynchronous receive cannot be completed -successfully (including by being canceled or timing out), then -the callback will still be executed, -but xref:nng_aio_result.3.adoc[`nng_aio_result()`] will be non-zero. - -NOTE: The semantics of what receiving a message means varies from protocol to -protocol, so examination of the protocol documentation is encouraged. - -== RETURN VALUES - -None. (The operation completes asynchronously.) - -== ERRORS - -[horizontal] -`NNG_ECANCELED`:: The operation was aborted. -`NNG_ECLOSED`:: The context _ctx_ is not open. -`NNG_ENOMEM`:: Insufficient memory is available. -`NNG_ENOTSUP`:: The protocol for context _ctx_ does not support receiving. -`NNG_ESTATE`:: The context _ctx_ cannot receive data in this state. -`NNG_ETIMEDOUT`:: The receive timeout expired. - -== SEE ALSO - -[.text-left] -xref:nng_aio_get_msg.3.adoc[nng_aio_get_msg(3)], -xref:nng_aio_set_msg.3.adoc[nng_aio_set_msg(3)], -xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng_ctx.5.adoc[nng_ctx(5)], -xref:nng_msg.5.adoc[nng_msg(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_ctx_recvmsg.3.adoc b/docs/man/nng_ctx_recvmsg.3.adoc deleted file mode 100644 index 9651c34c..00000000 --- a/docs/man/nng_ctx_recvmsg.3.adoc +++ /dev/null @@ -1,63 +0,0 @@ -= nng_ctx_recvmsg(3) -// -// Copyright 2021 Staysail Systems, Inc. -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_ctx_recvmsg - receive message using socket - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_ctx_recvmsg(nng_ctx ctx, nng_msg **msgp, int flags); ----- - -== DESCRIPTION - -The `nng_ctx_recvmsg()` receives a message on context _ctx_, storing the -received message at the location pointed to by _msgp_. - -The _flags_ may contain the following value: - -`NNG_FLAG_NONBLOCK`:: - The function returns immediately, even if no message is available. - Without this flag, the function will wait until a message is receivable - on the context _ctx_, or any configured timer expires. - -NOTE: The semantics of what receiving a message means vary from protocol to -protocol, so examination of the protocol documentation is encouraged. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_EAGAIN`:: The operation would block, but `NNG_FLAG_NONBLOCK` was specified. -`NNG_ECLOSED`:: The context or socket is not open. -`NNG_EINVAL`:: An invalid set of _flags_ was specified. -`NNG_ENOMEM`:: Insufficient memory is available. -`NNG_ENOTSUP`:: The protocol does not support receiving. -`NNG_ESTATE`:: The context cannot receive data in this state. -`NNG_ETIMEDOUT`:: The operation timed out. - -== SEE ALSO - -[.text-left] -xref:nng_msg_free.3.adoc[nng_msg_free(3)], -xref:nng_ctx_open.3.adoc[nng_ctx_open(3)], -xref:nng_ctx_recv.3.adoc[nng_ctx_recv(3)], -xref:nng_ctx_sendmsg.3.adoc[nng_ctx_sendmsg(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_ctx.5.adoc[nng_ctx(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_ctx_send.3.adoc b/docs/man/nng_ctx_send.3.adoc deleted file mode 100644 index 8724c1aa..00000000 --- a/docs/man/nng_ctx_send.3.adoc +++ /dev/null @@ -1,88 +0,0 @@ -= nng_ctx_send(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_ctx_send - send message using context asynchronously - -== SYNOPSIS - -[source, c] ----- -#include - -void nng_ctx_send(nng_ctx ctx, nng_aio *aio); ----- - -== DESCRIPTION - -The `nng_ctx_send()` sends a xref:nng_msg.5.adoc[message] using the -xref:nng_ctx.5.adoc[context] _ctx_ asynchronously. - -The message to send must have previously been set on the _aio_ -using the xref:nng_aio_set_msg.3.adoc[`nng_aio_set_msg()`] function. -The function assumes ownership of the message. - -If the message was successfully queued for delivery to the socket, -then the _aio_ will be completed, and xref:nng_aio_result.3.adoc[`nng_aio_result()`] -will return zero. -In this case the socket will dispose of the message when it is finished with it. - -NOTE: The operation will be completed, and the callback associated -with the _aio_ executed, as soon as the socket accepts the message -for sending. -This does _not_ indicate that the message was actually delivered, as it -may still be buffered in the sending socket, buffered in the receiving -socket, or in flight over physical media. - -If the operation fails for any reason (including cancellation or timeout), -then the _aio_ callback will be executed and -xref:nng_aio_result.3.adoc[`nng_aio_result()`] will return a non-zero error status. -In this case, the callback has a responsibility to retrieve the message from -the _aio_ with xref:nng_aio_get_msg.3.adoc[`nng_aio_get_msg()`] and dispose of -it appropriately. -(This may include retrying the send operation on the same or a different -socket, or deallocating the message with xref:nng_msg_free.3.adoc[`nng_msg_free()`].) - -NOTE: The semantics of what sending a message means varies from protocol to -protocol, so examination of the protocol documentation is encouraged. - -TIP: Context send operations are asynchronous. -If a synchronous operation is needed, one can be constructed by using a -`NULL` callback on the _aio_ and then waiting for the operation using -xref:nng_aio_wait.3.adoc[`nng_aio_wait()`]. - -== RETURN VALUES - -None. (The operation completes asynchronously.) - -== ERRORS - -[horizontal] -`NNG_ECANCELED`:: The operation was aborted. -`NNG_ECLOSED`:: The context _ctx_ is not open. -`NNG_EMSGSIZE`:: The message is too large. -`NNG_ENOMEM`:: Insufficient memory is available. -`NNG_ENOTSUP`:: The protocol for context _ctx_ does not support sending. -`NNG_ESTATE`:: The context _ctx_ cannot send data in this state. -`NNG_ETIMEDOUT`:: The send timeout expired. - -== SEE ALSO - -[.text-left] -xref:nng_aio_get_msg.3.adoc[nng_aio_get_msg(3)], -xref:nng_aio_set_msg.3.adoc[nng_aio_set_msg(3)], -xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng_ctx.5.adoc[nng_ctx(5)], -xref:nng_msg.5.adoc[nng_msg(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_ctx_sendmsg.3.adoc b/docs/man/nng_ctx_sendmsg.3.adoc deleted file mode 100644 index 8e2c97f4..00000000 --- a/docs/man/nng_ctx_sendmsg.3.adoc +++ /dev/null @@ -1,84 +0,0 @@ -= nng_ctx_sendmsg(3) -// -// Copyright 2021 Staysail Systems, Inc. -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_ctx_sendmsg - send message using context - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_ctx_sendmsg(nng_ctx c, nng_msg *msg, int flags); ----- - -== DESCRIPTION - -The `nng_ctx_sendmsg()` sends message _msg_ using the context _ctx_. - -If the function returns zero, indicating it has accepted the message for -delivery, then the _msg_ is owned by the socket _s_, and the caller -must not make any further use of it. -The socket will free the message when it is finished. - -If the function returns non-zero, then it is the caller's responsibility -to dispose of the _msg_, which may include freeing it, sending it to -another socket, or simply trying again later. - -NOTE: The semantics of what sending a message means vary from protocol to -protocol, so examination of the protocol documentation is encouraged. - -The _flags_ may contain the following value: - -`NNG_FLAG_NONBLOCK`:: - The function returns immediately, regardless of whether - the context is able to accept the data or not. - If the context is unable to accept the data (such as if backpressure exists - because the peers are consuming messages too slowly, or no peer is present), - then the function will return with `NNG_EAGAIN`. - If this flag is not specified, then the function will block if such a - condition exists. - - -NOTE: Regardless of the presence or absence of `NNG_FLAG_NONBLOCK`, there may -be queues between the sender and the receiver. -Furthermore, there is no guarantee that the message has actually been delivered. -Finally, with some protocols, the semantic is implicitly `NNG_FLAG_NONBLOCK`. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_EAGAIN`:: The operation would block, but `NNG_FLAG_NONBLOCK` was specified. -`NNG_ECLOSED`:: The context or socket is not open. -`NNG_EINVAL`:: An invalid set of _flags_ was specified. -`NNG_EMSGSIZE`:: The value of _size_ is too large. -`NNG_ENOMEM`:: Insufficient memory is available. -`NNG_ENOTSUP`:: The protocol does not support sending. -`NNG_ESTATE`:: The context cannot send data in this state. -`NNG_ETIMEDOUT`:: The operation timed out. - -== SEE ALSO - -[.text-left] -xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], -xref:nng_ctx_open.3.adoc[nng_ctx_open(3)], -xref:nng_ctx_recvmsg.3.adoc[nng_ctx_recvmsg(3)], -xref:nng_ctx_send.3.adoc[nng_ctx_send(3)], -xref:nng_sendmsg.3.adoc[nng_sendmsg(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_msg.5.adoc[nng_msg(5)], -xref:nng_ctx.5.adoc[nng_ctx(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_ctx_set.3.adoc b/docs/man/nng_ctx_set.3.adoc deleted file mode 100644 index 9bfeb43f..00000000 --- a/docs/man/nng_ctx_set.3.adoc +++ /dev/null @@ -1,113 +0,0 @@ -= nng_ctx_set(3) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_ctx_set - set context option - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_ctx_set(nng_ctx ctx, const char *opt, const void *val, size_t valsz); - -int nng_ctx_set_bool(nng_ctx ctx, const char *opt, int bval); - -int nng_ctx_set_int(nng_ctx ctx, const char *opt, int ival); - -int nng_ctx_set_ms(nng_ctx ctx, const char *opt, nng_duration dur); - -int nng_ctx_set_size(nng_ctx ctx, const char *opt, size_t z); - -int nng_ctx_set_string(nng_ctx ctx, const char *opt, const char *str); - -int nng_ctx_set_uint64(nng_ctx ctx, const char *opt, uint64_t u64); ----- - -== DESCRIPTION - -NOTE: These functions are deprecated. Please see xref:nng_ctx_set.3.adoc[nng_ctx_set]. - -(((options, context))) -The `nng_ctx_set()` functions are used to configure options for -the context _ctx_. -The actual options that may be configured in this way vary, and are -specified by _opt_. - -NOTE: Context options are protocol specific. -The details will be documented with the protocol. - -=== Forms - -The details of the type, size, and semantics of the option will depend -on the actual option, and will be documented with the option itself. - -`nng_ctx_set()`:: -This function is untyped, and can be used to configure any arbitrary data. -The _val_ pointer addresses the data to copy, and _valsz_ is the -size of the objected located at _val_. - -TIP: It may be easier to use one of the typed forms of this function. - -`nng_ctx_set_bool()`:: -This function is for options which take a Boolean (`bool`). -The _bval_ is passed to the option. - -`nng_ctx_set_int()`:: -This function is for options which take an integer (`int`). -The _ival_ is passed to the option. - -`nng_ctx_set_ms()`:: -This function is used to configure time durations (such as timeouts) using -type xref:nng_duration.5.adoc[`nng_duration`]. -The duration _dur_ is an integer number of milliseconds. - -`nng_ctx_set_size()`:: -This function is used to configure a size, _z_, typically for buffer sizes, -message maximum sizes, and similar options. - -`nng_ctx_set_string()`:: -This function is used to pass configure a string, _str_. -Strings passed this way must be legal UTF-8 or ASCII strings, terminated -with a `NUL` (`\0`) byte. -(Other constraints may apply as well, see the documentation for each option -for details.) - -`nng_ctx_set_uint64()`:: -This function is used to configure a 64-bit unsigned value, _u64_. -This is typically used for options related to identifiers, network numbers, -and similar. - -== RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ECLOSED`:: Parameter _s_ does not refer to an open socket. -`NNG_EINVAL`:: The value being passed is invalid. -`NNG_ENOTSUP`:: The option _opt_ is not supported. -`NNG_EREADONLY`:: The option _opt_ is read-only. -`NNG_ESTATE`:: The socket is in an inappropriate state for setting this option. - -== SEE ALSO - -[.text-left] -xref:nng_ctx_get.3.adoc[nng_ctx_get(3)], -xref:nng_socket_set.3.adoc[nng_socket_set(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_ctx.5.adoc[nng_ctx(5)], -xref:nng_options.5.adoc[nng_options(5)], -xref:nng_socket.5.adoc[nng_socket(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_ctx_setopt.3.adoc b/docs/man/nng_ctx_setopt.3.adoc deleted file mode 100644 index f6f7f9ef..00000000 --- a/docs/man/nng_ctx_setopt.3.adoc +++ /dev/null @@ -1,114 +0,0 @@ -= nng_ctx_setopt(3) -// -// Copyright 2020 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_ctx_setopt - set context option - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_ctx_setopt(nng_ctx ctx, const char *opt, const void *val, size_t valsz); - -int nng_ctx_setopt_bool(nng_ctx ctx, const char *opt, int bval); - -int nng_ctx_setopt_int(nng_ctx ctx, const char *opt, int ival); - -int nng_ctx_setopt_ms(nng_ctx ctx, const char *opt, nng_duration dur); - -int nng_ctx_setopt_size(nng_ctx ctx, const char *opt, size_t z); - -int nng_ctx_setopt_string(nng_ctx ctx, const char *opt, const char *str); - -int nng_ctx_setopt_uint64(nng_ctx ctx, const char *opt, uint64_t u64); ----- - -== DESCRIPTION - -IMPORTANT: These functions are deprecated. Please see xref:nng_ctx_set.3.adoc[nng_ctx_set]. -They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`. - -(((options, context))) -The `nng_ctx_setopt()` functions are used to configure options for -the context _ctx_. -The actual options that may be configured in this way vary, and are -specified by _opt_. - -NOTE: Context options are protocol specific. -The details will be documented with the protocol. - -=== Forms - -The details of the type, size, and semantics of the option will depend -on the actual option, and will be documented with the option itself. - -`nng_ctx_setopt()`:: -This function is untyped, and can be used to configure any arbitrary data. -The _val_ pointer addresses the data to copy, and _valsz_ is the -size of the objected located at _val_. - -TIP: It may be easier to use one of the typed forms of this function. - -`nng_ctx_setopt_bool()`:: -This function is for options which take a Boolean (`bool`). -The _bval_ is passed to the option. - -`nng_ctx_setopt_int()`:: -This function is for options which take an integer (`int`). -The _ival_ is passed to the option. - -`nng_ctx_setopt_ms()`:: -This function is used to configure time durations (such as timeouts) using -type xref:nng_duration.5.adoc[`nng_duration`]. -The duration _dur_ is an integer number of milliseconds. - -`nng_ctx_setopt_size()`:: -This function is used to configure a size, _z_, typically for buffer sizes, -message maximum sizes, and similar options. - -`nng_ctx_setopt_string()`:: -This function is used to pass configure a string, _str_. -Strings passed this way must be legal UTF-8 or ASCII strings, terminated -with a `NUL` (`\0`) byte. -(Other constraints may apply as well, see the documentation for each option -for details.) - -`nng_ctx_setopt_uint64()`:: -This function is used to configure a 64-bit unsigned value, _u64_. -This is typically used for options related to identifiers, network numbers, -and similar. - -== RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ECLOSED`:: Parameter _s_ does not refer to an open socket. -`NNG_EINVAL`:: The value being passed is invalid. -`NNG_ENOTSUP`:: The option _opt_ is not supported. -`NNG_EREADONLY`:: The option _opt_ is read-only. -`NNG_ESTATE`:: The socket is in an inappropriate state for setting this option. - -== SEE ALSO - -[.text-left] -xref:nng_ctx_getopt.3.adoc[nng_ctx_getopt(3)], -xref:nng_setopt.3.adoc[nng_setopt(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_ctx.5.adoc[nng_ctx(5)], -xref:nng_options.5.adoc[nng_options(5)], -xref:nng_socket.5.adoc[nng_socket(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/SUMMARY.md b/docs/reference/src/SUMMARY.md index 867007d2..c605fa3b 100644 --- a/docs/reference/src/SUMMARY.md +++ b/docs/reference/src/SUMMARY.md @@ -74,6 +74,6 @@ - [nng_bus_open](api/nng_bus_open.md) - [nng_close](api/nng_close.md) - - [Legacy Compatibility](api/compat.md) + - [Legacy Compatibility](api/compat/index.md) - [Index](./indexing.md) diff --git a/docs/reference/src/api/compat.md b/docs/reference/src/api/compat.md deleted file mode 100644 index 4ff75b3e..00000000 --- a/docs/reference/src/api/compat.md +++ /dev/null @@ -1,120 +0,0 @@ -# Legacy Compatibility Functions - -{{hi:compatibility layer}} -_NNG_ provides source-level compatibility for most _libnanomsg_ 1.0 applications. - -This is intended to facilitate converting {{i:legacy applications}} to use _NNG_. -New applications should use the newer _NNG_ APIs instead. - -Applications making use of this must take care -to link with _libnng_ instead of _libnn_. - -> [!TIP] -> While not recommended for long term use, the value returned by -> [`nng_socket_id()`](nng_socket_id.md) can be used with these functions -> just like a value returned by [`nn_socket()`](nn_socket.md). -> This can be way to facilitate incremental transition to the new API. - -Some capabilities, protocols, and transports, will not be accessible -using this API, as the compatible API has no provision for expression -of certain concepts introduced in the new API. - -While reasonable efforts have been made to provide for compatibility, -some things may behave differently, and some less common parts of the -_libnanomsg_ 1.0 API are not supported at this time, including certain -options and the statistics API. -See the [Caveats](#caveats) section below. - -### Availability - -The availability of this legacy API depends on whether the library was -configured to include it. - -> [!NOTE] -> Future versions of _NNG_ may not include this compatibility layer -> by default, or even at all. Modernizing applications to use the new -> API is strongly recommended. - -### Compiling - -When compiling legacy _nanomsg_ applications, it will generally be -necessary to change the include search path to add the `compat` subdirectory -of the directory where headers were installed. -For example, if _NNG_ is installed in `$prefix`, then header files will -normally be located in `$prefix/include/nng`. -In this case, to build legacy _nanomsg_ apps against _NNG_ you would -add `$prefix/include/nng/compat` to your compiler's search path. - -Alternatively, you can change your source code so that `#include` statements -referring to `` instead refer to ``. -For example, instead of: - -```c -#include -#include -``` - -you would have this: - -```c -#include -#include -``` - -Legacy applications built using these methods should be linked against _libnng_ -instead of _libnn_, just like any other _NNG_ application. - -### Caveats - -The following caveats apply when using the legacy API with _NNG_. - -- Socket numbers can be quite large. - The legacy _libnanomsg_ attempted to reuse socket numbers, like - file descriptors in UNIX systems. - _NNG_ avoids this to prevent accidental reuse or - collision after a descriptor is closed. - Consequently, socket numbers can become quite large, and should - probably not be used for array indices. - -- The following options (`nn_getsockopt`) are unsupported: - `NN_SNDPRIO`, `NN_RCVPRIO`, `NN_IPV4ONLY`. - -- Access to statistics using this legacy API - [`nn_get_statistic()`](nn_get_statistic.md) is unsupported. - -- Some transports can support longer URLs than legacy _libnanomsg_ can. - It is a good idea to use short pathnames in URLs if interoperability - is a concern. - -- Only absolute paths are supported in `ipc://` URLs. - For example, `ipc:///tmp/mysocket` is acceptable, but `ipc://mysocket` is not. - -- The WebSocket transport in this implementation (`ws://` URLs) - only supports `BINARY` frames. - -- Some newer transports are unusable from this mode. - In particular, this legacy API offers no way to configure - TLS or ZeroTier parameters that may be required for use. - -- ABI versioning of the compatibility layer is not supported, - and the `NN_VERSION_` macros are not present. - -- Runtime symbol information is not implemented. - Specifically, there is no `nn_symbol()` function. - -- The TCP transport (`tcp://` URLs) does not support specifying the local - address or interface when binding. (This could be fixed in the future, - but most likely this will be available only using the new API.) - -- The values of `NN_RCVMAXSIZE` are constrained. - Specifically, values set larger than 2GB using the new API will be reported - as unlimited (`-1`) in the new API, and the value `0` will disable any - enforcement, just like `-1`. - (There is no practical reason to ever want to limit the receive size to - zero.) - -- This implementation counts buffers in terms of messages rather than bytes. - As a result, the buffer sizes accessed with `NN_SNDBUF` and `NN_RCVBUF` are - rounded up to a whole number of kilobytes, then divided by 1024, in order - to approximate buffering assuming 1 KB messages. - Few applications should need to adjust the default values. diff --git a/docs/reference/src/api/compat/index.md b/docs/reference/src/api/compat/index.md new file mode 100644 index 00000000..4ff75b3e --- /dev/null +++ b/docs/reference/src/api/compat/index.md @@ -0,0 +1,120 @@ +# Legacy Compatibility Functions + +{{hi:compatibility layer}} +_NNG_ provides source-level compatibility for most _libnanomsg_ 1.0 applications. + +This is intended to facilitate converting {{i:legacy applications}} to use _NNG_. +New applications should use the newer _NNG_ APIs instead. + +Applications making use of this must take care +to link with _libnng_ instead of _libnn_. + +> [!TIP] +> While not recommended for long term use, the value returned by +> [`nng_socket_id()`](nng_socket_id.md) can be used with these functions +> just like a value returned by [`nn_socket()`](nn_socket.md). +> This can be way to facilitate incremental transition to the new API. + +Some capabilities, protocols, and transports, will not be accessible +using this API, as the compatible API has no provision for expression +of certain concepts introduced in the new API. + +While reasonable efforts have been made to provide for compatibility, +some things may behave differently, and some less common parts of the +_libnanomsg_ 1.0 API are not supported at this time, including certain +options and the statistics API. +See the [Caveats](#caveats) section below. + +### Availability + +The availability of this legacy API depends on whether the library was +configured to include it. + +> [!NOTE] +> Future versions of _NNG_ may not include this compatibility layer +> by default, or even at all. Modernizing applications to use the new +> API is strongly recommended. + +### Compiling + +When compiling legacy _nanomsg_ applications, it will generally be +necessary to change the include search path to add the `compat` subdirectory +of the directory where headers were installed. +For example, if _NNG_ is installed in `$prefix`, then header files will +normally be located in `$prefix/include/nng`. +In this case, to build legacy _nanomsg_ apps against _NNG_ you would +add `$prefix/include/nng/compat` to your compiler's search path. + +Alternatively, you can change your source code so that `#include` statements +referring to `` instead refer to ``. +For example, instead of: + +```c +#include +#include +``` + +you would have this: + +```c +#include +#include +``` + +Legacy applications built using these methods should be linked against _libnng_ +instead of _libnn_, just like any other _NNG_ application. + +### Caveats + +The following caveats apply when using the legacy API with _NNG_. + +- Socket numbers can be quite large. + The legacy _libnanomsg_ attempted to reuse socket numbers, like + file descriptors in UNIX systems. + _NNG_ avoids this to prevent accidental reuse or + collision after a descriptor is closed. + Consequently, socket numbers can become quite large, and should + probably not be used for array indices. + +- The following options (`nn_getsockopt`) are unsupported: + `NN_SNDPRIO`, `NN_RCVPRIO`, `NN_IPV4ONLY`. + +- Access to statistics using this legacy API + [`nn_get_statistic()`](nn_get_statistic.md) is unsupported. + +- Some transports can support longer URLs than legacy _libnanomsg_ can. + It is a good idea to use short pathnames in URLs if interoperability + is a concern. + +- Only absolute paths are supported in `ipc://` URLs. + For example, `ipc:///tmp/mysocket` is acceptable, but `ipc://mysocket` is not. + +- The WebSocket transport in this implementation (`ws://` URLs) + only supports `BINARY` frames. + +- Some newer transports are unusable from this mode. + In particular, this legacy API offers no way to configure + TLS or ZeroTier parameters that may be required for use. + +- ABI versioning of the compatibility layer is not supported, + and the `NN_VERSION_` macros are not present. + +- Runtime symbol information is not implemented. + Specifically, there is no `nn_symbol()` function. + +- The TCP transport (`tcp://` URLs) does not support specifying the local + address or interface when binding. (This could be fixed in the future, + but most likely this will be available only using the new API.) + +- The values of `NN_RCVMAXSIZE` are constrained. + Specifically, values set larger than 2GB using the new API will be reported + as unlimited (`-1`) in the new API, and the value `0` will disable any + enforcement, just like `-1`. + (There is no practical reason to ever want to limit the receive size to + zero.) + +- This implementation counts buffers in terms of messages rather than bytes. + As a result, the buffer sizes accessed with `NN_SNDBUF` and `NN_RCVBUF` are + rounded up to a whole number of kilobytes, then divided by 1024, in order + to approximate buffering assuming 1 KB messages. + Few applications should need to adjust the default values. -- cgit v1.2.3-70-g09d2