From 90b02493491e7ea6f962081efde4e29a1fd794c4 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Tue, 26 Mar 2024 07:55:58 -0700 Subject: More updates. --- docs/reference/src/SUMMARY.md | 41 ++++-- docs/reference/src/api/aio/index.md | 32 ++--- docs/reference/src/api/aio/nng_aio_abort.md | 8 +- docs/reference/src/api/aio/nng_aio_alloc.md | 30 ++-- docs/reference/src/api/aio/nng_aio_busy.md | 8 +- docs/reference/src/api/aio/nng_aio_cancel.md | 8 +- docs/reference/src/api/aio/nng_aio_count.md | 10 +- docs/reference/src/api/aio/nng_aio_free.md | 6 +- docs/reference/src/api/aio/nng_aio_get_msg.md | 8 +- docs/reference/src/api/aio/nng_aio_get_output.md | 10 +- docs/reference/src/api/aio/nng_aio_result.md | 10 +- docs/reference/src/api/aio/nng_aio_set_input.md | 6 +- docs/reference/src/api/aio/nng_aio_set_msg.md | 6 +- docs/reference/src/api/aio/nng_aio_set_timeout.md | 8 +- docs/reference/src/api/aio/nng_aio_stop.md | 10 +- docs/reference/src/api/aio/nng_aio_wait.md | 6 +- docs/reference/src/api/aio_provider/index.md | 10 +- .../src/api/aio_provider/nng_aio_begin.md | 8 +- .../src/api/aio_provider/nng_aio_defer.md | 8 +- .../src/api/aio_provider/nng_aio_finish.md | 10 +- .../src/api/aio_provider/nng_aio_get_input.md | 10 +- .../src/api/aio_provider/nng_aio_set_output.md | 4 +- docs/reference/src/api/context/index.md | 160 +++++++++++++++++++++ docs/reference/src/api/context/nng_ctx_close.md | 41 ++++++ docs/reference/src/api/context/nng_ctx_get.md | 112 +++++++++++++++ docs/reference/src/api/context/nng_ctx_getopt.md | 116 +++++++++++++++ docs/reference/src/api/context/nng_ctx_id.md | 31 ++++ docs/reference/src/api/context/nng_ctx_open.md | 56 ++++++++ docs/reference/src/api/context/nng_ctx_recv.md | 56 ++++++++ docs/reference/src/api/context/nng_ctx_recvmsg.md | 50 +++++++ docs/reference/src/api/context/nng_ctx_send.md | 68 +++++++++ docs/reference/src/api/context/nng_ctx_sendmsg.md | 67 +++++++++ docs/reference/src/api/context/nng_ctx_set.md | 94 ++++++++++++ docs/reference/src/api/context/nng_ctx_setopt.md | 98 +++++++++++++ docs/reference/src/api/index.md | 4 +- docs/reference/src/api/msg/index.md | 96 +++++++++++++ docs/reference/src/api/msg/nng_msg_alloc.md | 40 ++++++ docs/reference/src/api/msg/nng_msg_append.md | 46 ++++++ docs/reference/src/api/msg/nng_msg_body.md | 47 ++++++ docs/reference/src/api/msg/nng_msg_capacity.md | 30 ++++ docs/reference/src/api/msg/nng_msg_chop.md | 47 ++++++ docs/reference/src/api/msg/nng_msg_clear.md | 23 +++ docs/reference/src/api/msg/nng_msg_dup.md | 34 +++++ docs/reference/src/api/msg/nng_msg_free.md | 22 +++ docs/reference/src/api/msg/nng_msg_get_pipe.3.adoc | 60 ++++++++ docs/reference/src/api/msg/nng_msg_header.3.adoc | 58 ++++++++ .../src/api/msg/nng_msg_header_append.3.adoc | 58 ++++++++ .../src/api/msg/nng_msg_header_chop.3.adoc | 58 ++++++++ .../src/api/msg/nng_msg_header_clear.3.adoc | 42 ++++++ .../src/api/msg/nng_msg_header_insert.3.adoc | 60 ++++++++ .../src/api/msg/nng_msg_header_len.3.adoc | 43 ++++++ .../src/api/msg/nng_msg_header_trim.3.adoc | 59 ++++++++ docs/reference/src/api/msg/nng_msg_insert.3.adoc | 63 ++++++++ docs/reference/src/api/msg/nng_msg_len.3.adoc | 43 ++++++ docs/reference/src/api/msg/nng_msg_realloc.3.adoc | 66 +++++++++ docs/reference/src/api/msg/nng_msg_reserve.3.adoc | 63 ++++++++ docs/reference/src/api/msg/nng_msg_set_pipe.3.adoc | 50 +++++++ docs/reference/src/api/msg/nng_msg_trim.md | 48 +++++++ docs/reference/src/api/nng_ctx.md | 160 --------------------- docs/reference/src/api/nng_ctx_close.md | 42 ------ docs/reference/src/api/nng_ctx_get.md | 113 --------------- docs/reference/src/api/nng_ctx_getopt.md | 117 --------------- docs/reference/src/api/nng_ctx_id.md | 35 ----- docs/reference/src/api/nng_ctx_open.md | 57 -------- docs/reference/src/api/nng_ctx_recv.md | 61 -------- docs/reference/src/api/nng_ctx_recvmsg.md | 51 ------- docs/reference/src/api/nng_ctx_send.md | 69 --------- docs/reference/src/api/nng_ctx_sendmsg.md | 70 --------- docs/reference/src/api/nng_ctx_set.md | 95 ------------ docs/reference/src/api/nng_ctx_setopt.md | 99 ------------- docs/reference/src/api/socket/index.md | 6 +- docs/reference/src/api/socket/nng_bus_open.md | 8 +- docs/reference/src/api/socket/nng_close.md | 6 +- docs/reference/src/api/socket/nng_pub_open.md | 8 +- docs/reference/src/api/threads/nng_cv_alloc.md | 14 +- docs/reference/src/api/threads/nng_cv_free.md | 4 +- docs/reference/src/api/threads/nng_cv_wait.md | 16 +-- docs/reference/src/api/threads/nng_cv_wake.md | 16 +-- docs/reference/src/api/threads/nng_cv_wake1.md | 17 ++- docs/reference/src/api/util/nng_alloc.md | 6 +- docs/reference/src/api/util/nng_clock.md | 8 +- docs/reference/src/api/util/nng_free.md | 6 +- docs/reference/src/api/util/nng_random.md | 2 +- docs/reference/src/api/util/nng_strerror.md | 2 +- docs/reference/src/api/util/nng_version.md | 2 +- 85 files changed, 2300 insertions(+), 1156 deletions(-) create mode 100644 docs/reference/src/api/context/index.md create mode 100644 docs/reference/src/api/context/nng_ctx_close.md create mode 100644 docs/reference/src/api/context/nng_ctx_get.md create mode 100644 docs/reference/src/api/context/nng_ctx_getopt.md create mode 100644 docs/reference/src/api/context/nng_ctx_id.md create mode 100644 docs/reference/src/api/context/nng_ctx_open.md create mode 100644 docs/reference/src/api/context/nng_ctx_recv.md create mode 100644 docs/reference/src/api/context/nng_ctx_recvmsg.md create mode 100644 docs/reference/src/api/context/nng_ctx_send.md create mode 100644 docs/reference/src/api/context/nng_ctx_sendmsg.md create mode 100644 docs/reference/src/api/context/nng_ctx_set.md create mode 100644 docs/reference/src/api/context/nng_ctx_setopt.md create mode 100644 docs/reference/src/api/msg/index.md create mode 100644 docs/reference/src/api/msg/nng_msg_alloc.md create mode 100644 docs/reference/src/api/msg/nng_msg_append.md create mode 100644 docs/reference/src/api/msg/nng_msg_body.md create mode 100644 docs/reference/src/api/msg/nng_msg_capacity.md create mode 100644 docs/reference/src/api/msg/nng_msg_chop.md create mode 100644 docs/reference/src/api/msg/nng_msg_clear.md create mode 100644 docs/reference/src/api/msg/nng_msg_dup.md create mode 100644 docs/reference/src/api/msg/nng_msg_free.md create mode 100644 docs/reference/src/api/msg/nng_msg_get_pipe.3.adoc create mode 100644 docs/reference/src/api/msg/nng_msg_header.3.adoc create mode 100644 docs/reference/src/api/msg/nng_msg_header_append.3.adoc create mode 100644 docs/reference/src/api/msg/nng_msg_header_chop.3.adoc create mode 100644 docs/reference/src/api/msg/nng_msg_header_clear.3.adoc create mode 100644 docs/reference/src/api/msg/nng_msg_header_insert.3.adoc create mode 100644 docs/reference/src/api/msg/nng_msg_header_len.3.adoc create mode 100644 docs/reference/src/api/msg/nng_msg_header_trim.3.adoc create mode 100644 docs/reference/src/api/msg/nng_msg_insert.3.adoc create mode 100644 docs/reference/src/api/msg/nng_msg_len.3.adoc create mode 100644 docs/reference/src/api/msg/nng_msg_realloc.3.adoc create mode 100644 docs/reference/src/api/msg/nng_msg_reserve.3.adoc create mode 100644 docs/reference/src/api/msg/nng_msg_set_pipe.3.adoc create mode 100644 docs/reference/src/api/msg/nng_msg_trim.md delete mode 100644 docs/reference/src/api/nng_ctx.md delete mode 100644 docs/reference/src/api/nng_ctx_close.md delete mode 100644 docs/reference/src/api/nng_ctx_get.md delete mode 100644 docs/reference/src/api/nng_ctx_getopt.md delete mode 100644 docs/reference/src/api/nng_ctx_id.md delete mode 100644 docs/reference/src/api/nng_ctx_open.md delete mode 100644 docs/reference/src/api/nng_ctx_recv.md delete mode 100644 docs/reference/src/api/nng_ctx_recvmsg.md delete mode 100644 docs/reference/src/api/nng_ctx_send.md delete mode 100644 docs/reference/src/api/nng_ctx_sendmsg.md delete mode 100644 docs/reference/src/api/nng_ctx_set.md delete mode 100644 docs/reference/src/api/nng_ctx_setopt.md (limited to 'docs/reference/src') diff --git a/docs/reference/src/SUMMARY.md b/docs/reference/src/SUMMARY.md index f029f8fb..81d2f24c 100644 --- a/docs/reference/src/SUMMARY.md +++ b/docs/reference/src/SUMMARY.md @@ -19,12 +19,38 @@ - [API Reference](./api/index.md) + - [Messages](api/msg/index.md) + + - [nng_msg_alloc](api/msg/nng_msg_alloc.md) + - [nng_msg_append](api/msg/nng_msg_append.md) + - [nng_msg_body](api/msg/nng_msg_body.md) + - [nng_msg_capacity](api/msg/nng_msg_capacity.md) + - [nng_msg_chop](api/msg/nng_msg_chop.md) + - [nng_msg_clear](api/msg/nng_msg_clear.md) + - [nng_msg_dup](api/msg/nng_msg_dup.md) + - [nng_msg_free](api/msg/nng_msg_free.md) + - [nng_msg_trim](api/msg/nng_msg_trim.md) + - [Sockets](api/socket/index.md) - [nng_bus_open](api/socket/nng_bus_open.md) - [nng_close](api/socket/nng_close.md) - [nng_pub_open](api/socket/nng_pub_open.md) + - [Contexts](api/context/index.md) + + - [nng_ctx_close](api/context/nng_ctx_close.md) + - [nng_ctx_get](api/context/nng_ctx_get.md) + - [nng_ctx_getopt](api/context/nng_ctx_getopt.md) + - [nng_ctx_id](api/context/nng_ctx_id.md) + - [nng_ctx_open](api/context/nng_ctx_open.md) + - [nng_ctx_recv](api/context/nng_ctx_recv.md) + - [nng_ctx_recvmsg](api/context/nng_ctx_recvmsg.md) + - [nng_ctx_send](api/context/nng_ctx_send.md) + - [nng_ctx_sendmsg](api/context/nng_ctx_sendmsg.md) + - [nng_ctx_set](api/context/nng_ctx_set.md) + - [nng_ctx_setopt](api/context/nng_ctx_setopt.md) + - [Asynchronous I/O](./api/aio/index.md) - [nng_aio_abort](api/aio/nng_aio_abort.md) @@ -69,21 +95,6 @@ - [nng_cv_wake](api/threads/nng_cv_wake.md) - [nng_cv_wake1](api/threads/nng_cv_wake1.md) - - [Context Functions](api/context.md) - - - [nng_ctx](api/nng_ctx.md) - - [nng_ctx_close](api/nng_ctx_close.md) - - [nng_ctx_get](api/nng_ctx_get.md) - - [nng_ctx_getopt](api/nng_ctx_getopt.md) - - [nng_ctx_id](api/nng_ctx_id.md) - - [nng_ctx_open](api/nng_ctx_open.md) - - [nng_ctx_recv](api/nng_ctx_recv.md) - - [nng_ctx_recvmsg](api/nng_ctx_recvmsg.md) - - [nng_ctx_send](api/nng_ctx_send.md) - - [nng_ctx_sendmsg](api/nng_ctx_sendmsg.md) - - [nng_ctx_set](api/nng_ctx_set.md) - - [nng_ctx_setopt](api/nng_ctx_setopt.md) - - [Legacy Compatibility](api/compat/index.md) - [Index](./indexing.md) diff --git a/docs/reference/src/api/aio/index.md b/docs/reference/src/api/aio/index.md index 4c49ff78..84c6d6e1 100644 --- a/docs/reference/src/api/aio/index.md +++ b/docs/reference/src/api/aio/index.md @@ -1,4 +1,4 @@ -# Interfaces for Aysnchronous I/O +# Aysnchronous I/O _NNG_ provides rich support for {{i:asynchronous I/O}}. This allows applications to achieve high levels of concurrency with a @@ -57,18 +57,18 @@ complete [`nng_aio_wait()`](nng_aio_wait.md). ## See Also -[nng_aio_abort()](nng_aio_abort.md), -[nng_aio_alloc()](nng_aio_alloc.md), -[nng_aio_cancel()](nng_aio_cancel.md), -[nng_aio_count()](nng_aio_count.md), -[nng_aio_free()](nng_aio_free.md), -[nng_aio_get_input()](nng_aio_get_input.md), -[nng_aio_get_msg()](nng_aio_get_msg.md), -[nng_aio_get_output()](nng_aio_get_output.md), -[nng_aio_result()](nng_aio_result.md), -[nng_aio_set_input()](nng_aio_set_input.md), -[nng_aio_set_iov()](nng_aio_set_iov.md), -[nng_aio_set_msg()](nng_aio_set_msg.md), -[nng_aio_set_timeout()](nng_aio_set_timeout.md), -[nng_aio_stop()](nng_aio_stop.md), -[nng_aio_wait()](nng_aio_wait.md) +[nng_aio_abort](nng_aio_abort.md), +[nng_aio_alloc](nng_aio_alloc.md), +[nng_aio_cancel](nng_aio_cancel.md), +[nng_aio_count](nng_aio_count.md), +[nng_aio_free](nng_aio_free.md), +[nng_aio_get_input](nng_aio_get_input.md), +[nng_aio_get_msg](nng_aio_get_msg.md), +[nng_aio_get_output](nng_aio_get_output.md), +[nng_aio_result](nng_aio_result.md), +[nng_aio_set_input](nng_aio_set_input.md), +[nng_aio_set_iov](nng_aio_set_iov.md), +[nng_aio_set_msg](nng_aio_set_msg.md), +[nng_aio_set_timeout](nng_aio_set_timeout.md), +[nng_aio_stop](nng_aio_stop.md), +[nng_aio_wait](nng_aio_wait.md) diff --git a/docs/reference/src/api/aio/nng_aio_abort.md b/docs/reference/src/api/aio/nng_aio_abort.md index 09e0fd2e..a94ffd30 100644 --- a/docs/reference/src/api/aio/nng_aio_abort.md +++ b/docs/reference/src/api/aio/nng_aio_abort.md @@ -1,4 +1,4 @@ -# nng_aio_abort() +# nng_aio_abort ## NAME @@ -30,6 +30,6 @@ has no effect. ## SEE ALSO -[nng_aio_alloc()](nng_aio_alloc.md), -[nng_aio_cancel()](nng_aio_cancel.md), -[nng_aio_result()](nng_aio_result.md) +[nng_aio_alloc](nng_aio_alloc.md), +[nng_aio_cancel](nng_aio_cancel.md), +[nng_aio_result](nng_aio_result.md) diff --git a/docs/reference/src/api/aio/nng_aio_alloc.md b/docs/reference/src/api/aio/nng_aio_alloc.md index 1f3f6be8..5636f398 100644 --- a/docs/reference/src/api/aio/nng_aio_alloc.md +++ b/docs/reference/src/api/aio/nng_aio_alloc.md @@ -1,4 +1,4 @@ -# nng_aio_alloc() +# nng_aio_alloc ## NAME @@ -58,17 +58,17 @@ This function returns 0 on success, and non-zero otherwise. ## SEE ALSO -[nng_aio_abort()](nng_aio_abort.md), -[nng_aio_cancel()](nng_aio_cancel.md), -[nng_aio_count()](nng_aio_count.md), -[nng_aio_free()](nng_aio_free.md), -[nng_aio_get_input()](nng_aio_get_input.md), -[nng_aio_get_msg()](nng_aio_get_msg.md), -[nng_aio_get_output()](nng_aio_get_output.md), -[nng_aio_result()](nng_aio_result.md), -[nng_aio_set_input()](nng_aio_set_input.md), -[nng_aio_set_iov()](nng_aio_set_iov.md), -[nng_aio_set_msg()](nng_aio_set_msg.md), -[nng_aio_set_timeout()](nng_aio_set_timeout.md), -[nng_aio_stop()](nng_aio_stop.md), -[nng_aio_wait()](nng_aio_wait.md) +[nng_aio_abort](nng_aio_abort.md), +[nng_aio_cancel](nng_aio_cancel.md), +[nng_aio_count](nng_aio_count.md), +[nng_aio_free](nng_aio_free.md), +[nng_aio_get_input](nng_aio_get_input.md), +[nng_aio_get_msg](nng_aio_get_msg.md), +[nng_aio_get_output](nng_aio_get_output.md), +[nng_aio_result](nng_aio_result.md), +[nng_aio_set_input](nng_aio_set_input.md), +[nng_aio_set_iov](nng_aio_set_iov.md), +[nng_aio_set_msg](nng_aio_set_msg.md), +[nng_aio_set_timeout](nng_aio_set_timeout.md), +[nng_aio_stop](nng_aio_stop.md), +[nng_aio_wait](nng_aio_wait.md) diff --git a/docs/reference/src/api/aio/nng_aio_busy.md b/docs/reference/src/api/aio/nng_aio_busy.md index 2a794a83..826247fa 100644 --- a/docs/reference/src/api/aio/nng_aio_busy.md +++ b/docs/reference/src/api/aio/nng_aio_busy.md @@ -1,4 +1,4 @@ -# nng_aio_busy() +# nng_aio_busy ## NAME @@ -36,6 +36,6 @@ True if the _aio_ is busy, false otherwise. ## SEE ALSO -[nng_aio_abort()](nng_aio_abort.md), -[nng_aio_alloc()](nng_aio_alloc.md), -[nng_aio_wait(3)](nng_aio_wait.md) +[nng_aio_abort](nng_aio_abort.md), +[nng_aio_alloc](nng_aio_alloc.md), +[nng_aio_wait](nng_aio_wait.md) diff --git a/docs/reference/src/api/aio/nng_aio_cancel.md b/docs/reference/src/api/aio/nng_aio_cancel.md index 63cad987..c523bf52 100644 --- a/docs/reference/src/api/aio/nng_aio_cancel.md +++ b/docs/reference/src/api/aio/nng_aio_cancel.md @@ -1,4 +1,4 @@ -# nng_aio_cancel() +# nng_aio_cancel ## NAME @@ -32,6 +32,6 @@ This function is the same as calling ## SEE ALSO -[nng_aio_abort()](nng_aio_abort.md), -[nng_aio_alloc()](nng_aio_alloc.md), -[nng_aio_result()](nng_aio_result.md) +[nng_aio_abort](nng_aio_abort.md), +[nng_aio_alloc](nng_aio_alloc.md), +[nng_aio_result](nng_aio_result.md) diff --git a/docs/reference/src/api/aio/nng_aio_count.md b/docs/reference/src/api/aio/nng_aio_count.md index a4da3c64..ae844da0 100644 --- a/docs/reference/src/api/aio/nng_aio_count.md +++ b/docs/reference/src/api/aio/nng_aio_count.md @@ -1,4 +1,4 @@ -# nng_aio_count() +# nng_aio_count ## NAME @@ -38,7 +38,7 @@ The number of bytes transferred by the operation. ## SEE ALSO -[nng_aio_alloc()](nng_aio_alloc.md), -[nng_aio_result()](nng_aio_result.md), -[nng_aio_set_iov()](nng_aio_set_iov.md), -[nng_aio_wait()](nng_aio_wait.md) +[nng_aio_alloc](nng_aio_alloc.md), +[nng_aio_result](nng_aio_result.md), +[nng_aio_set_iov](nng_aio_set_iov.md), +[nng_aio_wait](nng_aio_wait.md) diff --git a/docs/reference/src/api/aio/nng_aio_free.md b/docs/reference/src/api/aio/nng_aio_free.md index 3d73dd7c..ba400bba 100644 --- a/docs/reference/src/api/aio/nng_aio_free.md +++ b/docs/reference/src/api/aio/nng_aio_free.md @@ -1,4 +1,4 @@ -# nng_aio_free() +# nng_aio_free ## NAME @@ -30,5 +30,5 @@ This can be useful to discard the _aio_ object from within the callback for the ## SEE ALSO -[nng_aio_alloc()](nng_aio_alloc.md), -[nng_aio_stop()](nng_aio_stop.md) +[nng_aio_alloc](nng_aio_alloc.md), +[nng_aio_stop](nng_aio_stop.md) diff --git a/docs/reference/src/api/aio/nng_aio_get_msg.md b/docs/reference/src/api/aio/nng_aio_get_msg.md index 55f712db..e77b7810 100644 --- a/docs/reference/src/api/aio/nng_aio_get_msg.md +++ b/docs/reference/src/api/aio/nng_aio_get_msg.md @@ -1,4 +1,4 @@ -# nng_aio_get_msg() +# nng_aio_get_msg ## NAME @@ -25,6 +25,6 @@ or that was previously stored with ## SEE ALSO -[nng_aio_set_msg()](nng_aio_set_msg.md), -[nng_recv_aio()](nng_recv_aio.md), -[nng_msg](nng_msg.md) +[nng_aio_set_msg](nng_aio_set_msg.md), +[nng_recv_aio](nng_recv_aio.md), +[Messages](../msg/index.md) diff --git a/docs/reference/src/api/aio/nng_aio_get_output.md b/docs/reference/src/api/aio/nng_aio_get_output.md index d25c1c20..9983696f 100644 --- a/docs/reference/src/api/aio/nng_aio_get_output.md +++ b/docs/reference/src/api/aio/nng_aio_get_output.md @@ -1,4 +1,4 @@ -# nng_aio_get_output() +# nng_aio_get_output ## NAME @@ -31,10 +31,10 @@ operations. ## RETURN VALUES -The _index_‍th output from the operation, or `NULL`. +The *index*th output from the operation, or `NULL`. ## SEE ALSO -[nng_aio_alloc()](nng_aio_alloc.md), -[nng_aio_set_output()](../aio_provider/nng_aio_set_output.md), -[nng_aio_result()](nng_aio_result.md) +[nng_aio_alloc](nng_aio_alloc.md), +[nng_aio_set_output](../aio_provider/nng_aio_set_output.md), +[nng_aio_result](nng_aio_result.md) diff --git a/docs/reference/src/api/aio/nng_aio_result.md b/docs/reference/src/api/aio/nng_aio_result.md index 607f34d4..21038719 100644 --- a/docs/reference/src/api/aio/nng_aio_result.md +++ b/docs/reference/src/api/aio/nng_aio_result.md @@ -1,4 +1,4 @@ -# nng_aio_result() +# nng_aio_result ## NAME @@ -40,7 +40,7 @@ Various other return values are possible depending on the operation. ## SEE ALSO -[nng_aio_abort()](nng_aio_abort.md), -[nng_aio_alloc()](nng_aio_alloc.md), -[nng_aio_wait()](nng_aio_wait.md), -[nng_strerror()](../util/nng_strerror.md) +[nng_aio_abort](nng_aio_abort.md), +[nng_aio_alloc](nng_aio_alloc.md), +[nng_aio_wait](nng_aio_wait.md), +[nng_strerror](../util/nng_strerror.md) diff --git a/docs/reference/src/api/aio/nng_aio_set_input.md b/docs/reference/src/api/aio/nng_aio_set_input.md index 1b3e0883..baf9587a 100644 --- a/docs/reference/src/api/aio/nng_aio_set_input.md +++ b/docs/reference/src/api/aio/nng_aio_set_input.md @@ -1,4 +1,4 @@ -# nng_aio_set_input() +# nng_aio_set_input ## NAME @@ -38,5 +38,5 @@ the [`nng_aio_get_input()`](nng_aio_get_input.md) function. ## SEE ALSO -[nng_aio_alloc()](nng_aio_alloc.md), -[nng_aio_get_input()](../aio_provider/nng_aio_get_input.md) +[nng_aio_alloc](nng_aio_alloc.md), +[nng_aio_get_input](../aio_provider/nng_aio_get_input.md) diff --git a/docs/reference/src/api/aio/nng_aio_set_msg.md b/docs/reference/src/api/aio/nng_aio_set_msg.md index 24ba9f60..c9b5c03a 100644 --- a/docs/reference/src/api/aio/nng_aio_set_msg.md +++ b/docs/reference/src/api/aio/nng_aio_set_msg.md @@ -23,6 +23,6 @@ for an asynchronous send operation (see ## SEE ALSO -[nng_aio_get_msg()](nng_aio_get_msg.md), -[nng_send_aio()](nng_send_aio.md), -[nng_msg](nng_msg.md) +[nng_aio_get_msg](nng_aio_get_msg.md), +[nng_send_aio](nng_send_aio.md), +[Messages](../msg/index.md) diff --git a/docs/reference/src/api/aio/nng_aio_set_timeout.md b/docs/reference/src/api/aio/nng_aio_set_timeout.md index e5ac3e8e..34daa6f4 100644 --- a/docs/reference/src/api/aio/nng_aio_set_timeout.md +++ b/docs/reference/src/api/aio/nng_aio_set_timeout.md @@ -1,4 +1,4 @@ -# nng_aio_set_timeout() +# nng_aio_set_timeout ## NAME @@ -48,6 +48,6 @@ or absolute timeout. ## SEE ALSO -[nng_aio_cancel()](nng_aio_cancel.md), -[nng_aio_result()](nng_aio_result.md), -[nng_clock()](../util/nng_clock.md) +[nng_aio_cancel](nng_aio_cancel.md), +[nng_aio_result](nng_aio_result.md), +[nng_clock](../util/nng_clock.md) diff --git a/docs/reference/src/api/aio/nng_aio_stop.md b/docs/reference/src/api/aio/nng_aio_stop.md index 8ac32a76..7838eda2 100644 --- a/docs/reference/src/api/aio/nng_aio_stop.md +++ b/docs/reference/src/api/aio/nng_aio_stop.md @@ -1,4 +1,4 @@ -# nng_aio_stop() +# nng_aio_stop ## NAME @@ -33,7 +33,7 @@ pending for it. ## SEE ALSO -[nng_aio_cancel()](nng_aio_cancel.md), -[nng_aio_free()](nng_aio_free.md), -[nng_aio_begin()](nng_aio_begin.md), -[nng_aio_wait()](nng_aio-wait.md) +[nng_aio_cancel](nng_aio_cancel.md), +[nng_aio_free](nng_aio_free.md), +[nng_aio_begin](nng_aio_begin.md), +[nng_aio_wait](nng_aio-wait.md) diff --git a/docs/reference/src/api/aio/nng_aio_wait.md b/docs/reference/src/api/aio/nng_aio_wait.md index be81378c..76198ca1 100644 --- a/docs/reference/src/api/aio/nng_aio_wait.md +++ b/docs/reference/src/api/aio/nng_aio_wait.md @@ -1,4 +1,4 @@ -# nng_aio_wait() +# nng_aio_wait ## NAME @@ -29,5 +29,5 @@ function will not be called until the callback has completed. ## SEE ALSO -[nng_aio_abort()](nng_aio_abort.md), -[nng_aio_busy()](nng_aio_busy.md) +[nng_aio_abort](nng_aio_abort.md), +[nng_aio_busy](nng_aio_busy.md) diff --git a/docs/reference/src/api/aio_provider/index.md b/docs/reference/src/api/aio_provider/index.md index 75a47358..8fcaeeb0 100644 --- a/docs/reference/src/api/aio_provider/index.md +++ b/docs/reference/src/api/aio_provider/index.md @@ -13,9 +13,9 @@ other consumer functions for [Aysnchronous I/O](../aio/index.md). ## See Also -[nng_aio_begin()](nng_aio_begin.md), -[nng_aio_defer()](nng_aio_defer.md), -[nng_aio_finish()](nng_aio_finish.md), -[nng_aio_get_input()](nng_aio_get_input.md), -[nng_aio_set_output()](nng_aio_set_output.md), +[nng_aio_begin](nng_aio_begin.md), +[nng_aio_defer](nng_aio_defer.md), +[nng_aio_finish](nng_aio_finish.md), +[nng_aio_get_input](nng_aio_get_input.md), +[nng_aio_set_output](nng_aio_set_output.md), [Asynchronous I/O](../aio/index.md) diff --git a/docs/reference/src/api/aio_provider/nng_aio_begin.md b/docs/reference/src/api/aio_provider/nng_aio_begin.md index 8e342b26..59f21112 100644 --- a/docs/reference/src/api/aio_provider/nng_aio_begin.md +++ b/docs/reference/src/api/aio_provider/nng_aio_begin.md @@ -1,4 +1,4 @@ -# nng_aio_begin() +# nng_aio_begin ## NAME @@ -39,6 +39,6 @@ exactly once, when the operation is complete or canceled. ## SEE ALSO -[nng_aio_cancel()](../aio/nng_aio_cancel.md), -[nng_aio_defer()](nng_aio_defer.md), -[nng_aio_finish()](nng_aio_finish.md) +[nng_aio_cancel](../aio/nng_aio_cancel.md), +[nng_aio_defer](nng_aio_defer.md), +[nng_aio_finish](nng_aio_finish.md) diff --git a/docs/reference/src/api/aio_provider/nng_aio_defer.md b/docs/reference/src/api/aio_provider/nng_aio_defer.md index 93d84769..e7782761 100644 --- a/docs/reference/src/api/aio_provider/nng_aio_defer.md +++ b/docs/reference/src/api/aio_provider/nng_aio_defer.md @@ -1,4 +1,4 @@ -# nng_aio_defer() +# nng_aio_defer ## NAME @@ -53,6 +53,6 @@ error code specified by _err_. ## SEE ALSO -[nng_aio_alloc()](../aio/nng_aio_alloc.md), -[nng_aio_cancel()](../aio/nng_aio_cancel.md), -[nng_aio_finish()](nng_aio_finish.md) +[nng_aio_alloc](../aio/nng_aio_alloc.md), +[nng_aio_cancel](../aio/nng_aio_cancel.md), +[nng_aio_finish](nng_aio_finish.md) diff --git a/docs/reference/src/api/aio_provider/nng_aio_finish.md b/docs/reference/src/api/aio_provider/nng_aio_finish.md index 61b1ca42..215f6716 100644 --- a/docs/reference/src/api/aio_provider/nng_aio_finish.md +++ b/docs/reference/src/api/aio_provider/nng_aio_finish.md @@ -1,4 +1,4 @@ -# nng_aio_finish() +# nng_aio_finish ## NAME @@ -33,7 +33,7 @@ This function causes the callback associated with the _aio_ to called. ## SEE ALSO -[nng_aio_begin()](nng_aio_begin.md), -[nng_aio_cancel()](nng_aio_cancel.md), -[nng_aio_defer()](nng_aio_defer.md), -[nng_aio_result()](../aio/nng_aio_result.md) +[nng_aio_begin](nng_aio_begin.md), +[nng_aio_cancel](../aio/nng_aio_cancel.md), +[nng_aio_defer](nng_aio_defer.md), +[nng_aio_result](../aio/nng_aio_result.md) diff --git a/docs/reference/src/api/aio_provider/nng_aio_get_input.md b/docs/reference/src/api/aio_provider/nng_aio_get_input.md index 28ecb797..598a5a47 100644 --- a/docs/reference/src/api/aio_provider/nng_aio_get_input.md +++ b/docs/reference/src/api/aio_provider/nng_aio_get_input.md @@ -1,4 +1,4 @@ -# nng_aio_get_input(3) +# nng_aio_get_input ## NAME @@ -16,7 +16,7 @@ void *nng_aio_get_input(nng_aio *aio, unsigned int index); The `nng_aio_get_input()` function returns the value of the input parameter previously set at _index_ on _aio_ with the -[`nng_aio_set_input()`](nng_aio_set_input.md) function. +[`nng_aio_set_input()`](../aio/nng_aio_set_input.md) function. The valid values of _index_ range from zero (0) to three (3), as no operation currently defined can accept more than four parameters. @@ -29,6 +29,6 @@ Value previously set, or `NULL`. ## SEE ALSO -[nng_aio_alloc()](../aio/nng_aio_alloc.md), -[nng_aio_get_output()](../aio/nng_aio_get_output.md), -[nng_aio_set_input()](../aio/nng_aio_set_input.md) +[nng_aio_alloc](../aio/nng_aio_alloc.md), +[nng_aio_get_output](../aio/nng_aio_get_output.md), +[nng_aio_set_input](../aio/nng_aio_set_input.md) diff --git a/docs/reference/src/api/aio_provider/nng_aio_set_output.md b/docs/reference/src/api/aio_provider/nng_aio_set_output.md index 902351b7..11761352 100644 --- a/docs/reference/src/api/aio_provider/nng_aio_set_output.md +++ b/docs/reference/src/api/aio_provider/nng_aio_set_output.md @@ -1,4 +1,4 @@ -# nng_aio_set_output() +# nng_aio_set_output ## NAME @@ -33,4 +33,4 @@ the [`nng_aio_get_output()`](../aio/nng_aio_get_output.md) function. ## SEE ALSO -[nng_aio_get_output(3)](../aio/nng_aio_get_output.md) +[nng_aio_get_output](../aio/nng_aio_get_output.md) diff --git a/docs/reference/src/api/context/index.md b/docs/reference/src/api/context/index.md new file mode 100644 index 00000000..d5a3fc90 --- /dev/null +++ b/docs/reference/src/api/context/index.md @@ -0,0 +1,160 @@ +# nng_ctx + +## NAME + +nng_ctx --- protocol context + +## SYNOPSIS + +```c +#include + +typedef struct nng_ctx_s nng_ctx +``` + +## DESCRIPTION + +An `nng_ctx`{{hi:context}} is a handle to an underlying context object, +which keeps the protocol state for some stateful protocols. +The purpose of a separate context object is to permit applications to +share a single [socket](../socket/index.md), with its various underlying +[dialers](nng_dialer.md), +[listeners](nng_listener.md), +[pipes](nng_pipe.md), +while still benefiting from separate state tracking. + +For example, a [_REQ_](../protocols/req.md) context will contain the request ID +of any sent request, a timer to retry the request on failure, and so forth. +A separate context on the same socket can have similar data, but corresponding +to a completely different request. + +> [!NOTE] +> The `nng_ctx` structure is always passed by value (both +> for input parameters and return values), and should be treated opaquely. +> Passing structures this way gives the compiler a chance to perform +> accurate type checks in functions passing values of this type. + +All contexts share the same socket, and so some options, as well as the +underlying transport details, will be common to all contexts on that socket. + +Protocols that make use of contexts will also have a default context +that is used when the socket global operations are used. +Operations using the global context will generally not interfere with +any other contexts, except that certain socket options may affect socket +global behavior. + +{{hi:concurrent}}{{hi:raw mode}} +Historically, applications wanting to use a stateful protocol concurrently +would have to resort to [raw mode](../overview/raw.md) sockets, which bypasses +much of the various protocol handling, leaving it to up to the application +to do so. +Contexts make it possible to still benefit from advanced protocol handling, +including timeouts, retries, and matching requests to responses, while doing so +concurrently. + +> [!TIP] +> Contexts are an excellent mechanism to use when building concurrent +> applications, and should be used in lieu of +> [raw mode](../overview/raw.md) sockets when possible. + +## Caveats + +Not every protocol supports separate contexts. +See the protocol-specific documentation for further details about whether +contexts are supported, and details about what options are supported for +contexts. + +Use of file descriptor polling (with descriptors obtained using the +[`NNG_OPT_RECVFD`](nng_options.md#NNG_OPT_RECVFD) or +[`NNG_OPT_SENDFD`](nng_options.md#NNG_OPT_SENDFD) options) while contexts +are in use on the same socket is not supported, and may lead to unpredictable +behavior. These asynchronous methods should not be mixed on the same socket. + +[Raw mode](../overview/raw.md) sockets do not support contexts, since +there is generally no state tracked for them, and thus contexts make no sense. + +## Initialization + +A context may be initialized using the macro `NNG_CTX_INITIALIZER` +before it is opened, to prevent confusion with valid open contexts. + +## Example + +The following program fragment demonstrates the use of contexts to implement +a concurrent [_REP_](../protocols/rep.md) service that simply echos messages back +to the sender. + +```c +struct echo_context { + nng_ctx ctx; + nng_aio *aio; + enum { INIT, RECV, SEND } state; +}; + +void +echo(void *arg) +{ + struct echo_context *ec = arg; + + switch (ec->state) { + case INIT: + ec->state = RECV; + nng_ctx_recv(ec->ctx, ec->aio); + return; + case RECV: + if (nng_aio_result(ec->aio) != 0) { + // ... handle error + } + // We reuse the message on the ec->aio + ec->state = SEND; + nng_ctx_send(ec->ctx, ec->aio); + return; + case SEND: + if (nng_aio_result(ec->aio) != 0) { + // ... handle error + } + ec->state = RECV; + nng_ctx_recv(ec->ctx, ec->aio); + return; + } +} +``` + +Given the above fragment, the following example shows setting up the +service. It assumes that the [socket](nng_socket.md) has already been +created and any transports set up as well with functions such as +[`nng_dial()`](nng_dial.md) or [`nng_listen()`](nng_listen.md). + +```c +#define CONCURRENCY 1024 + +echo_context ecs[CONCURRENCY]; + +void +start_echo_service(nng_socket rep_socket) +{ + for (int i = 0; i < CONCURRENCY; i++) { + // error checks elided for clarity + nng_ctx_open(ec[i].ctx, rep_socket) + nng_aio_alloc(ec[i].aio, echo, &e[i]); + ec[i].state = INIT; + echo(&ec[i]); // start it running + } +} +``` + +## SEE ALSO + +[nng_ctx_close](nng_ctx_close.md), +[nng_ctx_open](nng_ctx_open.md), +[nng_ctx_get](nng_ctx_get.md), +[nng_ctx_id](nng_ctx_id.md) +[nng_ctx_recv](nng_ctx_recv.md), +[nng_ctx_recvmsg](nng_ctx_recvmsg.md), +[nng_ctx_send](nng_ctx_send.md), +[nng_ctx_sendmsg](nng_ctx_sendmsg.md), +[nng_ctx_set](nng_ctx_set.md), +[nng_dialer](nng_dialer.md), +[nng_listener](nng_listener.md), +[nng_socket](../socket/index.md), +[nng_options](nng_options.md) diff --git a/docs/reference/src/api/context/nng_ctx_close.md b/docs/reference/src/api/context/nng_ctx_close.md new file mode 100644 index 00000000..e33dd843 --- /dev/null +++ b/docs/reference/src/api/context/nng_ctx_close.md @@ -0,0 +1,41 @@ +# nng_ctx_close + +## NAME + +nng_ctx_close --- close context + +## SYNOPSIS + +```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 [`nng_close()`](../socket/nng_close.md)) also closes this context. + +## RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +## ERRORS + +- `NNG_ECLOSED`: The context _ctx_ is already closed or was never opened. + +## SEE ALSO + +[nng_close](nng_close.md), +[nng_ctx_open](nng_ctx_open.md) diff --git a/docs/reference/src/api/context/nng_ctx_get.md b/docs/reference/src/api/context/nng_ctx_get.md new file mode 100644 index 00000000..35407f18 --- /dev/null +++ b/docs/reference/src/api/context/nng_ctx_get.md @@ -0,0 +1,112 @@ +# nng_ctx_get + +## NAME + +nng_ctx_get --- get context option + +## SYNOPSIS + +```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 + +{{hi:options, context}} +The `nng_ctx_get()` functions are used to retrieve option values for +the [context](index.md) _ctx_. +The actual options that may be retrieved in this way vary. +A number of them are documented in [nng_options](../socket/nng_options.md). + +> [!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. + +- `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 [durations](nng_duration.md) + (such as timeouts), stored in _durp_ as a number of milliseconds. + (The special value {{i:`NNG_DURATION_INFINITE`}} means an infinite amount of time, and + the special value {{i:`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 [`nng_strdup()`](nng_strdup.md) + and consequently must be freed by the caller using + [`nng_strfree()`](nng_strfree.md) 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 + +- `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 + +[nng_ctx_set](nng_ctx_set.md), +[nng_strdup](nng_strdup.md), +[nng_strfree](nng_strfree.md), +[nng_duration](nng_duration.md), +[nng_options](../socket/nng_options.md) diff --git a/docs/reference/src/api/context/nng_ctx_getopt.md b/docs/reference/src/api/context/nng_ctx_getopt.md new file mode 100644 index 00000000..83a648d0 --- /dev/null +++ b/docs/reference/src/api/context/nng_ctx_getopt.md @@ -0,0 +1,116 @@ +# nng_ctx_getopt + +## NAME + +nng_ctx_getopt --- get context option (deprecated) + +## SYNOPSIS + +```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 [nng_ctx_get](nng_ctx_get.md). +> They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`. +> They may also be removed entirely in a future version of _NNG_. + +The `nng_ctx_getopt()` functions are used to retrieve option values for +the [context](index.md) _ctx_. +The actual options that may be retrieved in this way vary. + +> [!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. + +- `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 [durations](nng_duration.md) + (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 [`nng_strdup()`](../util/nng_strdup.md) + and consequently must be freed by the caller using + [`nng_strfree()`](../util/nng_strfree.md) 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 + +- `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 + +[nng_strdup](../util/nng_strdup.md), +[nng_strfree](../util/nng_strfree.md), +[nng_duration](nng_duration.md), +[nng_options](../socket/nng_options.md) diff --git a/docs/reference/src/api/context/nng_ctx_id.md b/docs/reference/src/api/context/nng_ctx_id.md new file mode 100644 index 00000000..9d8d7223 --- /dev/null +++ b/docs/reference/src/api/context/nng_ctx_id.md @@ -0,0 +1,31 @@ +# nng_ctx_id + +## NAME + +nng_ctx_id --- return numeric context identifier + +## SYNOPSIS + +```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 +> [`nng_ctx_open()`](nng_ctx_open.md) function. +> Contexts that are allocated on the stack or statically should be +> initialized with the macro `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. diff --git a/docs/reference/src/api/context/nng_ctx_open.md b/docs/reference/src/api/context/nng_ctx_open.md new file mode 100644 index 00000000..b582e254 --- /dev/null +++ b/docs/reference/src/api/context/nng_ctx_open.md @@ -0,0 +1,56 @@ +# nng_ctx_open + +## NAME + +nng_ctx_open --- create context + +## SYNOPSIS + +```c +#include + +int nng_ctx_open(nng_ctx *ctxp, nng_socket s); +``` + +## DESCRIPTION + +The `nng_ctx_open()` function creates a separate {{i: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 +[_REP_](../protocols/rep.md) +socket can each receive requests, and send replies to them, without any +regard to or interference with each other. + +> [!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 +> {{hi:raw mode}}[raw mode](../overview/raw.md) sockets. + +> [!NOTE] +> Use of contexts with [raw mode](../overview/raw.md) sockets is +> nonsensical, and not supported. + +## RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +## ERRORS + +- `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 + +[nng_ctx_close](nng_ctx_close.md), +[nng_ctx_get](nng_ctx_get.md), +[nng_ctx_recv](nng_ctx_recv.md), +[nng_ctx_send](nng_ctx_send.md), +[nng_ctx_set](nng_ctx_set.md) diff --git a/docs/reference/src/api/context/nng_ctx_recv.md b/docs/reference/src/api/context/nng_ctx_recv.md new file mode 100644 index 00000000..2ef398ea --- /dev/null +++ b/docs/reference/src/api/context/nng_ctx_recv.md @@ -0,0 +1,56 @@ +# nng_ctx_recv + +## NAME + +nng_ctx_recv --- receive message using context asynchronously + +## SYNOPSIS + +```c +#include + +void nng_ctx_recv(nng_ctx ctx, nng_aio *aio); +``` + +## DESCRIPTION + +The `nng_ctx_recv()` receives a [message](../msg/index.md) using the +[context](index.md) _s_ asynchronously. + +When a message is successfully received by the context, it is +stored in the _aio_ by an internal call equivalent to +[`nng_aio_set_msg()`](../aio/nng_aio_set_msg.md), then the completion +callback on the _aio_ is executed. +In this case, [`nng_aio_result()`](../aio/nng_aio_result.md) 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 [`nng_aio_result()`](../aio/nng_aio_result.md) will be non-zero. + +> [!TIP] +> The semantics of what receiving a message means varies from protocol to +> protocol, so examination of the protocol documentation is encouraged. + +## ERRORS + +The following errors may be set on the _aio_, if the operation fails. + +- `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 + +[Asynchronous I/O](../aio/index.md), +[Messages](../msg/index.md) diff --git a/docs/reference/src/api/context/nng_ctx_recvmsg.md b/docs/reference/src/api/context/nng_ctx_recvmsg.md new file mode 100644 index 00000000..c0065dd3 --- /dev/null +++ b/docs/reference/src/api/context/nng_ctx_recvmsg.md @@ -0,0 +1,50 @@ +# nng_ctx_recvmsg + +## NAME + +nng_ctx_recvmsg --- receive message using socket + +## SYNOPSIS + +```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. + +> [!TIP] +> 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 + +- `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 + +[nng_msg_free()](../msg/nng_msg_free.md), +[nng_ctx_open()](nng_ctx_open.md), +[nng_ctx_recv()](nng_ctx_recv.md), +[nng_ctx_sendmsg()](nng_ctx_sendmsg.md) diff --git a/docs/reference/src/api/context/nng_ctx_send.md b/docs/reference/src/api/context/nng_ctx_send.md new file mode 100644 index 00000000..9caad652 --- /dev/null +++ b/docs/reference/src/api/context/nng_ctx_send.md @@ -0,0 +1,68 @@ +# nng_ctx_send + +## NAME + +nng_ctx_send --- send message using context asynchronously + +## SYNOPSIS + +```c +#include + +void nng_ctx_send(nng_ctx ctx, nng_aio *aio); +``` + +## DESCRIPTION + +The `nng_ctx_send()` sends a [message](../msg/index.md) using the +[context](nng_ctx.md) _ctx_ asynchronously. + +The message to send must have previously been set on the _aio_ +using the [`nng_aio_set_msg()`](../aio/nng_aio_set_msg.md) 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 [`nng_aio_result()`](../aio/nng_aio_result.md) +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 +[`nng_aio_result()`](../aio/nng_aio_result.md) will return a non-zero error status. +In this case, the callback has a responsibility to retrieve the message from +the _aio_ with [`nng_aio_get_msg()`](../aio/nng_aio_get_msg.md) and dispose of +it appropriately. +(This may include retrying the send operation on the same or a different +socket, or deallocating the message with [`nng_msg_free()`](../msg/nng_msg_free.md). + +> [!TIP] +> The semantics of what sending a message means varies from protocol to +> protocol, so examination of the protocol documentation is encouraged. + +## ERRORS + +- `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 + +[nng_aio_get_msg](../aio/nng_aio_get_msg.md), +[nng_aio_set_msg](../aio/nng_aio_set_msg.md), +[nng_ctx_sendmsg](nng_ctx_sendmsg.md), +[nng_msg_alloc](../msg/nng_msg_alloc.md), +[nng_msg_free](../msg/nng_msg_free.md), +[Asynchronous I/O](../aio/index.md), +[Messages](../msg/index.md) diff --git a/docs/reference/src/api/context/nng_ctx_sendmsg.md b/docs/reference/src/api/context/nng_ctx_sendmsg.md new file mode 100644 index 00000000..346f927d --- /dev/null +++ b/docs/reference/src/api/context/nng_ctx_sendmsg.md @@ -0,0 +1,67 @@ +# nng_ctx_sendmsg() + +## NAME + +nng_ctx_sendmsg --- send message using context + +## SYNOPSIS + +```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. + +> [!TIP] +> 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 + +- `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 + +[nng_ctx_send()](nng_ctx_send.md), +[Messages](../msg/index.md) diff --git a/docs/reference/src/api/context/nng_ctx_set.md b/docs/reference/src/api/context/nng_ctx_set.md new file mode 100644 index 00000000..b3237717 --- /dev/null +++ b/docs/reference/src/api/context/nng_ctx_set.md @@ -0,0 +1,94 @@ +# nng_ctx_set + +## NAME + +nng_ctx_set --- set context option + +## SYNOPSIS + +```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 + +{{hi: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_. + +- `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 [`nng_duration`](nng_duration.md). + 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 + +- `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 + +[nng_ctx_get](nng_ctx_get), +[nng_socket_set](../socket/nng_socket_get), +[nng_options](nng_options) diff --git a/docs/reference/src/api/context/nng_ctx_setopt.md b/docs/reference/src/api/context/nng_ctx_setopt.md new file mode 100644 index 00000000..f62b6857 --- /dev/null +++ b/docs/reference/src/api/context/nng_ctx_setopt.md @@ -0,0 +1,98 @@ +# nng_ctx_setopt + +## NAME + +nng_ctx_setopt --- set context option (deprecated) + +## SYNOPSIS + +```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 [nng_ctx_set()](nng_ctx_set.md). +> They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`. +> They may also be removed entirely in a future version of _NNG_. + +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_. + +- `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 [`nng_duration`](nng_duration.md). + 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 + +- `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 + +[nng_ctx_set](nng_ctx_set.md), +[nng_options](nng_options.md) diff --git a/docs/reference/src/api/index.md b/docs/reference/src/api/index.md index a88c44f1..8bd48a04 100644 --- a/docs/reference/src/api/index.md +++ b/docs/reference/src/api/index.md @@ -10,9 +10,11 @@ the _NNG_ programming interface. We have organized the reference material along general functional areas. They are: +- Messages - Sockets -- Dialers, Listeners, and Pipes - Contexts +- Options +- Dialers, Listeners, and Pipes - [Asynchronous I/O](aio/index.md) - [Asynchronous I/O for Providers](aio_provider/index.md) - [Utility Functions](util/index.md) diff --git a/docs/reference/src/api/msg/index.md b/docs/reference/src/api/msg/index.md new file mode 100644 index 00000000..1a7bdabf --- /dev/null +++ b/docs/reference/src/api/msg/index.md @@ -0,0 +1,96 @@ +# Messages + +Messages in Scalability Protocols are the fundamental unit of transmission +and reception, +as these protocols are fundamentally message-oriented. + +## {{i: Message object}} + +An `nng_msg` represents a single {{i:message}} sent between Scalability Protocols peers. + +Messages have a {{i:body}}, containing the application supplied +payload, and a {{i:header}}, containing protocol specific routing and similar +related information. + +> [!TIP] +> Only applications using [raw](../../overview/raw.md) mode need to +> access the message header. + +### Creating, Destroying and Using + +Messages are allocated using [`nng_msg_alloc()`](nng_msg_alloc.md), +and are deallocated using [`nng_msg_free()`](nng_msg_free.md). + +In addition there are other functions used to access message contents, +including adding data to either the beginning or end of the message, +automatic data conversion, and removing data from the beginning or end. + +### Performance Considerations + +While there are convenience wrappers for sending and receiving arrays of +bytes, using message objects directly when possible will give better +performance by reducing data copies and needless allocations. + +These functions are designed to try to avoid copying message contents +by making use of scratch areas at the beginning and end of the message. +These scratch areas, the "headroom" and "tailroom", are automatically +included when allocating a message. + +### Direct Use Forbidden + +The `nng_msg` structure is opaque, and applications should never try to +rely on the size of it, nor access internal members directly. +This insulates the application from changes in subsequent _NNG_ versions +that would affect the binary representation of the `nng_msg` itself. + +## Examples + +### Example 1: Preparing a message for use + +```c +#include +nng_msg *m; +if (nng_msg_alloc(&m, strlen("content") + 1) != 0) { + // handle error +} +strcpy(nng_msg_body(m), "content"); +``` + +### Example 2: Preallocating message content + +```c +if (nng_msg_alloc(&m, 1024) != 0) { + // handle error +} +while ((val64 = next_datum()) != 0) P + if (nng_msg_append_u64(m, val64) != 0) { + // handle error + } +} +``` + +## See Also + +[nng_aio_get_msg](../aio/nng_aio_get_msg.md), +[nng_aio_set_msg](../aio/nng_aio_set_msg.md), +[nng_msg_alloc](nng_msg_alloc.md), +[nng_msg_append](nng_msg_append.md), +[nng_msg_body](nng_msg_body.md), +[nng_msg_capacity](nng_msg_capacity.md), +[nng_msg_dup](nng_msg_dup.md), +[nng_msg_free](nng_msg_free.md), +[nng_msg_header](nng_msg_header.md), +[nng_msg_header_append](nng_msg_header_append.md), +[nng_msg_header_chop](nng_msg_header_chop.md), +[nng_msg_header_clear](nng_msg_header_clear.md), +[nng_msg_header_insert](nng_msg_header_insert.md), +[nng_msg_header_len](nng_msg_header_len.md), +[nng_msg_header_trim](nng_msg_header_trim.md), +[nng_msg_insert](nng_msg_insert.md), +[nng_msg_len](nng_msg_len.md), +[nng_msg_reserve](nng_msg_reserve.md), +[nng_msg_realloc](nng_msg_realloc.md), +[nng_msg_set_pipe](nng_msg_set_pipe.md), +[nng_msg_trim](nng_msg_trim.md), +[nng_recvmsg](../socket/nng_recvmsg.md), +[nng_sendmsg](../socket/nng_sendmsg.md) diff --git a/docs/reference/src/api/msg/nng_msg_alloc.md b/docs/reference/src/api/msg/nng_msg_alloc.md new file mode 100644 index 00000000..163d193b --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_alloc.md @@ -0,0 +1,40 @@ +# nng_msg_alloc + +## NAME + +nng_msg_alloc --- allocate a message + +## SYNOPSIS + +```c +#include + +int nng_msg_alloc(nng_msg **msgp, size_t size); +``` + +## DESCRIPTION + +The `nng_msg_alloc()` function allocates a new message with body length _size_ +and stores the result in _msgp_. +Messages allocated with this function contain a body and optionally a header. +They are used with receive and transmit functions. + +## RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +## ERRORS + +- `NNG_ENOMEM`: Insufficient free memory exists to allocate a message. + +## SEE ALSO + +[nng_msg_free](nng_msg_free.md), +[nng_msg_body](nng_msg_body.md), +[nng_msg_dup](nng_msg_dup.md), +[nng_msg_header](nng_msg_header.md), +[nng_msg_header_len](nng_msg_header_len.md), +[nng_msg_len](nng_msg_len.md), +[nng_msg_capacity](nng_msg_capacity.md), +[nng_msg_reserve](nng_msg_reserve.md), +[nng_msg_realloc](nng_msg_realloc.md) diff --git a/docs/reference/src/api/msg/nng_msg_append.md b/docs/reference/src/api/msg/nng_msg_append.md new file mode 100644 index 00000000..5807d3a6 --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_append.md @@ -0,0 +1,46 @@ +# nng_msg_append + +## NAME + +nng_msg_append --- append to message body + +## SYNOPSIS + +```c +#include + +int nng_msg_append(nng_msg *msg, const void *val, size_t size); +int nng_msg_append_u16(nng_msg *msg, uint16_t val16); +int nng_msg_append_u32(nng_msg *msg, uint32_t val32); +int nng_msg_append_u64(nng_msg *msg, uint64_t val64); +``` + +## DESCRIPTION + +The `nng_msg_append()` family of functions appends data to +the end of the body of message _msg_, reallocating it if necessary. +The first function appends _size_ bytes, copying them from _val_. +The remaining functions append the value specified (such as _val32_) in +network-byte order (big-endian). + +## RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +## ERRORS + +- `NNG_ENOMEM`: Insufficient free memory exists. + +## SEE ALSO + +[nng_msg_alloc](nng_msg_alloc.md), +[nng_msg_body](nng_msg_body.md), +[nng_msg_capacity](nng_msg_capacity.md), +[nng_msg_chop](nng_msg_chop.md), +[nng_msg_clear](nng_msg_chop.md), +[nng_msg_free](nng_msg_free.md), +[nng_msg_insert](nng_msg_insert.md), +[nng_msg_len](nng_msg_len.md), +[nng_msg_reserve](nng_msg_reserve.md), +[nng_msg_realloc](nng_msg_realloc.md), +[nng_msg_trim](nng_msg_trim.md) diff --git a/docs/reference/src/api/msg/nng_msg_body.md b/docs/reference/src/api/msg/nng_msg_body.md new file mode 100644 index 00000000..abd49c7f --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_body.md @@ -0,0 +1,47 @@ +# nng_msg_body + +## NAME + +nng_msg_body --- return message body + +## SYNOPSIS + +```c +#include + +void *nng_msg_body(nng_msg *msg); +``` + +## DESCRIPTION + +The `nng_msg_body()` function returns a pointer to the start of the body +content of the message _msg_. + +> [!NOTE] +> The value returned by this is invalidated by a call to any of the +> functions that modify the message itself. +> Such functions are +> [`nng_msg_free()`](nng_msg_free.md), +> [`nng_msg_realloc()`](nng_msg_realloc.md), +> any of the [`nng_msg_trim()`](nng_msg_trim.md), +> [`nng_msg_chop()`](nng_msg_chop.md), +> [`nng_msg_append()`](nng_msg_append.md), +> or [`nng_msg_insert()`](nng_msg_insert.md) variants. + +## RETURN VALUES + +Pointer to start of message body. + +## SEE ALSO + +[nng_msg_alloc](nng_msg_alloc.md), +[nng_msg_append](nng_msg_append.md), +[nng_msg_capacity](nng_msg_capacity.md), +[nng_msg_chop](nng_msg_chop.md), +[nng_msg_clear](nng_msg_clear.md), +[nng_msg_free](nng_msg_free.md), +[nng_msg_insert](nng_msg_insert.md), +[nng_msg_len](nng_msg_len.md), +[nng_msg_reserve](nng_msg_reserve.md), +[nng_msg_realloc](nng_msg_realloc.md), +[nng_msg_trim](nng_msg_trim.md) diff --git a/docs/reference/src/api/msg/nng_msg_capacity.md b/docs/reference/src/api/msg/nng_msg_capacity.md new file mode 100644 index 00000000..707a04e3 --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_capacity.md @@ -0,0 +1,30 @@ +# nng_msg_capacity + +## NAME + +nng_msg_capacity --- return message body length + +## SYNOPSIS + +```c +#include + +size_t nng_msg_capacity(nng_msg *msg); +``` + +## DESCRIPTION + +The `nng_msg_capacity()` returns the storage allocated for the body of message _msg_. +The capacity includes the current contents of the message and free space after it. +The message body may grow to capacity without performing any further allocations. + +## RETURN VALUES + +Allocated capacity for message body. + +## SEE ALSO + +[nng_msg_alloc](nng_msg_alloc.md), +[nng_msg_realloc](nng_msg_realloc.md), +[nng_msg_reserve](nng_msg_reserve.md) +[nng_msg_body](nng_msg_body.md) diff --git a/docs/reference/src/api/msg/nng_msg_chop.md b/docs/reference/src/api/msg/nng_msg_chop.md new file mode 100644 index 00000000..fc9a0df5 --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_chop.md @@ -0,0 +1,47 @@ +# nng_msg_chop + +## NAME + +nng_msg_chop --- remove data from end of message body + +## SYNOPSIS + +```c +#include + +int nng_msg_chop(nng_msg *msg, size_t size); +int nng_msg_chop_u16(nng_msg *msg, uint16_t *val16); +int nng_msg_chop_u32(nng_msg *msg, uint32_t *val32); +int nng_msg_chop_u64(nng_msg *msg, uint64_t *val64); +``` + +## DESCRIPTION + +The `nng_msg_chop()` family of functions removes data from +the end of the body of message _msg_. +The first function removes _size_ bytes. +The remaining functions remove 2, 4, or 8 bytes, and stores them in the value +(such as _val32_), +after converting them from network-byte order (big-endian) to native byte order. + +## RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +## ERRORS + +- `NNG_EINVAL`: The message body is too short to remove the requested data. + +## SEE ALSO + +[nng_msg_alloc](nng_msg_alloc.md), +[nng_msg_append](nng_msg_alloc.md), +[nng_msg_body](nng_msg_body.md), +[nng_msg_capacity](nng_msg_capacity.md), +[nng_msg_clear](nng_msg_chop.md), +[nng_msg_free](nng_msg_free.md), +[nng_msg_insert](nng_msg_insert.md), +[nng_msg_len](nng_msg_len.md), +[nng_msg_reserve](nng_msg_reserve.md), +[nng_msg_realloc](nng_msg_realloc.md), +[nng_msg_trim](nng_msg_trim.md) diff --git a/docs/reference/src/api/msg/nng_msg_clear.md b/docs/reference/src/api/msg/nng_msg_clear.md new file mode 100644 index 00000000..af25c072 --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_clear.md @@ -0,0 +1,23 @@ +# nng_msg_clear + +## NAME + +nng_msg_clear --- clear message body content + +## SYNOPSIS + +```c +#include + +void nng_msg_clear(nng_msg *msg); +``` + +## DESCRIPTION + +The `nng_msg_clear()` function resets the body length of _msg_ to zero. + +## SEE ALSO + +[nng_msg_alloc](nng_msg_alloc.md), +[nng_msg_capacity](nng_msg_capacity.md), +[nng_msg_reserve](nng_msg_reserve.md) diff --git a/docs/reference/src/api/msg/nng_msg_dup.md b/docs/reference/src/api/msg/nng_msg_dup.md new file mode 100644 index 00000000..dae376e8 --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_dup.md @@ -0,0 +1,34 @@ +# nng_msg_dup + +## NAME + +nng_msg_dup --- duplicate a message + +## SYNOPSIS + +```c +#include + +int nng_msg_dup(nng_msg **dup, nng_msg_t *orig); +``` + +## DESCRIPTION + +The `nng_msg_dup()` makes a duplicate of the original message _orig_, and +saves the result in the location pointed by _dup_. +The actual message body and header content is copied, +but the duplicate may contain a +different amount of unused space than the original message. + +## RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +## ERRORS + +- `NNG_ENOMEM`: Insufficient free memory exists to duplicate a message. + +## SEE ALSO + +[nng_msg_alloc](nng_msg_alloc.md), +[nng_msg_free](nng_msg_free.md) diff --git a/docs/reference/src/api/msg/nng_msg_free.md b/docs/reference/src/api/msg/nng_msg_free.md new file mode 100644 index 00000000..94887be0 --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_free.md @@ -0,0 +1,22 @@ +# nng_msg_free + +## NAME + +nng_msg_free --- free a message + +## SYNOPSIS + +```c +#include + +void nng_msg_free(nng_msg *msg); +``` + +## DESCRIPTION + +The `nng_msg_free()` function deallocates the message _msg_ entirely. + +## SEE ALSO + +[nng_msg_alloc](nng_msg_alloc.md), +[nng_msg_realloc](nng_msg_realloc.md) diff --git a/docs/reference/src/api/msg/nng_msg_get_pipe.3.adoc b/docs/reference/src/api/msg/nng_msg_get_pipe.3.adoc new file mode 100644 index 00000000..154f4c43 --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_get_pipe.3.adoc @@ -0,0 +1,60 @@ += nng_msg_get_pipe(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_msg_get_pipe - get pipe for message + +== SYNOPSIS + +[source, c] +---- +#include + +nng_pipe nng_msg_get_pipe(nng_msg *msg); +---- + +== DESCRIPTION + +The `nng_msg_get_pipe()` returns the xref:nng_pipe.5.adoc[`nng_pipe`] object +associated with message _msg_. +On receive, this is the pipe from which a message was received. +On transmit, this would be the pipe that the message should be delivered +to, if a specific peer is required. + +NOTE: Not all protocols support overriding the destination pipe. + +The most usual use case for this is to obtain information about the peer +from which the message was received. +This can be used to provide different behaviors for different peers, such as +a higher level of authentication for peers located on an untrusted network. +The xref:nng_pipe_getopt.3.adoc[`nng_pipe_getopt()`] function +is useful in this situation. + + +== RETURN VALUES + +This function returns the pipe associated with this message, which will +be a positive value. +If the pipe is non-positive, then that indicates that +no specific pipe is associated with the message. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_set_pipe.3.adoc[nng_msg_set_pipe(3)], +xref:nng_pipe_getopt.3.adoc[nng_pipe_getopt(3)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/api/msg/nng_msg_header.3.adoc b/docs/reference/src/api/msg/nng_msg_header.3.adoc new file mode 100644 index 00000000..eac45ffd --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_header.3.adoc @@ -0,0 +1,58 @@ += nng_msg_header(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_msg_header - return message header + +== SYNOPSIS + +[source, c] +---- +#include + +void *nng_msg_header(nng_msg *msg); +---- + +== DESCRIPTION + +The `nng_msg_header()` function returns a pointer to the start of the header +content of the message _msg_. + +NOTE: The message header contains protocol-specific header content. Most +applications should not need to access this content, but it is available +for raw mode sockets (set with the +xref:nng_options.5.adoc#NNG_OPT_RAW[`NNG_OPT_RAW`] option.) + +NOTE: The value returned by this is invalidated by a call to any of the +functions that modify the message or the header content. + +== RETURN VALUES + +Pointer to start of message header. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_body.3.adoc[nng_msg_body(3)], +xref:nng_msg_free.3.adoc[nng_msg_free(3)], +xref:nng_msg_header_append.3.adoc[nng_msg_header_append(3)], +xref:nng_msg_header_chop.3.adoc[nng_msg_header_chop(3)], +xref:nng_msg_header_insert.3.adoc[nng_msg_header_insert(3)] +xref:nng_msg_header_len.3.adoc[nng_msg_header_len(3)], +xref:nng_msg_header_trim.3.adoc[nng_msg_header_trim(3)], +xref:nng_msg.5.adoc[nng_msg(5)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/api/msg/nng_msg_header_append.3.adoc b/docs/reference/src/api/msg/nng_msg_header_append.3.adoc new file mode 100644 index 00000000..16badf0b --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_header_append.3.adoc @@ -0,0 +1,58 @@ += nng_msg_header_append(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_msg_header_append - append to message header + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_msg_header_append(nng_msg *msg, const void *val, size_t size); +int nng_msg_header_append_u16(nng_msg *msg, uint16_t val16); +int nng_msg_header_append_u32(nng_msg *msg, uint32_t val32); +int nng_msg_header_append_u64(nng_msg *msg, uint64_t val64); +---- + +== DESCRIPTION + +The `nng_msg_header_append()` family of functions appends data to +the end of the headers of message _msg_, reallocating it if necessary. +The first function appends _size_ bytes, copying them from _val_. + +The remaining functions append the value (such as _val32_) in +network-byte order (big-endian). + + +== RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists. + +== SEE ALSO + +[.text-left] +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_header.3.adoc[nng_msg_header(3)], +xref:nng_msg_header_chop.3.adoc[nng_msg_header_chop(3)], +xref:nng_msg_header_insert.3.adoc[nng_msg_header_insert(3)], +xref:nng_msg_header_len.3.adoc[nng_msg_header_len(3)], +xref:nng_msg_header_trim.3.adoc[nng_msg_header_trim(3)], +xref:nng_msg_free.3.adoc[nng_msg_free(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/api/msg/nng_msg_header_chop.3.adoc b/docs/reference/src/api/msg/nng_msg_header_chop.3.adoc new file mode 100644 index 00000000..454e9e51 --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_header_chop.3.adoc @@ -0,0 +1,58 @@ += nng_msg_header_chop(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_msg_header_chop - remove data from end of message header + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_msg_header_chop(nng_msg *msg, size_t size); +int nng_msg_header_chop_u16(nng_msg *msg, uint16_t *val16); +int nng_msg_header_chop_u32(nng_msg *msg, uint32_t *val32); +int nng_msg_header_chop_u64(nng_msg *msg, uint64_t *val64); +---- + +== DESCRIPTION + +The `nng_msg_header_chop()` family of functions removes +data from the end of the header of message _msg_. +The first function removes _size_ bytes. +The remaining functions remove 2, 4, or 8 bytes, and stores them in the value +(such as _val32_), +after converting them from network-byte order (big-endian) to native +byte order. + +== RETURN VALUES + +These function return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_EINVAL`:: The message header is too short to remove the requested data. + +== SEE ALSO + +[.text-left] +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_header.3.adoc[nng_msg_header(3)], +xref:nng_msg_header_append.3.adoc[nng_msg_header_append(3)], +xref:nng_msg_header_insert.3.adoc[nng_msg_header_insert(3)], +xref:nng_msg_header_len.3.adoc[nng_msg_header_len(3)], +xref:nng_msg_header_trim.3.adoc[nng_msg_header_trim(3)], +xref:nng_msg_free.3.adoc[nng_msg_free(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/api/msg/nng_msg_header_clear.3.adoc b/docs/reference/src/api/msg/nng_msg_header_clear.3.adoc new file mode 100644 index 00000000..d00286ed --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_header_clear.3.adoc @@ -0,0 +1,42 @@ += nng_msg_header_clear(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_msg_header_clear - clear message header + +== SYNOPSIS + +[source, c] +---- +#include + +void nng_msg_header_clear(nng_msg *msg); +---- + +== DESCRIPTION + +The `nng_msg_clear()` function resets the header length of _msg_ to zero. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_free.3.adoc[nng_msg_free(3)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/api/msg/nng_msg_header_insert.3.adoc b/docs/reference/src/api/msg/nng_msg_header_insert.3.adoc new file mode 100644 index 00000000..a2bf0d63 --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_header_insert.3.adoc @@ -0,0 +1,60 @@ += nng_msg_header_insert(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_msg_header_insert - prepend to message header + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_msg_header_insert(nng_msg *msg, const void *val, size_t size); +int nng_msg_header_insert_u16(nng_msg *msg, uint16_t val16); +int nng_msg_header_insert_u32(nng_msg *msg, uint32_t val32); +int nng_msg_header_insert_u64(nng_msg *msg, uint64_t val64); +---- + +== DESCRIPTION + +The `nng_msg_header_insert()` family of functions +prepends data to the front of the headers of message _msg_, reallocating +if necessary. +The first function prepends _size_ bytes, copying them from _val_. +The remaining functions prepend the specified value (such as _val32_) in +network-byte order (big-endian). + +== RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists. + +== SEE ALSO + +[.text-left] +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_header.3.adoc[nng_msg_header(3)], +xref:nng_msg_header_append.3.adoc[nng_msg_header_append(3)], +xref:nng_msg_header_chop.3.adoc[nng_msg_header_chop(3)], +xref:nng_msg_header_len.3.adoc[nng_msg_header_len(3)], +xref:nng_msg_header_trim.3.adoc[nng_msg_header_trim(3)], +xref:nng_msg_free.3.adoc[nng_msg_free(3)], +xref:nng_msg_capacity.3.adoc[nng_msg_capacity(3)], +xref:nng_msg_reserve.3.adoc[nng_msg_reserve(3)], +xref:nng_msg_realloc.3.adoc[nng_msg_realloc(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/api/msg/nng_msg_header_len.3.adoc b/docs/reference/src/api/msg/nng_msg_header_len.3.adoc new file mode 100644 index 00000000..0a7b3613 --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_header_len.3.adoc @@ -0,0 +1,43 @@ += nng_msg_header_len(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_msg_header_len - return message header length + +== SYNOPSIS + +[source, c] +---- +#include + +size_t nng_msg_header_len(nng_msg *msg); +---- + +== DESCRIPTION + +The `nng_msg_header_len()` returns the length of message header of _msg_. + +== RETURN VALUES + +Length of message header. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_header.3.adoc[nng_msg_header(3)], +xref:nng_msg.5.adoc[nng_msg(5)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/api/msg/nng_msg_header_trim.3.adoc b/docs/reference/src/api/msg/nng_msg_header_trim.3.adoc new file mode 100644 index 00000000..6df504ff --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_header_trim.3.adoc @@ -0,0 +1,59 @@ += nng_msg_header_trim(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_msg_header_trim - remove data from start of message header + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_msg_header_trim(nng_msg *msg, size_t size); +int nng_msg_header_trim_u16(nng_msg *msg, uint16_t *val16); +int nng_msg_header_trim_u32(nng_msg *msg, uint32_t *val32); +int nng_msg_header_trim_u64(nng_msg *msg, uint64_t *val64); +---- + +== DESCRIPTION + +The `nng_msg_header_trim()` family of functions remove +data from the start of the header of message _msg_. +The first function removes _size_ bytes. +The remaining functions removes 2, 4, or 8 bytes, and stores them in the +value (such as _val32_), +after converting them from network-byte order (big-endian) to native +byte order. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_EINVAL`:: The message header is too short to remove the requested data. + +== SEE ALSO + +[.text-left] +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_header.3.adoc[nng_msg_header(3)], +xref:nng_msg_header_append.3.adoc[nng_msg_header_append(3)], +xref:nng_msg_header_chop.3.adoc[nng_msg_header_chop(3)], +xref:nng_msg_header_insert.3.adoc[nng_msg_header_insert(3)], +xref:nng_msg_header_len.3.adoc[nng_msg_header_len(3)], +xref:nng_msg_free.3.adoc[nng_msg_free(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_msg.5.adoc[nng_msg(5)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/api/msg/nng_msg_insert.3.adoc b/docs/reference/src/api/msg/nng_msg_insert.3.adoc new file mode 100644 index 00000000..25f98fce --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_insert.3.adoc @@ -0,0 +1,63 @@ += nng_msg_insert(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_msg_insert - prepend to message body + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_msg_insert(nng_msg *msg, const void *val, size_t size); +int nng_msg_insert_u16(nng_msg *msg, uint16_t val16); +int nng_msg_insert_u32(nng_msg *msg, uint32_t val32); +int nng_msg_insert_u64(nng_msg *msg, uint64_t val64); +---- + +== DESCRIPTION + +The `nng_msg_insert()` family of functions prepends data to +the front of the body of message _msg_, reallocating it if necessary. +The first function prepends _size_ bytes, copying them from _val_. +The remaining functions prepend the specified value (such as _val32_) +in network-byte order (big-endian). + +TIP: These functions make use of space pre-allocated in front of the +message body if available, so they can often avoid performing any reallocation. +Applications should use these instead of reallocating and copying message +content themselves, in order to benefit from this capability. + +== RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists. + +== SEE ALSO + +[.text-left] +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_append.3.adoc[nng_msg_append(3)], +xref:nng_msg_body.3.adoc[nng_msg_body(3)], +xref:nng_msg_chop.3.adoc[nng_msg_chop(3)], +xref:nng_msg_free.3.adoc[nng_msg_free(3)], +xref:nng_msg_len.3.adoc[nng_msg_len(3)], +xref:nng_msg_realloc.3.adoc[nng_msg_realloc(3)], +xref:nng_msg_trim.3.adoc[nng_msg_trim(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_msg.5.adoc[nng_msg(5)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/api/msg/nng_msg_len.3.adoc b/docs/reference/src/api/msg/nng_msg_len.3.adoc new file mode 100644 index 00000000..2a3dfe67 --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_len.3.adoc @@ -0,0 +1,43 @@ += nng_msg_len(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_msg_len - return message body length + +== SYNOPSIS + +[source, c] +---- +#include + +size_t nng_msg_len(nng_msg *msg); +---- + +== DESCRIPTION + +The `nng_msg_len()` returns the length of the body of message _msg_. + +== RETURN VALUES + +Length of message body. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_body.3.adoc[nng_msg_body(3)], +xref:nng_msg.5.adoc[nng_msg(5)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/api/msg/nng_msg_realloc.3.adoc b/docs/reference/src/api/msg/nng_msg_realloc.3.adoc new file mode 100644 index 00000000..bf407289 --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_realloc.3.adoc @@ -0,0 +1,66 @@ += nng_msg_realloc(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_msg_realloc - reallocate a message + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_msg_realloc(nng_msg *msg, size_t size); +---- + +== DESCRIPTION + +The `nng_msg_realloc()` function re-allocates a message so that it has +a body of length _size_. +This message attempts to avoid extra allocations, +and will reuse the existing memory when possible. + +TIP: `nng_msg_realloc` is suitable for creating space for direct writing of data. +When appending many small pieces of data to a message using xref:nng_msg_append.3.adoc[`nng_msg_append()`], +allocations may be reduced by first using xref:nng_msg_reserve.3.adoc[`nng_msg_reserve()`] +to create sufficient space. +In any case, reallocating or appending to a message is guaranteed to succeed if the resulting +body length is less than xref:nng_msg_capacity.3.adoc[`nng_msg_capacity()`]. + +NOTE: Pointers to message body and header content obtained prior to this +function must not be in use, as the underlying memory used for the message +may have changed, particularly if the message size is increasing. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists to reallocate a message. + +== SEE ALSO + +[.text-left] +xref:nng_msg_reserve.3.adoc[nng_msg_reserve(3)], +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_append.3.adoc[nng_msg_append(3)], +xref:nng_msg_body.3.adoc[nng_msg_body(3)], +xref:nng_msg_chop.3.adoc[nng_msg_chop(3)], +xref:nng_msg_free.3.adoc[nng_msg_free(3)], +xref:nng_msg_insert.3.adoc[nng_msg_insert(3)], +xref:nng_msg_len.3.adoc[nng_msg_len(3)], +xref:nng_msg_trim.3.adoc[nng_msg_trim(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_msg.5.adoc[nng_msg(5)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/api/msg/nng_msg_reserve.3.adoc b/docs/reference/src/api/msg/nng_msg_reserve.3.adoc new file mode 100644 index 00000000..254c1e94 --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_reserve.3.adoc @@ -0,0 +1,63 @@ += nng_msg_reserve(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_msg_reserve - reserve storage for a message + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_msg_reserve(nng_msg *msg, size_t capacity); +---- + +== DESCRIPTION + +The `nng_msg_reserve()` function ensures a message has allocated enough storage +to accommodate a body of the given length. +This message attempts to avoid extra allocations, +and will reuse the existing memory when possible. + +TIP: Using this message before xref:nng_msg_append.3.adoc[`nng_msg_append()`] +will prevent additional memory allocations until the message's length exceeds +the alotted capacity. + +NOTE: Pointers to message body and header content obtained prior to this +function must not be in use, as the underlying memory used for the message +may have changed, particularly if the message capacity is increasing. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists to reallocate a message. + +== SEE ALSO + +[.text-left] +xref:nng_msg_capacity.3.adoc[nng_msg_capacity(3)], +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_append.3.adoc[nng_msg_append(3)], +xref:nng_msg_body.3.adoc[nng_msg_body(3)], +xref:nng_msg_chop.3.adoc[nng_msg_chop(3)], +xref:nng_msg_free.3.adoc[nng_msg_free(3)], +xref:nng_msg_insert.3.adoc[nng_msg_insert(3)], +xref:nng_msg_len.3.adoc[nng_msg_len(3)], +xref:nng_msg_trim.3.adoc[nng_msg_trim(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_msg.5.adoc[nng_msg(5)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/api/msg/nng_msg_set_pipe.3.adoc b/docs/reference/src/api/msg/nng_msg_set_pipe.3.adoc new file mode 100644 index 00000000..c95cc83f --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_set_pipe.3.adoc @@ -0,0 +1,50 @@ += nng_msg_set_pipe(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_msg_set_pipe - set pipe for message + +== SYNOPSIS + +[source, c] +---- +#include + +void nng_msg_set_pipe(nng_msg *msg, nng_pipe p); +---- + +== DESCRIPTION + +The `nng_msg_set_pipe()` sets the pipe associated with message _m_ to _p_. +This is most often useful when used with protocols that support directing +a message to a specific peer. +For example the xref:nng_pair.7.adoc[_pair_] version 1 protocol can do +this when `NNG_OPT_PAIR1_POLY` mode is set. + +NOTE: Not all protocols support overriding the destination pipe. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], +xref:nng_msg_get_pipe.3.adoc[nng_msg_get_pipe(3)], +xref:nng_pipe_getopt.3.adoc[nng_pipe_getopt(3)], +xref:nng_msg.5.adoc[nng_msg(5)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/api/msg/nng_msg_trim.md b/docs/reference/src/api/msg/nng_msg_trim.md new file mode 100644 index 00000000..c0b8f694 --- /dev/null +++ b/docs/reference/src/api/msg/nng_msg_trim.md @@ -0,0 +1,48 @@ +# nng_msg_trim + +## NAME + +nng_msg_trim --- remove data from start of message body + +## SYNOPSIS + +```c +#include + +int nng_msg_trim(nng_msg *msg, size_t size); +int nng_msg_trim_u16(nng_msg *msg, uint16_t *val16); +int nng_msg_trim_u32(nng_msg *msg, uint32_t *val32); +int nng_msg_trim_u64(nng_msg *msg, uint64_t *val64); +``` + +## DESCRIPTION + +The `nng_msg_trim()` family of functions removes data from +the start of the body of message _msg_. +The first function removes _size_ bytes. +The remaining functions remove 2, 4, or 8 bytes, and stores them in the value +(such as _val32_), +after converting them from network-byte order (big-endian) to native +byte order. + +## RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +## ERRORS + +- `NNG_EINVAL`: The message body is too short to remove the requested data. + +## SEE ALSO + +[nng_msg_alloc](nng_msg_alloc.md), +[nng_msg_append](nng_msg_alloc.md), +[nng_msg_body](nng_msg_body.md), +[nng_msg_capacity](nng_msg_capacity.md), +[nng_msg_chop](nng_msg_chop.md) +[nng_msg_clear](nng_msg_chop.md), +[nng_msg_free](nng_msg_free.md), +[nng_msg_insert](nng_msg_insert.md), +[nng_msg_len](nng_msg_len.md), +[nng_msg_reserve](nng_msg_reserve.md), +[nng_msg_realloc](nng_msg_realloc.md) diff --git a/docs/reference/src/api/nng_ctx.md b/docs/reference/src/api/nng_ctx.md deleted file mode 100644 index 9f963e9a..00000000 --- a/docs/reference/src/api/nng_ctx.md +++ /dev/null @@ -1,160 +0,0 @@ -# nng_ctx - -## NAME - -nng_ctx --- protocol context - -## SYNOPSIS - -```c -#include - -typedef struct nng_ctx_s nng_ctx -``` - -## DESCRIPTION - -An `nng_ctx`{{hi:context}} is a handle to an underlying context object, -which keeps the protocol state for some stateful protocols. -The purpose of a separate context object is to permit applications to -share a single [socket](nng_socket.md), with its various underlying -[dialers](nng_dialer.md), -[listeners](nng_listener.md), -[pipes](nng_pipe.md), -while still benefiting from separate state tracking. - -For example, a [_REQ_](../protocols/req.md) context will contain the request ID -of any sent request, a timer to retry the request on failure, and so forth. -A separate context on the same socket can have similar data, but corresponding -to a completely different request. - -> [!NOTE] -> The `nng_ctx` structure is always passed by value (both -> for input parameters and return values), and should be treated opaquely. -> Passing structures this way gives the compiler a chance to perform -> accurate type checks in functions passing values of this type. - -All contexts share the same socket, and so some options, as well as the -underlying transport details, will be common to all contexts on that socket. - -Protocols that make use of contexts will also have a default context -that is used when the socket global operations are used. -Operations using the global context will generally not interfere with -any other contexts, except that certain socket options may affect socket -global behavior. - -{{hi:concurrent}}{{hi:raw mode}} -Historically, applications wanting to use a stateful protocol concurrently -would have to resort to [raw mode](../overview/raw.md) sockets, which bypasses -much of the various protocol handling, leaving it to up to the application -to do so. -Contexts make it possible to still benefit from advanced protocol handling, -including timeouts, retries, and matching requests to responses, while doing so -concurrently. - -> [!TIP] -> Contexts are an excellent mechanism to use when building concurrent -> applications, and should be used in lieu of -> [raw mode](../overview/raw.md) sockets when possible. - -## Caveats - -Not every protocol supports separate contexts. -See the protocol-specific documentation for further details about whether -contexts are supported, and details about what options are supported for -contexts. - -Use of file descriptor polling (with descriptors obtained using the -[`NNG_OPT_RECVFD`](nng_options.md#NNG_OPT_RECVFD) or -[`NNG_OPT_SENDFD`](nng_options.md#NNG_OPT_SENDFD) options) while contexts -are in use on the same socket is not supported, and may lead to unpredictable -behavior. These asynchronous methods should not be mixed on the same socket. - -[Raw mode](../overview/raw.md) sockets do not support contexts, since -there is generally no state tracked for them, and thus contexts make no sense. - -## Initialization - -A context may be initialized using the macro `NNG_CTX_INITIALIZER` -before it is opened, to prevent confusion with valid open contexts. - -## Example - -The following program fragment demonstrates the use of contexts to implement -a concurrent [_REP_](../protocols/rep.md) service that simply echos messages back -to the sender. - -```c -struct echo_context { - nng_ctx ctx; - nng_aio *aio; - enum { INIT, RECV, SEND } state; -}; - -void -echo(void *arg) -{ - struct echo_context *ec = arg; - - switch (ec->state) { - case INIT: - ec->state = RECV; - nng_ctx_recv(ec->ctx, ec->aio); - return; - case RECV: - if (nng_aio_result(ec->aio) != 0) { - // ... handle error - } - // We reuse the message on the ec->aio - ec->state = SEND; - nng_ctx_send(ec->ctx, ec->aio); - return; - case SEND: - if (nng_aio_result(ec->aio) != 0) { - // ... handle error - } - ec->state = RECV; - nng_ctx_recv(ec->ctx, ec->aio); - return; - } -} -``` - -Given the above fragment, the following example shows setting up the -service. It assumes that the [socket](nng_socket.md) has already been -created and any transports set up as well with functions such as -[`nng_dial()`](nng_dial.md) or [`nng_listen()`](nng_listen.md). - -```c -#define CONCURRENCY 1024 - -echo_context ecs[CONCURRENCY]; - -void -start_echo_service(nng_socket rep_socket) -{ - for (int i = 0; i < CONCURRENCY; i++) { - // error checks elided for clarity - nng_ctx_open(ec[i].ctx, rep_socket) - nng_aio_alloc(ec[i].aio, echo, &e[i]); - ec[i].state = INIT; - echo(&ec[i]); // start it running - } -} -``` - -## SEE ALSO - -[nng_ctx_close()](nng_ctx_close.md), -[nng_ctx_open()](nng_ctx_open.md), -[nng_ctx_get()](nng_ctx_get.md), -[nng_ctx_id()](nng_ctx_id.md) -[nng_ctx_recv()](nng_ctx_recv.md), -[nng_ctx_recvmsg()](nng_ctx_recvmsg.md), -[nng_ctx_send()](nng_ctx_send.md), -[nng_ctx_sendmsg()](nng_ctx_sendmsg.md), -[nng_ctx_set()](nng_ctx_set.md), -[nng_dialer](nng_dialer.md), -[nng_listener](nng_listener.md), -[nng_socket](nng_socket.md), -[nng_options](nng_options.md) diff --git a/docs/reference/src/api/nng_ctx_close.md b/docs/reference/src/api/nng_ctx_close.md deleted file mode 100644 index 443df76e..00000000 --- a/docs/reference/src/api/nng_ctx_close.md +++ /dev/null @@ -1,42 +0,0 @@ -# nng_ctx_close() - -## NAME - -nng_ctx_close --- close context - -## SYNOPSIS - -```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 [`nng_close()`](nng_close.md)) also closes this context. - -## RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_ECLOSED`: The context _ctx_ is already closed or was never opened. - -## SEE ALSO - -[nng_close()](nng_close.md), -[nng_ctx_open()](nng_ctx_open.md), -[nng_ctx](nng_ctx.md), diff --git a/docs/reference/src/api/nng_ctx_get.md b/docs/reference/src/api/nng_ctx_get.md deleted file mode 100644 index 0c2d131c..00000000 --- a/docs/reference/src/api/nng_ctx_get.md +++ /dev/null @@ -1,113 +0,0 @@ -# nng_ctx_get() - -## NAME - -nng_ctx_get --- get context option - -## SYNOPSIS - -```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 - -{{hi:options, context}} -The `nng_ctx_get()` functions are used to retrieve option values for -the [context](nng_ctx.md) _ctx_. -The actual options that may be retrieved in this way vary. -A number of them are documented in [nng_options](nng_options.md). - -> [!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. - -- `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 [durations](nng_duration.md) - (such as timeouts), stored in _durp_ as a number of milliseconds. - (The special value {{i:`NNG_DURATION_INFINITE`}} means an infinite amount of time, and - the special value {{i:`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 [`nng_strdup()`](nng_strdup.md) - and consequently must be freed by the caller using - [`nng_strfree()`](nng_strfree.md) 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 - -- `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 - -[nng_ctx_set()](nng_ctx_set.md), -[nng_strdup()](nng_strdup.md), -[nng_strfree()](nng_strfree.md), -[nng_duration](nng_duration.md), -[nng_ctx](nng_ctx.md), -[nng_options](nng_options.md) diff --git a/docs/reference/src/api/nng_ctx_getopt.md b/docs/reference/src/api/nng_ctx_getopt.md deleted file mode 100644 index ddd6f791..00000000 --- a/docs/reference/src/api/nng_ctx_getopt.md +++ /dev/null @@ -1,117 +0,0 @@ -# nng_ctx_getopt() - -## NAME - -nng_ctx_getopt --- get context option (deprecated) - -## SYNOPSIS - -```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 [nng_ctx_get](nng_ctx_get.md). -> They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`. -> They may also be removed entirely in a future version of _NNG_. - -The `nng_ctx_getopt()` functions are used to retrieve option values for -the [context](nng_ctx.md) _ctx_. -The actual options that may be retrieved in this way vary. - -> [!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. - -- `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 [durations](nng_duration.md) - (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 `nng_strdup()`](nng_strdup.md) - and consequently must be freed by the caller using - [`nng_strfree()`](nng_strfree.md) 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 - -- `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 - -[nng_strdup()](nng_strdup.md), -[nng_strfree()](nng_strfree.md), -[nng_duration](nng_duration.md), -[nng_ctx](nng_ctx.md), -[nng_options](nng_options.md) diff --git a/docs/reference/src/api/nng_ctx_id.md b/docs/reference/src/api/nng_ctx_id.md deleted file mode 100644 index 07af4c4b..00000000 --- a/docs/reference/src/api/nng_ctx_id.md +++ /dev/null @@ -1,35 +0,0 @@ -# nng_ctx_id() - -## NAME - -nng_ctx_id --- return numeric context identifier - -## SYNOPSIS - -```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 -> [`nng_ctx_open()`](nng_ctx_open.md) function. -> Contexts that are allocated on the stack or statically should be -> initialized with the macro `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. - -## SEE ALSO - -[nng_ctx](nng_ctx) diff --git a/docs/reference/src/api/nng_ctx_open.md b/docs/reference/src/api/nng_ctx_open.md deleted file mode 100644 index 521da916..00000000 --- a/docs/reference/src/api/nng_ctx_open.md +++ /dev/null @@ -1,57 +0,0 @@ -# nng_ctx_open() - -## NAME - -nng_ctx_open --- create context - -## SYNOPSIS - -```c -#include - -int nng_ctx_open(nng_ctx *ctxp, nng_socket s); -``` - -## DESCRIPTION - -The `nng_ctx_open()` function creates a separate {{i: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 -[_REP_](../protocols/rep.md) -socket can each receive requests, and send replies to them, without any -regard to or interference with each other. - -> [!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 -> {{hi:raw mode}}[raw mode](../overview/raw.md) sockets. - -> [!NOTE] -> Use of contexts with [raw mode](../overview/raw.md) sockets is -> nonsensical, and not supported. - -## RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -## ERRORS - -- `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 - -[nng_ctx_close()](nng_ctx_close.md), -[nng_ctx_get()](nng_ctx_get.md), -[nng_ctx_recv()](nng_ctx_recv.md), -[nng_ctx_send()](nng_ctx_send.md), -[nng_ctx_set()](nng_ctx_set.md), -[nng_ctx](nng_ctx.md) diff --git a/docs/reference/src/api/nng_ctx_recv.md b/docs/reference/src/api/nng_ctx_recv.md deleted file mode 100644 index d9aaae0f..00000000 --- a/docs/reference/src/api/nng_ctx_recv.md +++ /dev/null @@ -1,61 +0,0 @@ -# nng_ctx_recv() - -## NAME - -nng_ctx_recv --- receive message using context asynchronously - -## SYNOPSIS - -```c -#include - -void nng_ctx_recv(nng_ctx ctx, nng_aio *aio); -``` - -## DESCRIPTION - -The `nng_ctx_recv()` receives a [message](nng_msg.md) using the -[context](nng_ctx.md) _s_ asynchronously. - -When a message is successfully received by the context, it is -stored in the _aio_ by an internal call equivalent to -[`nng_aio_set_msg()`](nng_aio_set_msg.md), then the completion -callback on the _aio_ is executed. -In this case, [`nng_aio_result()`](nng_aio_result.md) 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 [`nng_aio_result()`](nng_aio_result.md) will be non-zero. - -> [!TIP] -> The semantics of what receiving a message means varies from protocol to -> protocol, so examination of the protocol documentation is encouraged. - -## ERRORS - -The following errors may be set on the _aio_, if the operation fails. - -- `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 - -[nng_aio_get_msg()](nng_aio_get_msg.md), -[nng_aio_set_msg()](nng_aio_set_msg.md), -[nng_msg_alloc()](nng_msg_alloc.md), -[nng_msg_free()](nng_msg_free.md), -[nng_aio](nng_aio.md), -[nng_ctx](nng_ctx.md), -[nng_msg](nng_msg.md) diff --git a/docs/reference/src/api/nng_ctx_recvmsg.md b/docs/reference/src/api/nng_ctx_recvmsg.md deleted file mode 100644 index 84368f76..00000000 --- a/docs/reference/src/api/nng_ctx_recvmsg.md +++ /dev/null @@ -1,51 +0,0 @@ -# nng_ctx_recvmsg() - -## NAME - -nng_ctx_recvmsg --- receive message using socket - -## SYNOPSIS - -```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. - -> [!TIP] -> 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 - -- `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 - -[nng_msg_free()](nng_msg_free.md), -[nng_ctx_open()](nng_ctx_open.md), -[nng_ctx_recv()](nng_ctx_recv.md), -[nng_ctx_sendmsg()](nng_ctx_sendmsg.md), -[nng_ctx](nng_ctx) diff --git a/docs/reference/src/api/nng_ctx_send.md b/docs/reference/src/api/nng_ctx_send.md deleted file mode 100644 index dcf839c0..00000000 --- a/docs/reference/src/api/nng_ctx_send.md +++ /dev/null @@ -1,69 +0,0 @@ -# nng_ctx_send() - -## NAME - -nng_ctx_send --- send message using context asynchronously - -## SYNOPSIS - -```c -#include - -void nng_ctx_send(nng_ctx ctx, nng_aio *aio); -``` - -## DESCRIPTION - -The `nng_ctx_send()` sends a [message](nng_msg.md) using the -[context](nng_ctx.md) _ctx_ asynchronously. - -The message to send must have previously been set on the _aio_ -using the [`nng_aio_set_msg()`](nng_aio_set_msg.md) 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 [`nng_aio_result()`](nng_aio_result.md) -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 -[`nng_aio_result()`](nng_aio_result.md) will return a non-zero error status. -In this case, the callback has a responsibility to retrieve the message from -the _aio_ with [`nng_aio_get_msg()`](nng_aio_get_msg.md) and dispose of -it appropriately. -(This may include retrying the send operation on the same or a different -socket, or deallocating the message with [`nng_msg_free()`](nng_msg_free.md). - -> [!TIP] -> The semantics of what sending a message means varies from protocol to -> protocol, so examination of the protocol documentation is encouraged. - -## ERRORS - -- `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 - -[nng_aio_get_msg()](nng_aio_get_msg.md), -[nng_aio_set_msg()](nng_aio_set_msg.md), -[nng_ctx_sendmsg()](nng_ctx_sendmsg.md), -[nng_msg_alloc()](nng_msg_alloc.md), -[nng_msg_alloc()](nng_msg_free.md), -[nng_aio](nng_aio.md), -[nng_ctx](nng_ctx), -[nng_msg](nng_msg) diff --git a/docs/reference/src/api/nng_ctx_sendmsg.md b/docs/reference/src/api/nng_ctx_sendmsg.md deleted file mode 100644 index 5c36837c..00000000 --- a/docs/reference/src/api/nng_ctx_sendmsg.md +++ /dev/null @@ -1,70 +0,0 @@ -# nng_ctx_sendmsg() - -## NAME - -nng_ctx_sendmsg --- send message using context - -## SYNOPSIS - -```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. - -> [!TIP] -> 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 - -- `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 - -[nng_ctx_send()](nng_ctx_send.md), -[nng_msg_alloc()](nng_msg_alloc.md), -[nng_msg_alloc()](nng_msg_free.md), -[nng_ctx](nng_ctx), -[nng_msg](nng_msg) diff --git a/docs/reference/src/api/nng_ctx_set.md b/docs/reference/src/api/nng_ctx_set.md deleted file mode 100644 index 13692c14..00000000 --- a/docs/reference/src/api/nng_ctx_set.md +++ /dev/null @@ -1,95 +0,0 @@ -# nng_ctx_set() - -## NAME - -nng_ctx_set --- set context option - -## SYNOPSIS - -```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 - -{{hi: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_. - -- `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 [`nng_duration`](nng_duration.md). - 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 - -- `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 - -[nng_ctx_get()](nng_ctx_get), -[nng_socket_set()](nng_socket_get), -[nng_ctx](nng_ctx), -[nng_options](nng_options) diff --git a/docs/reference/src/api/nng_ctx_setopt.md b/docs/reference/src/api/nng_ctx_setopt.md deleted file mode 100644 index 6bf7261a..00000000 --- a/docs/reference/src/api/nng_ctx_setopt.md +++ /dev/null @@ -1,99 +0,0 @@ -# nng_ctx_setopt() - -## NAME - -nng_ctx_setopt --- set context option (deprecated) - -## SYNOPSIS - -```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 [nng_ctx_set()](nng_ctx_set.md). -> They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`. -> They may also be removed entirely in a future version of _NNG_. - -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_. - -- `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 [`nng_duration`](nng_duration.md). - 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 - -- `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 - -[nng_ctx_set()](nng_ctx_set.md), -[nng_ctx](nng_ctx.md), -[nng_options](nng_options.md) diff --git a/docs/reference/src/api/socket/index.md b/docs/reference/src/api/socket/index.md index 8bd82b7d..f5f3783c 100644 --- a/docs/reference/src/api/socket/index.md +++ b/docs/reference/src/api/socket/index.md @@ -2,6 +2,6 @@ ## See Also -[nng_bus_open()](nng_bus_open.md) -[nng_close()](nng_close.md) -[nng_pub_open()](nng_pub_open.md) +[nng_bus_open](nng_bus_open.md) +[nng_close](nng_close.md) +[nng_pub_open](nng_pub_open.md) diff --git a/docs/reference/src/api/socket/nng_bus_open.md b/docs/reference/src/api/socket/nng_bus_open.md index fd56455b..5ec526b9 100644 --- a/docs/reference/src/api/socket/nng_bus_open.md +++ b/docs/reference/src/api/socket/nng_bus_open.md @@ -1,8 +1,8 @@ -# nng_bus_open() +# nng_bus_open ## NAME -nng_bus_open --- create _BUS_ socket +nng*bus_open --- create \_BUS* socket ## SYNOPSIS @@ -18,10 +18,10 @@ int nng_bus0_open_raw(nng_socket *s); ## DESCRIPTION The `nng_bus0_open()` function creates a [_BUS_](../../protocols/bus.md) version 0 -[socket](nng_socket.md) and returns it at the location pointed to by _s_. +[socket](index.md) and returns it at the location pointed to by _s_. The `nng_bus0_open_raw()` function creates a [_BUS_](../../protocols/bus.md) version 0 -[socket](nng_socket.md) in +[socket](index.md) in [raw](../overview/raw.md) mode, and returns it at the location pointed to by _s_. ## RETURN VALUES diff --git a/docs/reference/src/api/socket/nng_close.md b/docs/reference/src/api/socket/nng_close.md index 486cfe2c..fded0357 100644 --- a/docs/reference/src/api/socket/nng_close.md +++ b/docs/reference/src/api/socket/nng_close.md @@ -1,4 +1,4 @@ -# nng_close(3) +# nng_close ## NAME @@ -39,7 +39,3 @@ This function returns 0 on success, and non-zero otherwise. ## ERRORS - `NNG_ECLOSED`: The socket _s_ is already closed or was never opened. - -## SEE ALSO - -[nng_socket](nng_socket.md) diff --git a/docs/reference/src/api/socket/nng_pub_open.md b/docs/reference/src/api/socket/nng_pub_open.md index 987718f4..18321896 100644 --- a/docs/reference/src/api/socket/nng_pub_open.md +++ b/docs/reference/src/api/socket/nng_pub_open.md @@ -1,8 +1,8 @@ -# nng_pub_open() +# nng_pub_open ## NAME -nng_pub_open --- create _PUB_ socket +nng*pub_open --- create \_PUB* socket ## SYNOPSIS @@ -18,10 +18,10 @@ int nng_pub0_open_raw(nng_socket *s); == DESCRIPTION The `nng_pub0_open()` function creates a [_PUB_](../../protocols/pub.md) version 0 -[socket](nng_socket.md) and returns it at the location pointed to by _s_. +[socket](index.md) and returns it at the location pointed to by _s_. The `nng_pub0_open_raw()` function creates a [_PUB_](../../protocols/pub.md) version 0 -[socket](nng_socket.md) in +[socket](index.md) in [raw](../../overview/raw.md) mode and returns it at the location pointed to by _s_. ## RETURN VALUES diff --git a/docs/reference/src/api/threads/nng_cv_alloc.md b/docs/reference/src/api/threads/nng_cv_alloc.md index 7379df7e..faa18ba4 100644 --- a/docs/reference/src/api/threads/nng_cv_alloc.md +++ b/docs/reference/src/api/threads/nng_cv_alloc.md @@ -1,4 +1,4 @@ -# nng_cv_alloc() +# nng_cv_alloc ## NAME @@ -38,9 +38,9 @@ This function returns 0 on success, and non-zero otherwise. ## SEE ALSO -[nng_cv_free()](nng_cv_free.md), -[nng_cv_until()](nng_cv_until.md), -[nng_cv_wait()](nng_cv_wait.md), -[nng_cv_wake()](nng_cv_wake.md), -[nng_cv_wake1()](nng_cv_wake1.md), -[nng_mtx_alloc()](nng_mtx_alloc.md) +[nng_cv_free](nng_cv_free.md), +[nng_cv_until](nng_cv_until.md), +[nng_cv_wait](nng_cv_wait.md), +[nng_cv_wake](nng_cv_wake.md), +[nng_cv_wake1](nng_cv_wake1.md), +[nng_mtx_alloc](nng_mtx_alloc.md) diff --git a/docs/reference/src/api/threads/nng_cv_free.md b/docs/reference/src/api/threads/nng_cv_free.md index 87412ce9..f7103f66 100644 --- a/docs/reference/src/api/threads/nng_cv_free.md +++ b/docs/reference/src/api/threads/nng_cv_free.md @@ -1,4 +1,4 @@ -# nng_cv_free() +# nng_cv_free ## NAME @@ -19,4 +19,4 @@ The `nng_cv_free()` function frees the condition variable _cv_. ## SEE ALSO -[nng_cv_alloc()](nng_cv_alloc.md) +[nng_cv_alloc](nng_cv_alloc.md) diff --git a/docs/reference/src/api/threads/nng_cv_wait.md b/docs/reference/src/api/threads/nng_cv_wait.md index 1f4ddf42..d384201c 100644 --- a/docs/reference/src/api/threads/nng_cv_wait.md +++ b/docs/reference/src/api/threads/nng_cv_wait.md @@ -1,4 +1,4 @@ -# nng_cv_wait() +# nng_cv_wait ## NAME @@ -59,10 +59,10 @@ The following example demonstrates use of this function: ## SEE ALSO -[nng_cv_alloc()](nng_cv_alloc.md), -[nng_cv_until()](nng_cv_until.md), -[nng_cv_wake()](nng_cv_wake.md), -[nng_cv_wake1()](nng_cv_wake1.md), -[nng_mtx_alloc()](nng_mtx_alloc.md), -[nng_mtx_lock()](nng_mtx_lock.md), -[nng_mtx_unlock()](nng_mtx_unlock.md) +[nng_cv_alloc](nng_cv_alloc.md), +[nng_cv_until](nng_cv_until.md), +[nng_cv_wake](nng_cv_wake.md), +[nng_cv_wake1](nng_cv_wake1.md), +[nng_mtx_alloc](nng_mtx_alloc.md), +[nng_mtx_lock](nng_mtx_lock.md), +[nng_mtx_unlock](nng_mtx_unlock.md) diff --git a/docs/reference/src/api/threads/nng_cv_wake.md b/docs/reference/src/api/threads/nng_cv_wake.md index e83fa96d..8d0d2fbd 100644 --- a/docs/reference/src/api/threads/nng_cv_wake.md +++ b/docs/reference/src/api/threads/nng_cv_wake.md @@ -1,4 +1,4 @@ -# nng_cv_wake() +# nng_cv_wake ## NAME @@ -33,10 +33,10 @@ will check, while holding the mutex. ## SEE ALSO -[nng_cv_alloc()](nng_cv_alloc.md), -[nng_cv_until()](nng_cv_until.md), -[nng_cv_wait()](nng_cv_wait.md), -[nng_cv_wake1()](nng_cv_wake1.md), -[nng_mtx_alloc()](nng_mtx_alloc.md), -[nng_mtx_lock()](nng_mtx_lock.md), -[nng_mtx_unlock()](nng_mtx_unlock.md) +[nng_cv_alloc](nng_cv_alloc.md), +[nng_cv_until](nng_cv_until.md), +[nng_cv_wait](nng_cv_wait.md), +[nng_cv_wake1](nng_cv_wake1.md), +[nng_mtx_alloc](nng_mtx_alloc.md), +[nng_mtx_lock](nng_mtx_lock.md), +[nng_mtx_unlock](nng_mtx_unlock.md) diff --git a/docs/reference/src/api/threads/nng_cv_wake1.md b/docs/reference/src/api/threads/nng_cv_wake1.md index 1c70388d..09b31755 100644 --- a/docs/reference/src/api/threads/nng_cv_wake1.md +++ b/docs/reference/src/api/threads/nng_cv_wake1.md @@ -1,4 +1,4 @@ -# nng_cv_wake1() +# nng_cv_wake1 ## NAME @@ -33,11 +33,10 @@ will check, while holding the mutex. ## SEE ALSO -[.text-left] -[nng_cv_alloc()](nng_cv_alloc.md), -[nng_cv_until()](nng_cv_until.md), -[nng_cv_wait()](nng_cv_wait.md), -[nng_cv_wake()](nng_cv_wake.md), -[nng_mtx_alloc()](nng_mtx_alloc.md), -[nng_mtx_lock()](nng_mtx_lock.md), -[nng_mtx_unlock()](nng_mtx_unlock.md) +[nng_cv_alloc](nng_cv_alloc.md), +[nng_cv_until](nng_cv_until.md), +[nng_cv_wait](nng_cv_wait.md), +[nng_cv_wake](nng_cv_wake.md), +[nng_mtx_alloc](nng_mtx_alloc.md), +[nng_mtx_lock](nng_mtx_lock.md), +[nng_mtx_unlock](nng_mtx_unlock.md) diff --git a/docs/reference/src/api/util/nng_alloc.md b/docs/reference/src/api/util/nng_alloc.md index 98f71fa5..ffc46083 100644 --- a/docs/reference/src/api/util/nng_alloc.md +++ b/docs/reference/src/api/util/nng_alloc.md @@ -1,4 +1,4 @@ -# nng_alloc() +# nng_alloc ## NAME @@ -40,5 +40,5 @@ is returned. ## SEE ALSO -[nng_free()](nng_free.md), -[nng_send()](../socket/nng_send.md) +[nng_free](nng_free.md), +[nng_send](../socket/nng_send.md) diff --git a/docs/reference/src/api/util/nng_clock.md b/docs/reference/src/api/util/nng_clock.md index 2b42b158..1bc4037d 100644 --- a/docs/reference/src/api/util/nng_clock.md +++ b/docs/reference/src/api/util/nng_clock.md @@ -1,4 +1,4 @@ -# nng_clock() +# nng_clock ## NAME @@ -38,7 +38,7 @@ Milliseconds since reference time. ## SEE ALSO -[nng_sleep_aio()](nng_sleep_aio.md), -[nng_cv_until()](../threads/nng_cv_until.md), -[nng_msleep()](nng_msleep.md), +[nng_sleep_aio](nng_sleep_aio.md), +[nng_cv_until](../threads/nng_cv_until.md), +[nng_msleep](nng_msleep.md), [nng_duration](nng_duration.md) diff --git a/docs/reference/src/api/util/nng_free.md b/docs/reference/src/api/util/nng_free.md index ca527914..c25686b4 100644 --- a/docs/reference/src/api/util/nng_free.md +++ b/docs/reference/src/api/util/nng_free.md @@ -1,4 +1,4 @@ -# nng_free() +# nng_free ## NAME @@ -31,5 +31,5 @@ that was previously allocated by [`nng_alloc()`](nng_alloc.md) or ## SEE ALSO -[nng_alloc()](nng_alloc.md), -[nng_recv()](nng_free.md) +[nng_alloc](nng_alloc.md), +[nng_recv](../socket/nng_recv.md) diff --git a/docs/reference/src/api/util/nng_random.md b/docs/reference/src/api/util/nng_random.md index b358dfb6..7cc73d2a 100644 --- a/docs/reference/src/api/util/nng_random.md +++ b/docs/reference/src/api/util/nng_random.md @@ -1,4 +1,4 @@ -# nng_random() +# nng_random ## NAME diff --git a/docs/reference/src/api/util/nng_strerror.md b/docs/reference/src/api/util/nng_strerror.md index 3315651a..14041fad 100644 --- a/docs/reference/src/api/util/nng_strerror.md +++ b/docs/reference/src/api/util/nng_strerror.md @@ -1,4 +1,4 @@ -# nng_strerror() +# nng_strerror ## NAME diff --git a/docs/reference/src/api/util/nng_version.md b/docs/reference/src/api/util/nng_version.md index 20ae094b..53c49ee6 100644 --- a/docs/reference/src/api/util/nng_version.md +++ b/docs/reference/src/api/util/nng_version.md @@ -1,4 +1,4 @@ -# nng_version(3) +# nng_version ## NAME -- cgit v1.2.3-70-g09d2