diff options
Diffstat (limited to 'docs/reference/src')
73 files changed, 1418 insertions, 274 deletions
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/nng_ctx.md b/docs/reference/src/api/context/index.md index 9f963e9a..d5a3fc90 100644 --- a/docs/reference/src/api/nng_ctx.md +++ b/docs/reference/src/api/context/index.md @@ -17,7 +17,7 @@ typedef struct nng_ctx_s nng_ctx 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 +share a single [socket](../socket/index.md), with its various underlying [dialers](nng_dialer.md), [listeners](nng_listener.md), [pipes](nng_pipe.md), @@ -145,16 +145,16 @@ start_echo_service(nng_socket rep_socket) ## 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_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_socket](../socket/index.md), [nng_options](nng_options.md) diff --git a/docs/reference/src/api/nng_ctx_close.md b/docs/reference/src/api/context/nng_ctx_close.md index 443df76e..e33dd843 100644 --- a/docs/reference/src/api/nng_ctx_close.md +++ b/docs/reference/src/api/context/nng_ctx_close.md @@ -1,4 +1,4 @@ -# nng_ctx_close() +# nng_ctx_close ## NAME @@ -25,7 +25,7 @@ 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. +> (using [`nng_close()`](../socket/nng_close.md)) also closes this context. ## RETURN VALUES @@ -37,6 +37,5 @@ This function returns 0 on success, and non-zero otherwise. ## SEE ALSO -[nng_close()](nng_close.md), -[nng_ctx_open()](nng_ctx_open.md), -[nng_ctx](nng_ctx.md), +[nng_close](nng_close.md), +[nng_ctx_open](nng_ctx_open.md) diff --git a/docs/reference/src/api/nng_ctx_get.md b/docs/reference/src/api/context/nng_ctx_get.md index 0c2d131c..35407f18 100644 --- a/docs/reference/src/api/nng_ctx_get.md +++ b/docs/reference/src/api/context/nng_ctx_get.md @@ -1,4 +1,4 @@ -# nng_ctx_get() +# nng_ctx_get ## NAME @@ -28,9 +28,9 @@ int nng_ctx_get_uint64(nng_ctx ctx, const char *opt, uint64_t *u64p); {{hi:options, context}} The `nng_ctx_get()` functions are used to retrieve option values for -the [context](nng_ctx.md) _ctx_. +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](nng_options.md). +A number of them are documented in [nng_options](../socket/nng_options.md). > [!NOTE] > Context options are protocol specific. @@ -105,9 +105,8 @@ These functions return 0 on success, and non-zero otherwise. ## SEE ALSO -[nng_ctx_set()](nng_ctx_set.md), -[nng_strdup()](nng_strdup.md), -[nng_strfree()](nng_strfree.md), +[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) +[nng_options](../socket/nng_options.md) diff --git a/docs/reference/src/api/nng_ctx_getopt.md b/docs/reference/src/api/context/nng_ctx_getopt.md index ddd6f791..83a648d0 100644 --- a/docs/reference/src/api/nng_ctx_getopt.md +++ b/docs/reference/src/api/context/nng_ctx_getopt.md @@ -1,4 +1,4 @@ -# nng_ctx_getopt() +# nng_ctx_getopt ## NAME @@ -32,7 +32,7 @@ int nng_ctx_getopt_uint64(nng_ctx ctx, const char *opt, uint64_t *u64p); > 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 [context](index.md) _ctx_. The actual options that may be retrieved in this way vary. > [!NOTE] @@ -85,9 +85,9 @@ on the actual option, and will be documented with the option itself. - `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) + 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()`](nng_strfree.md) when it is no longer needed. + [`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 @@ -110,8 +110,7 @@ These functions return 0 on success, and non-zero otherwise. ## SEE ALSO -[nng_strdup()](nng_strdup.md), -[nng_strfree()](nng_strfree.md), +[nng_strdup](../util/nng_strdup.md), +[nng_strfree](../util/nng_strfree.md), [nng_duration](nng_duration.md), -[nng_ctx](nng_ctx.md), -[nng_options](nng_options.md) +[nng_options](../socket/nng_options.md) diff --git a/docs/reference/src/api/nng_ctx_id.md b/docs/reference/src/api/context/nng_ctx_id.md index 07af4c4b..9d8d7223 100644 --- a/docs/reference/src/api/nng_ctx_id.md +++ b/docs/reference/src/api/context/nng_ctx_id.md @@ -1,4 +1,4 @@ -# nng_ctx_id() +# nng_ctx_id ## NAME @@ -29,7 +29,3 @@ Otherwise it returns `-1`. 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/context/nng_ctx_open.md index 521da916..b582e254 100644 --- a/docs/reference/src/api/nng_ctx_open.md +++ b/docs/reference/src/api/context/nng_ctx_open.md @@ -1,4 +1,4 @@ -# nng_ctx_open() +# nng_ctx_open ## NAME @@ -49,9 +49,8 @@ This function returns 0 on success, and non-zero otherwise. ## 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) +[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/nng_ctx_recv.md b/docs/reference/src/api/context/nng_ctx_recv.md index d9aaae0f..2ef398ea 100644 --- a/docs/reference/src/api/nng_ctx_recv.md +++ b/docs/reference/src/api/context/nng_ctx_recv.md @@ -1,4 +1,4 @@ -# nng_ctx_recv() +# nng_ctx_recv ## NAME @@ -14,14 +14,14 @@ 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. +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()`](nng_aio_set_msg.md), then the completion +[`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()`](nng_aio_result.md) will +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. @@ -33,7 +33,7 @@ and disposing of it appropriately. 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. +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 @@ -52,10 +52,5 @@ The following errors may be set on the _aio_, if the operation fails. ## 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) +[Asynchronous I/O](../aio/index.md), +[Messages](../msg/index.md) diff --git a/docs/reference/src/api/nng_ctx_recvmsg.md b/docs/reference/src/api/context/nng_ctx_recvmsg.md index 84368f76..c0065dd3 100644 --- a/docs/reference/src/api/nng_ctx_recvmsg.md +++ b/docs/reference/src/api/context/nng_ctx_recvmsg.md @@ -1,4 +1,4 @@ -# nng_ctx_recvmsg() +# nng_ctx_recvmsg ## NAME @@ -44,8 +44,7 @@ This function returns 0 on success, and non-zero otherwise. ## SEE ALSO -[nng_msg_free()](nng_msg_free.md), +[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), -[nng_ctx](nng_ctx) +[nng_ctx_sendmsg()](nng_ctx_sendmsg.md) diff --git a/docs/reference/src/api/nng_ctx_send.md b/docs/reference/src/api/context/nng_ctx_send.md index dcf839c0..9caad652 100644 --- a/docs/reference/src/api/nng_ctx_send.md +++ b/docs/reference/src/api/context/nng_ctx_send.md @@ -1,4 +1,4 @@ -# nng_ctx_send() +# nng_ctx_send ## NAME @@ -14,15 +14,15 @@ void nng_ctx_send(nng_ctx ctx, nng_aio *aio); ## DESCRIPTION -The `nng_ctx_send()` sends a [message](nng_msg.md) using the +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()`](nng_aio_set_msg.md) function. +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()`](nng_aio_result.md) +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. @@ -36,12 +36,12 @@ In this case the socket will dispose of the message when it is finished with it. 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. +[`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()`](nng_aio_get_msg.md) and dispose of +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()`](nng_msg_free.md). +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 @@ -59,11 +59,10 @@ socket, or deallocating the message with [`nng_msg_free()`](nng_msg_free.md). ## 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) +[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/nng_ctx_sendmsg.md b/docs/reference/src/api/context/nng_ctx_sendmsg.md index 5c36837c..346f927d 100644 --- a/docs/reference/src/api/nng_ctx_sendmsg.md +++ b/docs/reference/src/api/context/nng_ctx_sendmsg.md @@ -64,7 +64,4 @@ This function returns 0 on success, and non-zero otherwise. ## 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) +[Messages](../msg/index.md) diff --git a/docs/reference/src/api/nng_ctx_set.md b/docs/reference/src/api/context/nng_ctx_set.md index 13692c14..b3237717 100644 --- a/docs/reference/src/api/nng_ctx_set.md +++ b/docs/reference/src/api/context/nng_ctx_set.md @@ -1,4 +1,4 @@ -# nng_ctx_set() +# nng_ctx_set ## NAME @@ -89,7 +89,6 @@ These functions return 0 on success, and non-zero otherwise. ## SEE ALSO -[nng_ctx_get()](nng_ctx_get), -[nng_socket_set()](nng_socket_get), -[nng_ctx](nng_ctx), +[nng_ctx_get](nng_ctx_get), +[nng_socket_set](../socket/nng_socket_get), [nng_options](nng_options) diff --git a/docs/reference/src/api/nng_ctx_setopt.md b/docs/reference/src/api/context/nng_ctx_setopt.md index 6bf7261a..f62b6857 100644 --- a/docs/reference/src/api/nng_ctx_setopt.md +++ b/docs/reference/src/api/context/nng_ctx_setopt.md @@ -1,4 +1,4 @@ -# nng_ctx_setopt() +# nng_ctx_setopt ## NAME @@ -94,6 +94,5 @@ These functions return 0 on success, and non-zero otherwise. ## SEE ALSO -[nng_ctx_set()](nng_ctx_set.md), -[nng_ctx](nng_ctx.md), +[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/nng.h> +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 <nng/nng.h> + +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 <nng/nng.h> + +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 <nng/nng.h> + +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 <nng/nng.h> + +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 <nng/nng.h> + +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 <nng/nng.h> + +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 <nng/nng.h> + +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 <nng/nng.h> + +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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// 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/nng.h> + +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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// 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 <nng/nng.h> + +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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// 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 <nng/nng.h> + +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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// 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 <nng/nng.h> + +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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// 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 <nng/nng.h> + +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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// 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 <nng/nng.h> + +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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// 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 <nng/nng.h> + +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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// 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 <nng/nng.h> + +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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// 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 <nng/nng.h> + +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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// 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 <nng/nng.h> + +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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// 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 <nng/nng.h> + +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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// 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 <nng/nng.h> + +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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// 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 <nng/nng.h> + +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 <nng/nng.h> + +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/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 |