From 9b156d28f1a830cc7339ab9993991ef5dd0b0fed Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sat, 30 Mar 2024 15:57:15 -0700 Subject: Organization changes abound. --- docs/reference/src/SUMMARY.md | 80 ++++++++--------- docs/reference/src/api/msg/index.md | 97 --------------------- 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.md | 44 ---------- docs/reference/src/api/msg/nng_msg_header.md | 42 --------- .../reference/src/api/msg/nng_msg_header_append.md | 41 --------- docs/reference/src/api/msg/nng_msg_header_chop.md | 42 --------- docs/reference/src/api/msg/nng_msg_header_clear.md | 22 ----- .../reference/src/api/msg/nng_msg_header_insert.md | 41 --------- docs/reference/src/api/msg/nng_msg_header_len.md | 25 ------ docs/reference/src/api/msg/nng_msg_header_trim.md | 42 --------- docs/reference/src/api/msg/nng_msg_insert.md | 53 ------------ docs/reference/src/api/msg/nng_msg_len.md | 26 ------ docs/reference/src/api/msg/nng_msg_realloc.md | 53 ------------ docs/reference/src/api/msg/nng_msg_reserve.md | 46 ---------- docs/reference/src/api/msg/nng_msg_set_pipe.md | 29 ------- docs/reference/src/api/msg/nng_msg_trim.md | 48 ----------- docs/reference/src/api/threads/nng_cv_alloc.md | 46 ---------- docs/reference/src/api/threads/nng_cv_free.md | 22 ----- docs/reference/src/api/threads/nng_cv_until.md | 75 ---------------- docs/reference/src/api/threads/nng_cv_wait.md | 68 --------------- docs/reference/src/api/threads/nng_cv_wake.md | 42 --------- docs/reference/src/api/threads/nng_cv_wake1.md | 42 --------- docs/reference/src/api/threads/nng_mtx_alloc.md | 44 ---------- docs/reference/src/api/threads/nng_mtx_free.md | 23 ----- docs/reference/src/api/threads/nng_mtx_lock.md | 38 --------- docs/reference/src/api/threads/nng_mtx_unlock.md | 29 ------- docs/reference/src/msg/index.md | 99 ++++++++++++++++++++++ docs/reference/src/msg/nng_msg_alloc.md | 42 +++++++++ docs/reference/src/msg/nng_msg_append.md | 48 +++++++++++ docs/reference/src/msg/nng_msg_body.md | 49 +++++++++++ docs/reference/src/msg/nng_msg_capacity.md | 32 +++++++ docs/reference/src/msg/nng_msg_chop.md | 49 +++++++++++ docs/reference/src/msg/nng_msg_clear.md | 25 ++++++ docs/reference/src/msg/nng_msg_dup.md | 36 ++++++++ docs/reference/src/msg/nng_msg_free.md | 24 ++++++ docs/reference/src/msg/nng_msg_get_pipe.md | 46 ++++++++++ docs/reference/src/msg/nng_msg_header.md | 44 ++++++++++ docs/reference/src/msg/nng_msg_header_append.md | 43 ++++++++++ docs/reference/src/msg/nng_msg_header_chop.md | 44 ++++++++++ docs/reference/src/msg/nng_msg_header_clear.md | 24 ++++++ docs/reference/src/msg/nng_msg_header_insert.md | 43 ++++++++++ docs/reference/src/msg/nng_msg_header_len.md | 27 ++++++ docs/reference/src/msg/nng_msg_header_trim.md | 44 ++++++++++ docs/reference/src/msg/nng_msg_insert.md | 55 ++++++++++++ docs/reference/src/msg/nng_msg_len.md | 28 ++++++ docs/reference/src/msg/nng_msg_realloc.md | 55 ++++++++++++ docs/reference/src/msg/nng_msg_reserve.md | 48 +++++++++++ docs/reference/src/msg/nng_msg_set_pipe.md | 31 +++++++ docs/reference/src/msg/nng_msg_trim.md | 50 +++++++++++ docs/reference/src/refs.md | 37 +++++++- docs/reference/src/thr/nng_cv_alloc.md | 48 +++++++++++ docs/reference/src/thr/nng_cv_free.md | 24 ++++++ docs/reference/src/thr/nng_cv_until.md | 77 +++++++++++++++++ docs/reference/src/thr/nng_cv_wait.md | 70 +++++++++++++++ docs/reference/src/thr/nng_cv_wake.md | 44 ++++++++++ docs/reference/src/thr/nng_cv_wake1.md | 44 ++++++++++ docs/reference/src/thr/nng_mtx_alloc.md | 46 ++++++++++ docs/reference/src/thr/nng_mtx_free.md | 25 ++++++ docs/reference/src/thr/nng_mtx_lock.md | 40 +++++++++ docs/reference/src/thr/nng_mtx_unlock.md | 31 +++++++ docs/reference/src/tran/index.md | 13 +++ docs/reference/src/tran/inproc.md | 49 +++++++++++ docs/reference/src/tran/tcp.md | 72 ++++++++++++++++ docs/reference/src/transports/index.md | 5 -- docs/reference/src/transports/inproc.md | 50 ----------- docs/reference/src/transports/tcp.md | 70 --------------- 74 files changed, 1643 insertions(+), 1537 deletions(-) delete mode 100644 docs/reference/src/api/msg/index.md delete mode 100644 docs/reference/src/api/msg/nng_msg_alloc.md delete mode 100644 docs/reference/src/api/msg/nng_msg_append.md delete mode 100644 docs/reference/src/api/msg/nng_msg_body.md delete mode 100644 docs/reference/src/api/msg/nng_msg_capacity.md delete mode 100644 docs/reference/src/api/msg/nng_msg_chop.md delete mode 100644 docs/reference/src/api/msg/nng_msg_clear.md delete mode 100644 docs/reference/src/api/msg/nng_msg_dup.md delete mode 100644 docs/reference/src/api/msg/nng_msg_free.md delete mode 100644 docs/reference/src/api/msg/nng_msg_get_pipe.md delete mode 100644 docs/reference/src/api/msg/nng_msg_header.md delete mode 100644 docs/reference/src/api/msg/nng_msg_header_append.md delete mode 100644 docs/reference/src/api/msg/nng_msg_header_chop.md delete mode 100644 docs/reference/src/api/msg/nng_msg_header_clear.md delete mode 100644 docs/reference/src/api/msg/nng_msg_header_insert.md delete mode 100644 docs/reference/src/api/msg/nng_msg_header_len.md delete mode 100644 docs/reference/src/api/msg/nng_msg_header_trim.md delete mode 100644 docs/reference/src/api/msg/nng_msg_insert.md delete mode 100644 docs/reference/src/api/msg/nng_msg_len.md delete mode 100644 docs/reference/src/api/msg/nng_msg_realloc.md delete mode 100644 docs/reference/src/api/msg/nng_msg_reserve.md delete mode 100644 docs/reference/src/api/msg/nng_msg_set_pipe.md delete mode 100644 docs/reference/src/api/msg/nng_msg_trim.md delete mode 100644 docs/reference/src/api/threads/nng_cv_alloc.md delete mode 100644 docs/reference/src/api/threads/nng_cv_free.md delete mode 100644 docs/reference/src/api/threads/nng_cv_until.md delete mode 100644 docs/reference/src/api/threads/nng_cv_wait.md delete mode 100644 docs/reference/src/api/threads/nng_cv_wake.md delete mode 100644 docs/reference/src/api/threads/nng_cv_wake1.md delete mode 100644 docs/reference/src/api/threads/nng_mtx_alloc.md delete mode 100644 docs/reference/src/api/threads/nng_mtx_free.md delete mode 100644 docs/reference/src/api/threads/nng_mtx_lock.md delete mode 100644 docs/reference/src/api/threads/nng_mtx_unlock.md create mode 100644 docs/reference/src/msg/index.md create mode 100644 docs/reference/src/msg/nng_msg_alloc.md create mode 100644 docs/reference/src/msg/nng_msg_append.md create mode 100644 docs/reference/src/msg/nng_msg_body.md create mode 100644 docs/reference/src/msg/nng_msg_capacity.md create mode 100644 docs/reference/src/msg/nng_msg_chop.md create mode 100644 docs/reference/src/msg/nng_msg_clear.md create mode 100644 docs/reference/src/msg/nng_msg_dup.md create mode 100644 docs/reference/src/msg/nng_msg_free.md create mode 100644 docs/reference/src/msg/nng_msg_get_pipe.md create mode 100644 docs/reference/src/msg/nng_msg_header.md create mode 100644 docs/reference/src/msg/nng_msg_header_append.md create mode 100644 docs/reference/src/msg/nng_msg_header_chop.md create mode 100644 docs/reference/src/msg/nng_msg_header_clear.md create mode 100644 docs/reference/src/msg/nng_msg_header_insert.md create mode 100644 docs/reference/src/msg/nng_msg_header_len.md create mode 100644 docs/reference/src/msg/nng_msg_header_trim.md create mode 100644 docs/reference/src/msg/nng_msg_insert.md create mode 100644 docs/reference/src/msg/nng_msg_len.md create mode 100644 docs/reference/src/msg/nng_msg_realloc.md create mode 100644 docs/reference/src/msg/nng_msg_reserve.md create mode 100644 docs/reference/src/msg/nng_msg_set_pipe.md create mode 100644 docs/reference/src/msg/nng_msg_trim.md create mode 100644 docs/reference/src/thr/nng_cv_alloc.md create mode 100644 docs/reference/src/thr/nng_cv_free.md create mode 100644 docs/reference/src/thr/nng_cv_until.md create mode 100644 docs/reference/src/thr/nng_cv_wait.md create mode 100644 docs/reference/src/thr/nng_cv_wake.md create mode 100644 docs/reference/src/thr/nng_cv_wake1.md create mode 100644 docs/reference/src/thr/nng_mtx_alloc.md create mode 100644 docs/reference/src/thr/nng_mtx_free.md create mode 100644 docs/reference/src/thr/nng_mtx_lock.md create mode 100644 docs/reference/src/thr/nng_mtx_unlock.md create mode 100644 docs/reference/src/tran/index.md create mode 100644 docs/reference/src/tran/inproc.md create mode 100644 docs/reference/src/tran/tcp.md delete mode 100644 docs/reference/src/transports/index.md delete mode 100644 docs/reference/src/transports/inproc.md delete mode 100644 docs/reference/src/transports/tcp.md (limited to 'docs/reference/src') diff --git a/docs/reference/src/SUMMARY.md b/docs/reference/src/SUMMARY.md index 99924f3d..bc24ac01 100644 --- a/docs/reference/src/SUMMARY.md +++ b/docs/reference/src/SUMMARY.md @@ -6,7 +6,7 @@ - [RAW mode](./overview/raw.md) -- [Protocols](./proto/index.md) +- [Protocols](proto/index.md) - [BUS](proto/bus.md) - [PAIR](proto/pair.md) @@ -19,37 +19,37 @@ - [SUB](proto/sub.md) - [SURVEYOR](proto/surveyor.md) -- [Transports](./transports/index.md) +- [Transports](tran/index.md) - - [INPROC](transports/inproc.md) - - [TCP](transports/tcp.md) + - [INPROC](tran/inproc.md) + - [TCP](tran/tcp.md) - [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_get_pipe](api/msg/nng_msg_get_pipe.md) - - [nng_msg_header](api/msg/nng_msg_header.md) - - [nng_msg_header_append](api/msg/nng_msg_header_append.md) - - [nng_msg_header_chop](api/msg/nng_msg_header_chop.md) - - [nng_msg_header_clear](api/msg/nng_msg_header_clear.md) - - [nng_msg_header_insert](api/msg/nng_msg_header_insert.md) - - [nng_msg_header_len](api/msg/nng_msg_header_len.md) - - [nng_msg_header_trim](api/msg/nng_msg_header_trim.md) - - [nng_msg_insert](api/msg/nng_msg_insert.md) - - [nng_msg_len](api/msg/nng_msg_len.md) - - [nng_msg_realloc](api/msg/nng_msg_realloc.md) - - [nng_msg_reserve](api/msg/nng_msg_reserve.md) - - [nng_msg_set_pipe](api/msg/nng_msg_set_pipe.md) - - [nng_msg_trim](api/msg/nng_msg_trim.md) + - [Messages](msg/index.md) + + - [nng_msg_alloc](msg/nng_msg_alloc.md) + - [nng_msg_append](msg/nng_msg_append.md) + - [nng_msg_body](msg/nng_msg_body.md) + - [nng_msg_capacity](msg/nng_msg_capacity.md) + - [nng_msg_chop](msg/nng_msg_chop.md) + - [nng_msg_clear](msg/nng_msg_clear.md) + - [nng_msg_dup](msg/nng_msg_dup.md) + - [nng_msg_free](msg/nng_msg_free.md) + - [nng_msg_get_pipe](msg/nng_msg_get_pipe.md) + - [nng_msg_header](msg/nng_msg_header.md) + - [nng_msg_header_append](msg/nng_msg_header_append.md) + - [nng_msg_header_chop](msg/nng_msg_header_chop.md) + - [nng_msg_header_clear](msg/nng_msg_header_clear.md) + - [nng_msg_header_insert](msg/nng_msg_header_insert.md) + - [nng_msg_header_len](msg/nng_msg_header_len.md) + - [nng_msg_header_trim](msg/nng_msg_header_trim.md) + - [nng_msg_insert](msg/nng_msg_insert.md) + - [nng_msg_len](msg/nng_msg_len.md) + - [nng_msg_realloc](msg/nng_msg_realloc.md) + - [nng_msg_reserve](msg/nng_msg_reserve.md) + - [nng_msg_set_pipe](msg/nng_msg_set_pipe.md) + - [nng_msg_trim](msg/nng_msg_trim.md) - [Sockets](api/socket/index.md) @@ -110,18 +110,18 @@ - [nng_strfree](api/util/nng_strfree.md) - [nng_version](api/util/nng_version.md) - - [Threads and Synchronization](api/threads/index.md) - - - [nng_cv_alloc](api/threads/nng_cv_alloc.md) - - [nng_cv_free](api/threads/nng_cv_free.md) - - [nng_cv_until](api/threads/nng_cv_until.md) - - [nng_cv_wait](api/threads/nng_cv_wait.md) - - [nng_cv_wake](api/threads/nng_cv_wake.md) - - [nng_cv_wake1](api/threads/nng_cv_wake1.md) - - [nng_mtx_alloc](api/threads/nng_mtx_alloc.md) - - [nng_mtx_free](api/threads/nng_mtx_free.md) - - [nng_mtx_lock](api/threads/nng_mtx_lock.md) - - [nng_mtx_unlock](api/threads/nng_mtx_unlock.md) + - [Threads and Synchronization](thr/index.md) + + - [nng_cv_alloc](thr/nng_cv_alloc.md) + - [nng_cv_free](thr/nng_cv_free.md) + - [nng_cv_until](thr/nng_cv_until.md) + - [nng_cv_wait](thr/nng_cv_wait.md) + - [nng_cv_wake](thr/nng_cv_wake.md) + - [nng_cv_wake1](thr/nng_cv_wake1.md) + - [nng_mtx_alloc](thr/nng_mtx_alloc.md) + - [nng_mtx_free](thr/nng_mtx_free.md) + - [nng_mtx_lock](thr/nng_mtx_lock.md) + - [nng_mtx_unlock](thr/nng_mtx_unlock.md) - [Legacy Compatibility](api/compat/index.md) diff --git a/docs/reference/src/api/msg/index.md b/docs/reference/src/api/msg/index.md deleted file mode 100644 index 54d8d9b8..00000000 --- a/docs/reference/src/api/msg/index.md +++ /dev/null @@ -1,97 +0,0 @@ -# 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 deleted file mode 100644 index 163d193b..00000000 --- a/docs/reference/src/api/msg/nng_msg_alloc.md +++ /dev/null @@ -1,40 +0,0 @@ -# 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 deleted file mode 100644 index 5807d3a6..00000000 --- a/docs/reference/src/api/msg/nng_msg_append.md +++ /dev/null @@ -1,46 +0,0 @@ -# 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 deleted file mode 100644 index abd49c7f..00000000 --- a/docs/reference/src/api/msg/nng_msg_body.md +++ /dev/null @@ -1,47 +0,0 @@ -# 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 deleted file mode 100644 index 707a04e3..00000000 --- a/docs/reference/src/api/msg/nng_msg_capacity.md +++ /dev/null @@ -1,30 +0,0 @@ -# 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 deleted file mode 100644 index fc9a0df5..00000000 --- a/docs/reference/src/api/msg/nng_msg_chop.md +++ /dev/null @@ -1,47 +0,0 @@ -# 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 deleted file mode 100644 index af25c072..00000000 --- a/docs/reference/src/api/msg/nng_msg_clear.md +++ /dev/null @@ -1,23 +0,0 @@ -# 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 deleted file mode 100644 index dae376e8..00000000 --- a/docs/reference/src/api/msg/nng_msg_dup.md +++ /dev/null @@ -1,34 +0,0 @@ -# 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 deleted file mode 100644 index 94887be0..00000000 --- a/docs/reference/src/api/msg/nng_msg_free.md +++ /dev/null @@ -1,22 +0,0 @@ -# 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.md b/docs/reference/src/api/msg/nng_msg_get_pipe.md deleted file mode 100644 index 5f935347..00000000 --- a/docs/reference/src/api/msg/nng_msg_get_pipe.md +++ /dev/null @@ -1,44 +0,0 @@ -# nng_msg_get_pipe - -## NAME - -nng_msg_get_pipe --- get pipe for message - -## SYNOPSIS - -```c -#include - -nng_pipe nng_msg_get_pipe(nng_msg *msg); -``` - -## DESCRIPTION - -The `nng_msg_get_pipe()` returns the [`nng_pipe`](../conn/nng_pipe.md) 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 [`nng_pipe_get()`](../conn/nng_pipe_get.md) 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. - -## SEE ALSO - -[nng_msg_alloc](nng_msg_alloc.md), -[nng_msg_set_pipe](nng_msg_set_pipe.md), -[nng_pipe_get](../conn/nng_pipe_get.md) diff --git a/docs/reference/src/api/msg/nng_msg_header.md b/docs/reference/src/api/msg/nng_msg_header.md deleted file mode 100644 index 7a75464d..00000000 --- a/docs/reference/src/api/msg/nng_msg_header.md +++ /dev/null @@ -1,42 +0,0 @@ -# nng_msg_header - -## NAME - -nng_msg_header --- return message header - -## SYNOPSIS - -```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](../../overview/raw.md) mode sockets. - -> [!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. - -## SEE ALSO - -[nng_msg_alloc](nng_msg_alloc.md), -[nng_msg_body](nng_msg_body.md), -[nng_msg_free](nng_msg_free.md), -[nng_msg_header_append](nng_msg_header_append.md), -[nng_msg_header_chop](nng_msg_header_chop.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) diff --git a/docs/reference/src/api/msg/nng_msg_header_append.md b/docs/reference/src/api/msg/nng_msg_header_append.md deleted file mode 100644 index f87649a5..00000000 --- a/docs/reference/src/api/msg/nng_msg_header_append.md +++ /dev/null @@ -1,41 +0,0 @@ -# nng_msg_header_append - -## NAME - -nng_msg_header_append --- append to message header - -## SYNOPSIS - -```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 - -- `NNG_ENOMEM`: Insufficient free memory exists. - -## SEE ALSO - -[nng_msg_header](nng_msg_body.md), -[nng_msg_header_chop](nng_msg_header_chop.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) diff --git a/docs/reference/src/api/msg/nng_msg_header_chop.md b/docs/reference/src/api/msg/nng_msg_header_chop.md deleted file mode 100644 index 9419d88f..00000000 --- a/docs/reference/src/api/msg/nng_msg_header_chop.md +++ /dev/null @@ -1,42 +0,0 @@ -# nng_msg_header_chop - -## NAME - -nng_msg_header_chop --- remove data from end of message header - -## SYNOPSIS - -```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 - -- `NNG_EINVAL`: The message header is too short to remove the requested data. - -## SEE ALSO - -[nng_msg_header](nng_msg_body.md), -[nng_msg_header_append](nng_msg_header_append.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) diff --git a/docs/reference/src/api/msg/nng_msg_header_clear.md b/docs/reference/src/api/msg/nng_msg_header_clear.md deleted file mode 100644 index 7f3b8387..00000000 --- a/docs/reference/src/api/msg/nng_msg_header_clear.md +++ /dev/null @@ -1,22 +0,0 @@ -# nng_msg_header_clear - -## NAME - -nng_msg_header_clear --- clear message header - -## SYNOPSIS - -```c -#include - -void nng_msg_header_clear(nng_msg *msg); -``` - -## DESCRIPTION - -The `nng_msg_clear()` function resets the header length of _msg_ to zero. - -## SEE ALSO - -[nng_msg_header](nng_msg_header.md), -[nng_msg_header_len](nng_msg_header_len.md) diff --git a/docs/reference/src/api/msg/nng_msg_header_insert.md b/docs/reference/src/api/msg/nng_msg_header_insert.md deleted file mode 100644 index 07124fd9..00000000 --- a/docs/reference/src/api/msg/nng_msg_header_insert.md +++ /dev/null @@ -1,41 +0,0 @@ -# nng_msg_header_insert - -## NAME - -nng_msg_header_insert --- prepend to message header - -## SYNOPSIS - -```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 - -- `NNG_ENOMEM`: Insufficient free memory exists. - -## SEE ALSO - -[nng_msg_header](nng_msg_body.md), -[nng_msg_header_append](nng_msg_header_append.md) -[nng_msg_header_chop](nng_msg_header_chop.md), -[nng_msg_header_len](nng_msg_header_len.md), -[nng_msg_header_trim](nng_msg_header_trim.md) diff --git a/docs/reference/src/api/msg/nng_msg_header_len.md b/docs/reference/src/api/msg/nng_msg_header_len.md deleted file mode 100644 index 51bbf537..00000000 --- a/docs/reference/src/api/msg/nng_msg_header_len.md +++ /dev/null @@ -1,25 +0,0 @@ -# nng_msg_header_len - -## NAME - -nng_msg_header_len --- return message header length - -## SYNOPSIS - -```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. - -## SEE ALSO - -[nng_msg_header](nng_msg_header) diff --git a/docs/reference/src/api/msg/nng_msg_header_trim.md b/docs/reference/src/api/msg/nng_msg_header_trim.md deleted file mode 100644 index ef596dbc..00000000 --- a/docs/reference/src/api/msg/nng_msg_header_trim.md +++ /dev/null @@ -1,42 +0,0 @@ -# nng_msg_header_trim - -## NAME - -nng_msg_header_trim --- remove data from start of message header - -## SYNOPSIS - -```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 - -- `NNG_EINVAL`: The message header is too short to remove the requested data. - -## SEE ALSO - -[nng_msg_header](nng_msg_body.md), -[nng_msg_header_append](nng_msg_header_append.md), -[nng_msg_header_chop](nng_msg_header_chop.md) -[nng_msg_header_insert](nng_msg_header_insert.md) -[nng_msg_header_len](nng_msg_header_len.md), diff --git a/docs/reference/src/api/msg/nng_msg_insert.md b/docs/reference/src/api/msg/nng_msg_insert.md deleted file mode 100644 index a369d3c4..00000000 --- a/docs/reference/src/api/msg/nng_msg_insert.md +++ /dev/null @@ -1,53 +0,0 @@ -# nng_msg_insert - -## NAME - -nng_msg_insert --- prepend to message body - -## SYNOPSIS - -```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 - -- `NNG_ENOMEM`: Insufficient free memory exists. - -## SEE ALSO - -[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_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_len.md b/docs/reference/src/api/msg/nng_msg_len.md deleted file mode 100644 index c470955c..00000000 --- a/docs/reference/src/api/msg/nng_msg_len.md +++ /dev/null @@ -1,26 +0,0 @@ -# nng_msg_len - -## NAME - -nng_msg_len --- return message body length - -## SYNOPSIS - -```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. - -## SEE ALSO - -[nng_msg_alloc](nng_msg_alloc), -[nng_msg_body](nng_msg_body) diff --git a/docs/reference/src/api/msg/nng_msg_realloc.md b/docs/reference/src/api/msg/nng_msg_realloc.md deleted file mode 100644 index 66d113aa..00000000 --- a/docs/reference/src/api/msg/nng_msg_realloc.md +++ /dev/null @@ -1,53 +0,0 @@ -# nng_msg_realloc(3) - -## NAME - -nng_msg_realloc --- reallocate a message - -## SYNOPSIS - -```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 [`nng_msg_append()`](nng_msg_append.md), -allocations may be reduced by first using -[`nng_msg_reserve()`](nng_msg_reserve.md) -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 [`nng_msg_capacity()`](nng_msg_capacity.md). - -> [!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 - -- `NNG_ENOMEM`: Insufficient free memory exists to reallocate a message. - -## SEE ALSO - -[nng_msg_alloc](nng_msg_alloc.md), -[nng_msg_reserve](nng_msg_reserve.md), -[nng_msg_append](nng_msg_append.md), -[nng_msg_body](nng_msg_body.md), -[nng_msg_chop](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_trim](nng_msg_trim.md) diff --git a/docs/reference/src/api/msg/nng_msg_reserve.md b/docs/reference/src/api/msg/nng_msg_reserve.md deleted file mode 100644 index 2d96ac8b..00000000 --- a/docs/reference/src/api/msg/nng_msg_reserve.md +++ /dev/null @@ -1,46 +0,0 @@ -# nng_msg_reserve - -## NAME - -nng_msg_reserve --- reserve storage for a message - -## SYNOPSIS - -```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 [`nng_msg_append()`](nng_msg_append.md) -> will prevent additional memory allocations until the message's length exceeds -> the alotted capacity. - -> [!IMPORTANT] -> 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 - -- `NNG_ENOMEM`: Insufficient free memory exists to reallocate a message. - -## 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_insert](nng_msg_insert.md), -[nng_msg_len](nng_msg_len.md) diff --git a/docs/reference/src/api/msg/nng_msg_set_pipe.md b/docs/reference/src/api/msg/nng_msg_set_pipe.md deleted file mode 100644 index 58f339ca..00000000 --- a/docs/reference/src/api/msg/nng_msg_set_pipe.md +++ /dev/null @@ -1,29 +0,0 @@ -# nng_msg_set_pipe - -## NAME - -nng_msg_set_pipe --- set pipe for message - -## SYNOPSIS - -```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 [_PAIR_](../protocols/pair.md) version 1 protocol can do -this when `NNG_OPT_PAIR1_POLY` mode is set. - -> [!NOTE] -> Not all protocols support overriding the destination pipe. - -## SEE ALSO - -[nng_msg_alloc](nng_msg_alloc.md), -[nng_msg_get_pipe](nng_msg_get_pipe.md) diff --git a/docs/reference/src/api/msg/nng_msg_trim.md b/docs/reference/src/api/msg/nng_msg_trim.md deleted file mode 100644 index c0b8f694..00000000 --- a/docs/reference/src/api/msg/nng_msg_trim.md +++ /dev/null @@ -1,48 +0,0 @@ -# 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/threads/nng_cv_alloc.md b/docs/reference/src/api/threads/nng_cv_alloc.md deleted file mode 100644 index faa18ba4..00000000 --- a/docs/reference/src/api/threads/nng_cv_alloc.md +++ /dev/null @@ -1,46 +0,0 @@ -# nng_cv_alloc - -## NAME - -nng_cv_alloc --- allocate condition variable - -## SYNOPSIS - -```c -#include -#include - -typedef struct nng_cv nng_cv; - -int nng_cv_alloc(nng_cv **cvp, nng_mtx *mtx); -``` - -## DESCRIPTION - -The `nng_cv_alloc()` function allocates a condition variable, using -the mutex _mtx_, and returns it in _cvp_. - -Every condition variable is associated with a mutex, which must be -owned when a thread waits for the condition using -[`nng_cv_wait()`](nng_cv_wait.md) or -[`nng_cv_until()`](nng_cv_until.md). -The mutex must also be owned when signaling the condition using the -[`nng_cv_wake()`](nng_cv_wake.md) or -[`nng_cv_wake1()`](nng_cv_wake1.md) functions. - -## RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_ENOMEM`: Insufficient free memory exists. - -## 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) diff --git a/docs/reference/src/api/threads/nng_cv_free.md b/docs/reference/src/api/threads/nng_cv_free.md deleted file mode 100644 index f7103f66..00000000 --- a/docs/reference/src/api/threads/nng_cv_free.md +++ /dev/null @@ -1,22 +0,0 @@ -# nng_cv_free - -## NAME - -nng_cv_free --- free condition variable - -### SYNOPSIS - -```c -#include -#include - -void nng_cv_free(nng_cv *cv); -``` - -## DESCRIPTION - -The `nng_cv_free()` function frees the condition variable _cv_. - -## SEE ALSO - -[nng_cv_alloc](nng_cv_alloc.md) diff --git a/docs/reference/src/api/threads/nng_cv_until.md b/docs/reference/src/api/threads/nng_cv_until.md deleted file mode 100644 index 620b46b7..00000000 --- a/docs/reference/src/api/threads/nng_cv_until.md +++ /dev/null @@ -1,75 +0,0 @@ -# nng_cv_until() - -## NAME - -nng_cv_until --- wait for condition or timeout - -## SYNOPSIS - -```c -#include -#include - -int nng_cv_until(nng_cv *cv, nng_time when); -``` - -## DESCRIPTION - -The `nng_cv_until()` waits until either the condition variable _cv_ is signaled -by another thread calling either -[`nng_cv_wake()`](nng_cv_wake.md) or -[`nng_cv_wake1()`](nng_cv_wake1.md), or the system clock (as tracked -by [`nng_clock()`](../util/nng_clock.md)) reaches _when_. - -The caller must have have ownership of the mutex that was used when -_cv_ was allocated. -This function will drop the ownership of that mutex, and reacquire it -atomically just before returning to the caller. -(The waiting is done without holding the mutex.) - -Spurious wakeups can occur. - -> [!TIP] -> Any condition may be used or checked, but the condition must be -> checked, as it is possible for this function to wake up spuriously. -> The best way to do this is inside a loop that repeats until the condition -> tests for true. - -## EXAMPLE - -The following example demonstrates use of this function: - -### Example 1: Waiting for the condition - -```c - expire = nng_clock() + 1000; // 1 second in the future - nng_mtx_lock(m); // assume cv was allocated using m - while (!condition_true) { - if (nng_cv_until(cv, expire) == NNG_ETIMEDOUT) { - printf("Time out reached!\n"); - break; - } - } - // condition_true is true - nng_mtx_unlock(m); -``` - -### Example 2: Signaling the condition - -```c - nng_mtx_lock(m); - condition_true = true; - nng_cv_wake(cv); - nng_mtx_unlock(m); -``` - -## SEE ALSO - -[nng_clock()](../util/nng_clock.md), -[nng_cv_alloc()](nng_cv_alloc.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_mtx_lock()](nng_mtx_lock.md), -[nng_mtx_unlock()](nng_mtx_unlock.md) diff --git a/docs/reference/src/api/threads/nng_cv_wait.md b/docs/reference/src/api/threads/nng_cv_wait.md deleted file mode 100644 index d384201c..00000000 --- a/docs/reference/src/api/threads/nng_cv_wait.md +++ /dev/null @@ -1,68 +0,0 @@ -# nng_cv_wait - -## NAME - -nng_cv_wait --- wait for condition - -## SYNOPSIS - -```c -#include -#include - -void nng_cv_wait(nng_cv *cv); -``` - -## DESCRIPTION - -The `nng_cv_wait()` waits for the condition variable _cv_ to be signaled -by another thread calling either [`nng_cv_wake()`](nng_cv_wake.md) or -[`nng_cv_wake1()`](nng_cv_wake1.md). - -The caller must have have ownership of the mutex that was used when -_cv_ was allocated. -This function will drop the ownership of that mutex, and reacquire it -atomically just before returning to the caller. -(The waiting is done without holding the mutex.) - -Spurious wakeups are possible. - -> [!TIP] -> Any condition may be used or checked, but the condition must be -> checked, as it is possible for this function to wake up spuriously. -> The best way to do this is inside a loop that repeats until the condition -> tests for true. - -## EXAMPLE - -The following example demonstrates use of this function: - -### Example 1: Waiting for the condition - -```c - nng_mtx_lock(m); // assume cv was allocated using m - while (!condition_true) { - nng_cv_wait(cv); - } - // condition_true is true - nng_mtx_unlock(m); -``` - -### Example 2: Signaling the condition - -```c - nng_mtx_lock(m); - condition_true = true; - nng_cv_wake(cv); - nng_mtx_unlock(m); -``` - -## 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) diff --git a/docs/reference/src/api/threads/nng_cv_wake.md b/docs/reference/src/api/threads/nng_cv_wake.md deleted file mode 100644 index 8d0d2fbd..00000000 --- a/docs/reference/src/api/threads/nng_cv_wake.md +++ /dev/null @@ -1,42 +0,0 @@ -# nng_cv_wake - -## NAME - -nng_cv_wake --- wake all waiters - -## SYNOPSIS - -```c -#include -#include - -void nng_cv_wake(nng_cv *cv); -``` - -## DESCRIPTION - -The `nng_cv_wake()` wakes any threads waiting for the condition variable _cv_ -to be signaled in the [`nng_cv_wait()`](nng_cv_wait.md) or -[`nng_cv_until()`](nng_cv_until.md) functions. - -The caller must have have ownership of the mutex that was used when -_cv_ was allocated. - -The caller should already have set the condition that the waiters -will check, while holding the mutex. - -> [!TIP] -> This function wakes all threads, which is generally safer but can -> lead to a performance problem when there are many waiters, as they are all -> woken simultaneously and may contend for resources. -> See [`nng_cv_wake1()`](nng_cv_wake1.md) for a solution to this problem. - -## 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) diff --git a/docs/reference/src/api/threads/nng_cv_wake1.md b/docs/reference/src/api/threads/nng_cv_wake1.md deleted file mode 100644 index 09b31755..00000000 --- a/docs/reference/src/api/threads/nng_cv_wake1.md +++ /dev/null @@ -1,42 +0,0 @@ -# nng_cv_wake1 - -## NAME - -nng_cv_wake1 --- wake one waiter - -## SYNOPSIS - -```c -#include -#include - -void nng_cv_wake1(nng_cv *cv); -``` - -## DESCRIPTION - -The `nng_cv_wake1()` wakes at most one thread waiting for the condition -variable _cv_ -to be signaled in the [`nng_cv_wait()`](nng_cv_wait.md) or -[`nng_cv_until()`](nng_cv_until.md) functions. - -The caller must have have ownership of the mutex that was used when -_cv_ was allocated. - -The caller should already have set the condition that the waiters -will check, while holding the mutex. - -> [!NOTE] -> The caller cannot predict which waiter will be woken, and so the design must -> ensure that it is sufficient that _any_ waiter be woken. -> When in doubt, it is safer to use [`nng_cv_wake()`](nng_cv_wake.md). - -## 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_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/threads/nng_mtx_alloc.md b/docs/reference/src/api/threads/nng_mtx_alloc.md deleted file mode 100644 index 64263d59..00000000 --- a/docs/reference/src/api/threads/nng_mtx_alloc.md +++ /dev/null @@ -1,44 +0,0 @@ -# nng_mtx_alloc - -## NAME - -nng_mtx_alloc - allocate mutex - -## SYNOPSIS - -```c -#include -#include - -typedef struct nng_mtx nng_mtx; - -int nng_mtx_alloc(nng_mtx **mtxp); -``` - -## DESCRIPTION - -The `nng_mtx_alloc()` function allocates mutex and returns it in _mtxp_. - -The mutex objects created by this function are suitable only for -simple lock and unlock operations, and are not recursive. -Every effort has been made to use light-weight underlying primitives when available. - -Mutex (mutual exclusion) objects can be thought of as binary semaphores, -where only a single thread of execution is permitted to acquire the semaphore. - -Furthermore, a mutex can only be unlocked by the thread that locked it. - -## RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_ENOMEM`: Insufficient free memory exists. - -## SEE ALSO - -[nng_cv_alloc](nng_cv_alloc.md), -[nng_mtx_free](nng_mtx_free.md), -[nng_mtx_lock](nng_mtx_lock.md), -[nng_mtx_unlock](nng_mtx_unlock.md) diff --git a/docs/reference/src/api/threads/nng_mtx_free.md b/docs/reference/src/api/threads/nng_mtx_free.md deleted file mode 100644 index a6fe7d7b..00000000 --- a/docs/reference/src/api/threads/nng_mtx_free.md +++ /dev/null @@ -1,23 +0,0 @@ -# nng_mtx_free - -## NAME - -nng_mtx_free --- free mutex - -## SYNOPSIS - -```c -#include -#include - -void nng_mtx_free(nng_mtx *mtx); -``` - -## DESCRIPTION - -The `nng_mtx_free()` function frees the mutex _mtx_. -The mutex must not be locked when this function is called. - -## SEE ALSO - -[nng_mtx_alloc](nng_mtx_alloc) diff --git a/docs/reference/src/api/threads/nng_mtx_lock.md b/docs/reference/src/api/threads/nng_mtx_lock.md deleted file mode 100644 index 2e50f010..00000000 --- a/docs/reference/src/api/threads/nng_mtx_lock.md +++ /dev/null @@ -1,38 +0,0 @@ -# nng_mtx_lock - -## NAME - -nng_mtx_lock --- lock mutex - -## SYNOPSIS - -```c -#include -#include - -void nng_mtx_lock(nng_mtx *mtx); -``` - -## DESCRIPTION - -The `nng_mtx_lock()` acquires exclusive ownership of the mutex _mtx_. -If the lock is already owned, this function will wait until the current -owner releases it with [`nng_mtx_unlock()`](nng_mtx_unlock.md). - -If multiple threads are waiting for the lock, the order of acquisition -is not specified. - -> [!NOTE] -> A mutex can _only_ be unlocked by the thread that locked it. - -> [!NOTE] -> Mutex locks are _not_ recursive; attempts to reacquire the -> same mutex may result in deadlock or aborting the current program. -> It is a programming error for the owner of a mutex to attempt to -> reacquire it. - -## SEE ALSO - -[nng_cv_alloc](nng_cv_alloc.md), -[nng_mtx_alloc](nng_mtx_alloc.md), -[nng_mtx_unlock](nng_mtx_unlock.md) diff --git a/docs/reference/src/api/threads/nng_mtx_unlock.md b/docs/reference/src/api/threads/nng_mtx_unlock.md deleted file mode 100644 index d5815287..00000000 --- a/docs/reference/src/api/threads/nng_mtx_unlock.md +++ /dev/null @@ -1,29 +0,0 @@ -# nng_mtx_unlock(3supp) - -## NAME - -nng_mtx_unlock --- unlock mutex - -## SYNOPSIS - -```c -#include -#include - -void nng_mtx_unlock(nng_mtx *mtx); -``` - -## DESCRIPTION - -The `nng_mtx_unlock()` relinquishes ownership of the mutex _mtx_ that -was previously acquired via [`nng_mtx_lock()`](nng_mtx_lock.md). - -> [!NOTE] -> A mutex can _only_ be unlocked by the thread that locked it. -> Attempting to unlock a mutex that is not owned by the caller will result -> in undefined behavior. - -## SEE ALSO - -[nng_mtx_alloc](nng_mtx_alloc), -[nng_mtx_lock](nng_mtx_lock) diff --git a/docs/reference/src/msg/index.md b/docs/reference/src/msg/index.md new file mode 100644 index 00000000..ed63b4d2 --- /dev/null +++ b/docs/reference/src/msg/index.md @@ -0,0 +1,99 @@ +# 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 mode][raw] need to +> access the message header. + +### Creating, Destroying and Using + +Messages are allocated using [`nng_msg_alloc()`][nng_msg_alloc], +and are deallocated using [`nng_msg_free()`][nng_msg_free]. + +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 "{{i:headroom}}" and "{{i: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][nng_aio_get_msg], +[nng_aio_set_msg][nng_aio_set_msg], +[nng_msg_alloc][nng_msg_alloc], +[nng_msg_append][nng_msg_append], +[nng_msg_body][nng_msg_body], +[nng_msg_capacity][nng_msg_capacity], +[nng_msg_dup][nng_msg_dup], +[nng_msg_free][nng_msg_free], +[nng_msg_header][nng_msg_header], +[nng_msg_header_append][nng_msg_header_append], +[nng_msg_header_chop][nng_msg_header_chop], +[nng_msg_header_clear][nng_msg_header_clear], +[nng_msg_header_insert][nng_msg_header_insert], +[nng_msg_header_len][nng_msg_header_len], +[nng_msg_header_trim][nng_msg_header_trim], +[nng_msg_insert][nng_msg_insert], +[nng_msg_len][nng_msg_len], +[nng_msg_reserve][nng_msg_reserve], +[nng_msg_realloc][nng_msg_realloc], +[nng_msg_set_pipe][nng_msg_set_pipe], +[nng_msg_trim][nng_msg_trim], +[nng_recvmsg][nng_recvmsg], +[nng_sendmsg][nng_sendmsg] + +{{#include ../refs.md}} diff --git a/docs/reference/src/msg/nng_msg_alloc.md b/docs/reference/src/msg/nng_msg_alloc.md new file mode 100644 index 00000000..cddb5364 --- /dev/null +++ b/docs/reference/src/msg/nng_msg_alloc.md @@ -0,0 +1,42 @@ +# 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][msg] with {{i: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], +[nng_msg_body][nng_msg_body], +[nng_msg_dup][nng_msg_dup], +[nng_msg_header][nng_msg_header], +[nng_msg_header_len][nng_msg_header_len], +[nng_msg_len][nng_msg_len], +[nng_msg_capacity][nng_msg_capacity], +[nng_msg_reserve][nng_msg_reserve], +[nng_msg_realloc][nng_msg_realloc] + +{{#include ../refs.md}} diff --git a/docs/reference/src/msg/nng_msg_append.md b/docs/reference/src/msg/nng_msg_append.md new file mode 100644 index 00000000..cb6120f5 --- /dev/null +++ b/docs/reference/src/msg/nng_msg_append.md @@ -0,0 +1,48 @@ +# 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] _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], +[nng_msg_body][nng_msg_body], +[nng_msg_capacity][nng_msg_capacity], +[nng_msg_chop][nng_msg_chop], +[nng_msg_clear][nng_msg_chop], +[nng_msg_free][nng_msg_free], +[nng_msg_insert][nng_msg_insert], +[nng_msg_len][nng_msg_len.md], +[nng_msg_reserve][nng_msg_reserve], +[nng_msg_realloc][nng_msg_realloc], +[nng_msg_trim][nng_msg_trim] + +{{#include ../refs.md}} diff --git a/docs/reference/src/msg/nng_msg_body.md b/docs/reference/src/msg/nng_msg_body.md new file mode 100644 index 00000000..1fd67227 --- /dev/null +++ b/docs/reference/src/msg/nng_msg_body.md @@ -0,0 +1,49 @@ +# 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 {{i:body}} +content of the [message][msg] _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], +> [`nng_msg_realloc()`][nng_msg_realloc], +> any of the [`nng_msg_trim()`][nng_msg_trim], +> [`nng_msg_chop()`][nng_msg_chop], +> [`nng_msg_append()`][nng_msg_append], +> or [`nng_msg_insert()`][nng_msg_insert] variants. + +## RETURN VALUES + +Pointer to start of message body. + +## SEE ALSO + +[nng_msg_alloc][nng_msg_alloc], +[nng_msg_append][nng_msg_append], +[nng_msg_capacity][nng_msg_capacity], +[nng_msg_chop][nng_msg_chop], +[nng_msg_clear][nng_msg_clear], +[nng_msg_free][nng_msg_free], +[nng_msg_insert][nng_msg_insert], +[nng_msg_len][nng_msg_len], +[nng_msg_reserve][nng_msg_reserve], +[nng_msg_realloc][nng_msg_realloc], +[nng_msg_trim][nng_msg_trim] + +{{#include ../refs.md}} diff --git a/docs/reference/src/msg/nng_msg_capacity.md b/docs/reference/src/msg/nng_msg_capacity.md new file mode 100644 index 00000000..82c7ad07 --- /dev/null +++ b/docs/reference/src/msg/nng_msg_capacity.md @@ -0,0 +1,32 @@ +# 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] _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], +[nng_msg_realloc][nng_msg_realloc], +[nng_msg_reserve][nng_msg_reserve] +[nng_msg_body][nng_msg_body] + +{{#include ../refs.md}} diff --git a/docs/reference/src/msg/nng_msg_chop.md b/docs/reference/src/msg/nng_msg_chop.md new file mode 100644 index 00000000..918d244b --- /dev/null +++ b/docs/reference/src/msg/nng_msg_chop.md @@ -0,0 +1,49 @@ +# 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] _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], +[nng_msg_append][nng_msg_alloc], +[nng_msg_body][nng_msg_body], +[nng_msg_capacity][nng_msg_capacity], +[nng_msg_clear][nng_msg_chop], +[nng_msg_free][nng_msg_free], +[nng_msg_insert][nng_msg_insert], +[nng_msg_len][nng_msg_len], +[nng_msg_reserve][nng_msg_reserve], +[nng_msg_realloc][nng_msg_realloc], +[nng_msg_trim][nng_msg_trim] + +{{#include ../refs.md}} diff --git a/docs/reference/src/msg/nng_msg_clear.md b/docs/reference/src/msg/nng_msg_clear.md new file mode 100644 index 00000000..54dcbbde --- /dev/null +++ b/docs/reference/src/msg/nng_msg_clear.md @@ -0,0 +1,25 @@ +# 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 [message][msg] _msg_ to zero. + +## SEE ALSO + +[nng_msg_alloc][nng_msg_alloc], +[nng_msg_capacity][nng_msg_capacity], +[nng_msg_reserve][nng_msg_reserve] + +{{#include ../refs.md}} diff --git a/docs/reference/src/msg/nng_msg_dup.md b/docs/reference/src/msg/nng_msg_dup.md new file mode 100644 index 00000000..2f657307 --- /dev/null +++ b/docs/reference/src/msg/nng_msg_dup.md @@ -0,0 +1,36 @@ +# 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], +[nng_msg_free][nng_msg_free] + +{{#include ../refs.md}} diff --git a/docs/reference/src/msg/nng_msg_free.md b/docs/reference/src/msg/nng_msg_free.md new file mode 100644 index 00000000..6a84ee55 --- /dev/null +++ b/docs/reference/src/msg/nng_msg_free.md @@ -0,0 +1,24 @@ +# 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] _msg_ entirely. + +## SEE ALSO + +[nng_msg_alloc][nng_msg_alloc], +[nng_msg_realloc][nng_msg_realloc] + +{{#include ../refs.md}} diff --git a/docs/reference/src/msg/nng_msg_get_pipe.md b/docs/reference/src/msg/nng_msg_get_pipe.md new file mode 100644 index 00000000..9f37692b --- /dev/null +++ b/docs/reference/src/msg/nng_msg_get_pipe.md @@ -0,0 +1,46 @@ +# nng_msg_get_pipe + +## NAME + +nng_msg_get_pipe --- get pipe for message + +## SYNOPSIS + +```c +#include + +nng_pipe nng_msg_get_pipe(nng_msg *msg); +``` + +## DESCRIPTION + +The `nng_msg_get_pipe()` returns the [`nng_pipe`][pipe] object +associated with [message][msg] _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 [`nng_pipe_get()`][nng_pipe_get] 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. + +## SEE ALSO + +[nng_msg_alloc][nng_msg_alloc], +[nng_msg_set_pipe][nng_msg_set_pipe], +[nng_pipe_get][nng_pipe_get] + +{{#include ../refs.md}} diff --git a/docs/reference/src/msg/nng_msg_header.md b/docs/reference/src/msg/nng_msg_header.md new file mode 100644 index 00000000..7b072c18 --- /dev/null +++ b/docs/reference/src/msg/nng_msg_header.md @@ -0,0 +1,44 @@ +# nng_msg_header + +## NAME + +nng_msg_header --- return message header + +## SYNOPSIS + +```c +#include + +void *nng_msg_header(nng_msg *msg); +``` + +## DESCRIPTION + +The `nng_msg_header()` function returns a pointer to the start of the {{i:header}} +content of the [message][msg] _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][raw] sockets. + +> [!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. + +## SEE ALSO + +[nng_msg_alloc][nng_msg_alloc], +[nng_msg_body][nng_msg_body], +[nng_msg_free][nng_msg_free], +[nng_msg_header_append][nng_msg_header_append], +[nng_msg_header_chop][nng_msg_header_chop], +[nng_msg_header_insert][nng_msg_header_insert] +[nng_msg_header_len][nng_msg_header_len], +[nng_msg_header_trim][nng_msg_header_trim] + +{{#include ../refs.md}} diff --git a/docs/reference/src/msg/nng_msg_header_append.md b/docs/reference/src/msg/nng_msg_header_append.md new file mode 100644 index 00000000..6799bfac --- /dev/null +++ b/docs/reference/src/msg/nng_msg_header_append.md @@ -0,0 +1,43 @@ +# nng_msg_header_append + +## NAME + +nng_msg_header_append --- append to message header + +## SYNOPSIS + +```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 header of [message][msg] _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 + +- `NNG_ENOMEM`: Insufficient free memory exists. + +## SEE ALSO + +[nng_msg_header][nng_msg_body], +[nng_msg_header_chop][nng_msg_header_chop], +[nng_msg_header_insert][nng_msg_header_insert] +[nng_msg_header_len][nng_msg_header_len], +[nng_msg_header_trim][nng_msg_header_trim] + +{{#include ../refs.md}} diff --git a/docs/reference/src/msg/nng_msg_header_chop.md b/docs/reference/src/msg/nng_msg_header_chop.md new file mode 100644 index 00000000..c95242dc --- /dev/null +++ b/docs/reference/src/msg/nng_msg_header_chop.md @@ -0,0 +1,44 @@ +# nng_msg_header_chop + +## NAME + +nng_msg_header_chop --- remove data from end of message header + +## SYNOPSIS + +```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] _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 + +- `NNG_EINVAL`: The message header is too short to remove the requested data. + +## SEE ALSO + +[nng_msg_header][nng_msg_body], +[nng_msg_header_append][nng_msg_header_append], +[nng_msg_header_insert][nng_msg_header_insert] +[nng_msg_header_len][nng_msg_header_len], +[nng_msg_header_trim][nng_msg_header_trim] + +{{#include ../refs.md}} diff --git a/docs/reference/src/msg/nng_msg_header_clear.md b/docs/reference/src/msg/nng_msg_header_clear.md new file mode 100644 index 00000000..5ffb4ed7 --- /dev/null +++ b/docs/reference/src/msg/nng_msg_header_clear.md @@ -0,0 +1,24 @@ +# nng_msg_header_clear + +## NAME + +nng_msg_header_clear --- clear message header + +## SYNOPSIS + +```c +#include + +void nng_msg_header_clear(nng_msg *msg); +``` + +## DESCRIPTION + +The `nng_msg_clear()` function resets the header length of [messaage][msg] _msg_ to zero. + +## SEE ALSO + +[nng_msg_header][nng_msg_header], +[nng_msg_header_len][nng_msg_header_len] + +{{#include ../refs.md}} diff --git a/docs/reference/src/msg/nng_msg_header_insert.md b/docs/reference/src/msg/nng_msg_header_insert.md new file mode 100644 index 00000000..211bcb05 --- /dev/null +++ b/docs/reference/src/msg/nng_msg_header_insert.md @@ -0,0 +1,43 @@ +# nng_msg_header_insert + +## NAME + +nng_msg_header_insert --- prepend to message header + +## SYNOPSIS + +```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] _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 + +- `NNG_ENOMEM`: Insufficient free memory exists. + +## SEE ALSO + +[nng_msg_header][nng_msg_header], +[nng_msg_header_append][nng_msg_header_append] +[nng_msg_header_chop][nng_msg_header_chop], +[nng_msg_header_len][nng_msg_header_len], +[nng_msg_header_trim][nng_msg_header_trim] + +{{#include ../refs.md}} diff --git a/docs/reference/src/msg/nng_msg_header_len.md b/docs/reference/src/msg/nng_msg_header_len.md new file mode 100644 index 00000000..65d4fb1b --- /dev/null +++ b/docs/reference/src/msg/nng_msg_header_len.md @@ -0,0 +1,27 @@ +# nng_msg_header_len + +## NAME + +nng_msg_header_len --- return message header length + +## SYNOPSIS + +```c +#include + +size_t nng_msg_header_len(nng_msg *msg); +``` + +## DESCRIPTION + +The `nng_msg_header_len()` returns the length of the header of [message][msg] _msg_. + +## RETURN VALUES + +Length of message header. + +## SEE ALSO + +[nng_msg_header][nng_msg_header] + +{{#include ../refs.md}} diff --git a/docs/reference/src/msg/nng_msg_header_trim.md b/docs/reference/src/msg/nng_msg_header_trim.md new file mode 100644 index 00000000..4824e7aa --- /dev/null +++ b/docs/reference/src/msg/nng_msg_header_trim.md @@ -0,0 +1,44 @@ +# nng_msg_header_trim + +## NAME + +nng_msg_header_trim --- remove data from start of message header + +## SYNOPSIS + +```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] _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 + +- `NNG_EINVAL`: The message header is too short to remove the requested data. + +## SEE ALSO + +[nng_msg_header][nng_msg_body], +[nng_msg_header_append][nng_msg_header_append], +[nng_msg_header_chop][nng_msg_header_chop] +[nng_msg_header_insert][nng_msg_header_insert] +[nng_msg_header_len][nng_msg_header_len], + +{{#include ../refs.md}} diff --git a/docs/reference/src/msg/nng_msg_insert.md b/docs/reference/src/msg/nng_msg_insert.md new file mode 100644 index 00000000..23cee46f --- /dev/null +++ b/docs/reference/src/msg/nng_msg_insert.md @@ -0,0 +1,55 @@ +# nng_msg_insert + +## NAME + +nng_msg_insert --- prepend to message body + +## SYNOPSIS + +```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] _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 + +- `NNG_ENOMEM`: Insufficient free memory exists. + +## SEE ALSO + +[nng_msg_alloc][nng_msg_alloc], +[nng_msg_append][nng_msg_append], +[nng_msg_body][nng_msg_body], +[nng_msg_capacity][nng_msg_capacity], +[nng_msg_chop][nng_msg_chop], +[nng_msg_clear][nng_msg_chop], +[nng_msg_free][nng_msg_free], +[nng_msg_insert][nng_msg_insert], +[nng_msg_len][nng_msg_len], +[nng_msg_reserve][nng_msg_reserve], +[nng_msg_realloc][nng_msg_realloc], +[nng_msg_trim][nng_msg_trim] + +{{#include ../refs.md}} diff --git a/docs/reference/src/msg/nng_msg_len.md b/docs/reference/src/msg/nng_msg_len.md new file mode 100644 index 00000000..7a165138 --- /dev/null +++ b/docs/reference/src/msg/nng_msg_len.md @@ -0,0 +1,28 @@ +# nng_msg_len + +## NAME + +nng_msg_len --- return message body length + +## SYNOPSIS + +```c +#include + +size_t nng_msg_len(nng_msg *msg); +``` + +## DESCRIPTION + +The `nng_msg_len()` returns the length of the body of [message][msg] _msg_. + +## RETURN VALUES + +Length of message body. + +## SEE ALSO + +[nng_msg_alloc](nng_msg_alloc), +[nng_msg_body](nng_msg_body) + +{{#include ../refs.md}} diff --git a/docs/reference/src/msg/nng_msg_realloc.md b/docs/reference/src/msg/nng_msg_realloc.md new file mode 100644 index 00000000..82c55cb6 --- /dev/null +++ b/docs/reference/src/msg/nng_msg_realloc.md @@ -0,0 +1,55 @@ +# nng_msg_realloc(3) + +## NAME + +nng_msg_realloc --- reallocate a message + +## SYNOPSIS + +```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 {{i: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 [`nng_msg_append()`][nng_msg_append], +allocations may be reduced by first using +[`nng_msg_reserve()`][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 [`nng_msg_capacity()`][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 + +- `NNG_ENOMEM`: Insufficient free memory exists to reallocate a message. + +## SEE ALSO + +[nng_msg_alloc][nng_msg_alloc], +[nng_msg_reserve][nng_msg_reserve], +[nng_msg_append][nng_msg_append], +[nng_msg_body][nng_msg_body], +[nng_msg_chop][nng_msg_chop], +[nng_msg_free][nng_msg_free], +[nng_msg_insert][nng_msg_insert], +[nng_msg_len][nng_msg_len], +[nng_msg_trim][nng_msg_trim] + +{{#include ../refs.md}} diff --git a/docs/reference/src/msg/nng_msg_reserve.md b/docs/reference/src/msg/nng_msg_reserve.md new file mode 100644 index 00000000..c6accd19 --- /dev/null +++ b/docs/reference/src/msg/nng_msg_reserve.md @@ -0,0 +1,48 @@ +# nng_msg_reserve + +## NAME + +nng_msg_reserve --- reserve storage for a message + +## SYNOPSIS + +```c +#include + +int nng_msg_reserve(nng_msg *msg, size_t capacity); +``` + +## DESCRIPTION + +The `nng_msg_reserve()` function ensures a [message][msg] 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 [`nng_msg_append()`][nng_msg_append] +> will prevent additional memory allocations until the message's length exceeds +> the alotted capacity. + +> [!IMPORTANT] +> 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 + +- `NNG_ENOMEM`: Insufficient free memory exists to reallocate a message. + +## SEE ALSO + +[nng_msg_alloc][nng_msg_alloc], +[nng_msg_append][nng_msg_append], +[nng_msg_capacity][nng_msg_capacity], +[nng_msg_insert][nng_msg_insert], +[nng_msg_len][nng_msg_len] + +{{#include ../refs.md}} diff --git a/docs/reference/src/msg/nng_msg_set_pipe.md b/docs/reference/src/msg/nng_msg_set_pipe.md new file mode 100644 index 00000000..5e2f60d5 --- /dev/null +++ b/docs/reference/src/msg/nng_msg_set_pipe.md @@ -0,0 +1,31 @@ +# nng_msg_set_pipe + +## NAME + +nng_msg_set_pipe --- set pipe for message + +## SYNOPSIS + +```c +#include + +void nng_msg_set_pipe(nng_msg *msg, nng_pipe p); +``` + +## DESCRIPTION + +The `nng_msg_set_pipe()` sets the [pipe][pipe] associated with [message][msg] _m_ to _p_. +This is most often useful when used with protocols that support directing +a message to a specific peer. +For example the [_PAIR_][pair] version 1 protocol can do +this when `NNG_OPT_PAIR1_POLY` mode is set. + +> [!NOTE] +> Not all protocols support overriding the destination pipe. + +## SEE ALSO + +[nng_msg_alloc][nng_msg_alloc], +[nng_msg_get_pipe][nng_msg_get_pipe] + +{{#include ../refs.md}} diff --git a/docs/reference/src/msg/nng_msg_trim.md b/docs/reference/src/msg/nng_msg_trim.md new file mode 100644 index 00000000..258fe4c1 --- /dev/null +++ b/docs/reference/src/msg/nng_msg_trim.md @@ -0,0 +1,50 @@ +# 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] _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], +[nng_msg_append][nng_msg_alloc], +[nng_msg_body][nng_msg_body], +[nng_msg_capacity][nng_msg_capacity], +[nng_msg_chop][nng_msg_chop] +[nng_msg_clear][nng_msg_chop], +[nng_msg_free][nng_msg_free], +[nng_msg_insert][nng_msg_insert], +[nng_msg_len][nng_msg_len], +[nng_msg_reserve][nng_msg_reserve], +[nng_msg_realloc][nng_msg_realloc] + +{{#include ../refs.md}} diff --git a/docs/reference/src/refs.md b/docs/reference/src/refs.md index d1201354..2b4b0b65 100644 --- a/docs/reference/src/refs.md +++ b/docs/reference/src/refs.md @@ -3,8 +3,11 @@ [context]: ../overview/context.md [device]: ../overview/device.md [duration]: ../overview/duration.md -[msg]: ../overview/msg.md +[msg]: ../msg/index.md [pipe]: ../overview/pipe.md +[sockadddr]: ../overview/sockaddr.md +[sockaddr_in]: ../overview/sockaddr_in.md +[sockaddr_in6]: ../overview/sockaddr_in6.md [raw]: ../overview/raw.md [url]: ../overview/url.md @@ -25,8 +28,6 @@ [nng_bus_open]: ../api/nng_bus_open.md [nng_ctx_open]: ../api/nng_ctx_open.md -[nng_msg_get_pipe]: ../api/nng_msg_get_pipe.md -[nng_msg_set_pipe]: ../api/nng_msg_set_pipe.md [nng_pair_open]: ../api/nng_pair_open.md [nng_pub_open]: ../api/nng_pub_open.md [nng_pull_open]: ../api/nng_pull_open.md @@ -38,10 +39,40 @@ [nng_surveyor_open]: ../api/nng_surveyor_open.md [nng_sub_open]: ../api/nng_sub_open.md + + +[nng_msg_alloc]: ../nng_msg_alloc.md +[nng_msg_append]: ../msg/nng_msg_append.md +[nng_msg_body]: ../msg/nng_msg_body.md +[nng_msg_capacity]: ../msg/nng_msg_capacity.md +[nng_msg_chop]: ../msg/nng_msg_chop.md +[nng_msg_clear]: ../msg/nng_msg_clear.md +[nng_msg_dup]: ../msg/nng_msg_dup.md +[nng_msg_free]: ../msg/nng_msg_free.md +[nng_msg_get_pipe]: ../msg/nng_msg_get_pipe.md +[nng_msg_header]: ../msg/nng_msg_header.md +[nng_msg_header_append]: ../msg/nng_msg_header_append.md +[nng_msg_header_chop]: ../msg/nng_msg_header_chop.md +[nng_msg_header_clear]: ../msg/nng_msg_header_clear.md +[nng_msg_header_insert]: ../msg/nng_msg_header_insert.md +[nng_msg_header_len]: ../msg/nng_msg_header_len.md +[nng_msg_header_trim]: ../msg/nng_msg_header_trim.md +[nng_msg_insert]: ../msg/nng_msg_insert.md +[nng_msg_len]: ../msg/nng_msg_len.md +[nng_msg_realloc]: ../msg/nng_msg_realloc.md +[nng_msg_reserve]: ../msg/nng_msg_reserve.md +[nng_msg_set_pipe]: ../msg/nng_msg_set_pipe.md +[nng_msg_trim]: ../msg/nng_msg_trim.md + [NNG_OPT_MAXTTL]: ../opts/nng_opt_max_ttl.md [NNG_OPT_SENDBUF]: ../opts/nng_opt_sendbuf.md +[NNG_OPT_LOCADDR]: ../opts/nng_opt_locaddr.md +[NNG_OPT_REMADDR]: ../api/nng_options.md#NNG_OPT_REMADDR +[NNG_OPT_TCP_KEEPALIVE]: ../api/nng_tcp_options.md#NNG_OPT_TCP_KEEPALIVE +[NNG_OPT_TCP_NODELAY]: ../api/nng_tcp_options.md#NNG_OPT_TCP_NODELAY +[NNG_OPT_URL]: ../api/nng_options.md#NNG_OPT_URL diff --git a/docs/reference/src/thr/nng_cv_alloc.md b/docs/reference/src/thr/nng_cv_alloc.md new file mode 100644 index 00000000..8545958a --- /dev/null +++ b/docs/reference/src/thr/nng_cv_alloc.md @@ -0,0 +1,48 @@ +# nng_cv_alloc + +## NAME + +nng_cv_alloc --- allocate condition variable + +## SYNOPSIS + +```c +#include +#include + +typedef struct nng_cv nng_cv; + +int nng_cv_alloc(nng_cv **cvp, nng_mtx *mtx); +``` + +## DESCRIPTION + +The `nng_cv_alloc()` function allocates a {{i:condition variable}}, using +the mutex _mtx_, and returns it in _cvp_. + +Every condition variable is associated with a mutex, which must be +owned when a thread waits for the condition using +[`nng_cv_wait()`][nng_cv_wait] or +[`nng_cv_until()`][nng_cv_until]. +The mutex must also be owned when signaling the condition using the +[`nng_cv_wake()`][nng_cv_wake] or +[`nng_cv_wake1()`][nng_cv_wake1] functions. + +## RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +## ERRORS + +- `NNG_ENOMEM`: Insufficient free memory exists. + +## SEE ALSO + +[nng_cv_free][nng_cv_free], +[nng_cv_until][nng_cv_until], +[nng_cv_wait][nng_cv_wait], +[nng_cv_wake][nng_cv_wake], +[nng_cv_wake1][nng_cv_wake1], +[nng_mtx_alloc][nng_mtx_alloc] + +{{#include ../refs.md}} diff --git a/docs/reference/src/thr/nng_cv_free.md b/docs/reference/src/thr/nng_cv_free.md new file mode 100644 index 00000000..d2de68af --- /dev/null +++ b/docs/reference/src/thr/nng_cv_free.md @@ -0,0 +1,24 @@ +# nng_cv_free + +## NAME + +nng_cv_free --- free condition variable + +### SYNOPSIS + +```c +#include +#include + +void nng_cv_free(nng_cv *cv); +``` + +## DESCRIPTION + +The `nng_cv_free()` function frees the condition variable _cv_. + +## SEE ALSO + +[nng_cv_alloc][nng_cv_alloc] + +{{#include ../refs.md}} diff --git a/docs/reference/src/thr/nng_cv_until.md b/docs/reference/src/thr/nng_cv_until.md new file mode 100644 index 00000000..dde512c1 --- /dev/null +++ b/docs/reference/src/thr/nng_cv_until.md @@ -0,0 +1,77 @@ +# nng_cv_until() + +## NAME + +nng_cv_until --- wait for condition or timeout + +## SYNOPSIS + +```c +#include +#include + +int nng_cv_until(nng_cv *cv, nng_time when); +``` + +## DESCRIPTION + +The `nng_cv_until()` waits until either the condition variable _cv_ is signaled +by another thread calling either +[`nng_cv_wake()`][nng_cv_wake] or +[`nng_cv_wake1()`][nng_cv_wake1], or the system clock (as tracked +by [`nng_clock()`](../util/nng_clock.md)) reaches _when_. + +The caller must have have ownership of the mutex that was used when +_cv_ was allocated. +This function will drop the ownership of that mutex, and reacquire it +atomically just before returning to the caller. +(The waiting is done without holding the mutex.) + +Spurious wakeups can occur. + +> [!TIP] +> Any condition may be used or checked, but the condition must be +> checked, as it is possible for this function to wake up spuriously. +> The best way to do this is inside a loop that repeats until the condition +> tests for true. + +## EXAMPLE + +The following example demonstrates use of this function: + +### Example 1: Waiting for the condition + +```c + expire = nng_clock() + 1000; // 1 second in the future + nng_mtx_lock(m); // assume cv was allocated using m + while (!condition_true) { + if (nng_cv_until(cv, expire) == NNG_ETIMEDOUT) { + printf("Time out reached!\n"); + break; + } + } + // condition_true is true + nng_mtx_unlock(m); +``` + +### Example 2: Signaling the condition + +```c + nng_mtx_lock(m); + condition_true = true; + nng_cv_wake(cv); + nng_mtx_unlock(m); +``` + +## SEE ALSO + +[nng_clock()](../util/nng_clock.md), +[nng_cv_alloc()][nng_cv_alloc], +[nng_cv_wait()][nng_cv_wait], +[nng_cv_wake()][nng_cv_wake], +[nng_cv_wake1()][nng_cv_wake1], +[nng_mtx_alloc()][nng_mtx_alloc], +[nng_mtx_lock()][nng_mtx_lock], +[nng_mtx_unlock()][nng_mtx_unlock] + +{{#include ../refs.md}} diff --git a/docs/reference/src/thr/nng_cv_wait.md b/docs/reference/src/thr/nng_cv_wait.md new file mode 100644 index 00000000..bf5f13a5 --- /dev/null +++ b/docs/reference/src/thr/nng_cv_wait.md @@ -0,0 +1,70 @@ +# nng_cv_wait + +## NAME + +nng_cv_wait --- wait for condition + +## SYNOPSIS + +```c +#include +#include + +void nng_cv_wait(nng_cv *cv); +``` + +## DESCRIPTION + +The `nng_cv_wait()` waits for the condition variable _cv_ to be signaled +by another thread calling either [`nng_cv_wake()`][nng_cv_wake] or +[`nng_cv_wake1()`][nng_cv_wake1]. + +The caller must have have ownership of the mutex that was used when +_cv_ was allocated. +This function will drop the ownership of that mutex, and reacquire it +atomically just before returning to the caller. +(The waiting is done without holding the mutex.) + +Spurious wakeups are possible. + +> [!TIP] +> Any condition may be used or checked, but the condition must be +> checked, as it is possible for this function to wake up spuriously. +> The best way to do this is inside a loop that repeats until the condition +> tests for true. + +## EXAMPLE + +The following example demonstrates use of this function: + +### Example 1: Waiting for the condition + +```c + nng_mtx_lock(m); // assume cv was allocated using m + while (!condition_true) { + nng_cv_wait(cv); + } + // condition_true is true + nng_mtx_unlock(m); +``` + +### Example 2: Signaling the condition + +```c + nng_mtx_lock(m); + condition_true = true; + nng_cv_wake(cv); + nng_mtx_unlock(m); +``` + +## SEE ALSO + +[nng_cv_alloc][nng_cv_alloc], +[nng_cv_until][nng_cv_until], +[nng_cv_wake][nng_cv_wake], +[nng_cv_wake1][nng_cv_wake1], +[nng_mtx_alloc][nng_mtx_alloc], +[nng_mtx_lock][nng_mtx_lock], +[nng_mtx_unlock][nng_mtx_unlock] + +{{#include ../refs.md}} diff --git a/docs/reference/src/thr/nng_cv_wake.md b/docs/reference/src/thr/nng_cv_wake.md new file mode 100644 index 00000000..b01f27d5 --- /dev/null +++ b/docs/reference/src/thr/nng_cv_wake.md @@ -0,0 +1,44 @@ +# nng_cv_wake + +## NAME + +nng_cv_wake --- wake all waiters + +## SYNOPSIS + +```c +#include +#include + +void nng_cv_wake(nng_cv *cv); +``` + +## DESCRIPTION + +The `nng_cv_wake()` wakes any threads waiting for the condition variable _cv_ +to be signaled in the [`nng_cv_wait()`][nng_cv_wait] or +[`nng_cv_until()`][nng_cv_until] functions. + +The caller must have have ownership of the mutex that was used when +_cv_ was allocated. + +The caller should already have set the condition that the waiters +will check, while holding the mutex. + +> [!TIP] +> This function wakes all threads, which is generally safer but can +> lead to a performance problem when there are many waiters, as they are all +> woken simultaneously and may contend for resources. +> See [`nng_cv_wake1()`][nng_cv_wake1] for a solution to this problem. + +## SEE ALSO + +[nng_cv_alloc][nng_cv_alloc], +[nng_cv_until][nng_cv_until], +[nng_cv_wait][nng_cv_wait], +[nng_cv_wake1][nng_cv_wake1], +[nng_mtx_alloc][nng_mtx_alloc], +[nng_mtx_lock][nng_mtx_lock], +[nng_mtx_unlock][nng_mtx_unlock] + +{{#include ../refs.md}} diff --git a/docs/reference/src/thr/nng_cv_wake1.md b/docs/reference/src/thr/nng_cv_wake1.md new file mode 100644 index 00000000..4464d9bb --- /dev/null +++ b/docs/reference/src/thr/nng_cv_wake1.md @@ -0,0 +1,44 @@ +# nng_cv_wake1 + +## NAME + +nng_cv_wake1 --- wake one waiter + +## SYNOPSIS + +```c +#include +#include + +void nng_cv_wake1(nng_cv *cv); +``` + +## DESCRIPTION + +The `nng_cv_wake1()` wakes at most one thread waiting for the condition +variable _cv_ +to be signaled in the [`nng_cv_wait()`][nng_cv_wait] or +[`nng_cv_until()`][nng_cv_until] functions. + +The caller must have have ownership of the mutex that was used when +_cv_ was allocated. + +The caller should already have set the condition that the waiters +will check, while holding the mutex. + +> [!NOTE] +> The caller cannot predict which waiter will be woken, and so the design must +> ensure that it is sufficient that _any_ waiter be woken. +> When in doubt, it is safer to use [`nng_cv_wake()`][nng_cv_wake]. + +## SEE ALSO + +[nng_cv_alloc][nng_cv_alloc], +[nng_cv_until][nng_cv_until], +[nng_cv_wait][nng_cv_wait], +[nng_cv_wake][nng_cv_wake], +[nng_mtx_alloc][nng_mtx_alloc], +[nng_mtx_lock][nng_mtx_lock], +[nng_mtx_unlock][nng_mtx_unlock] + +{{#include ../refs.md}} diff --git a/docs/reference/src/thr/nng_mtx_alloc.md b/docs/reference/src/thr/nng_mtx_alloc.md new file mode 100644 index 00000000..c4c38562 --- /dev/null +++ b/docs/reference/src/thr/nng_mtx_alloc.md @@ -0,0 +1,46 @@ +# nng_mtx_alloc + +## NAME + +nng_mtx_alloc --- allocate mutex + +## SYNOPSIS + +```c +#include +#include + +typedef struct nng_mtx nng_mtx; + +int nng_mtx_alloc(nng_mtx **mtxp); +``` + +## DESCRIPTION + +The `nng_mtx_alloc()` function allocates {{i:mutex}} and returns it in _mtxp_. + +The mutex objects created by this function are suitable only for +simple lock and unlock operations, and are not recursive. +Every effort has been made to use light-weight underlying primitives when available. + +Mutex (mutual exclusion) objects can be thought of as binary semaphores, +where only a single thread of execution is permitted to acquire the semaphore. + +Furthermore, a mutex can only be unlocked by the thread that locked it. + +## RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +## ERRORS + +- `NNG_ENOMEM`: Insufficient free memory exists. + +## SEE ALSO + +[nng_cv_alloc][nng_cv_alloc], +[nng_mtx_free][nng_mtx_free], +[nng_mtx_lock][nng_mtx_lock], +[nng_mtx_unlock][nng_mtx_unlock] + +{{#include ../refs.md}} diff --git a/docs/reference/src/thr/nng_mtx_free.md b/docs/reference/src/thr/nng_mtx_free.md new file mode 100644 index 00000000..ac759331 --- /dev/null +++ b/docs/reference/src/thr/nng_mtx_free.md @@ -0,0 +1,25 @@ +# nng_mtx_free + +## NAME + +nng_mtx_free --- free mutex + +## SYNOPSIS + +```c +#include +#include + +void nng_mtx_free(nng_mtx *mtx); +``` + +## DESCRIPTION + +The `nng_mtx_free()` function frees the mutex _mtx_. +The mutex must not be locked when this function is called. + +## SEE ALSO + +[nng_mtx_alloc](nng_mtx_alloc) + +{{#include ../refs.md}} diff --git a/docs/reference/src/thr/nng_mtx_lock.md b/docs/reference/src/thr/nng_mtx_lock.md new file mode 100644 index 00000000..be84afe8 --- /dev/null +++ b/docs/reference/src/thr/nng_mtx_lock.md @@ -0,0 +1,40 @@ +# nng_mtx_lock + +## NAME + +nng_mtx_lock --- lock mutex + +## SYNOPSIS + +```c +#include +#include + +void nng_mtx_lock(nng_mtx *mtx); +``` + +## DESCRIPTION + +The `nng_mtx_lock()` acquires exclusive ownership of the mutex _mtx_. +If the lock is already owned, this function will wait until the current +owner releases it with [`nng_mtx_unlock()`][nng_mtx_unlock]. + +If multiple threads are waiting for the lock, the order of acquisition +is not specified. + +> [!NOTE] +> A mutex can _only_ be unlocked by the thread that locked it. + +> [!NOTE] +> Mutex locks are _not_ recursive; attempts to reacquire the +> same mutex may result in deadlock or aborting the current program. +> It is a programming error for the owner of a mutex to attempt to +> reacquire it. + +## SEE ALSO + +[nng_cv_alloc][nng_cv_alloc], +[nng_mtx_alloc][nng_mtx_alloc], +[nng_mtx_unlock][nng_mtx_unlock] + +{{#include ../refs.md}} diff --git a/docs/reference/src/thr/nng_mtx_unlock.md b/docs/reference/src/thr/nng_mtx_unlock.md new file mode 100644 index 00000000..60fe2f4f --- /dev/null +++ b/docs/reference/src/thr/nng_mtx_unlock.md @@ -0,0 +1,31 @@ +# nng_mtx_unlock(3supp) + +## NAME + +nng_mtx_unlock --- unlock mutex + +## SYNOPSIS + +```c +#include +#include + +void nng_mtx_unlock(nng_mtx *mtx); +``` + +## DESCRIPTION + +The `nng_mtx_unlock()` relinquishes ownership of the mutex _mtx_ that +was previously acquired via [`nng_mtx_lock()`][nng_mtx_lock]. + +> [!NOTE] +> A mutex can _only_ be unlocked by the thread that locked it. +> Attempting to unlock a mutex that is not owned by the caller will result +> in undefined behavior. + +## SEE ALSO + +[nng_mtx_alloc](nng_mtx_alloc), +[nng_mtx_lock](nng_mtx_lock) + +{{#include ../refs.md}} diff --git a/docs/reference/src/tran/index.md b/docs/reference/src/tran/index.md new file mode 100644 index 00000000..2e61d68d --- /dev/null +++ b/docs/reference/src/tran/index.md @@ -0,0 +1,13 @@ +# Transports + +This chapter provides information about the various transports that _NNG_ supports. {{hi:transport}} +Transports may be thought of as different underlying communications +technologies, such as TCP, Websockets, and so forth. + +## INPROC + +The [{{i:*inproc* transport}}][inproc] provides {{i: intra-process}} communication within a single process. + +## TCP + +The [{{i:*tcp* transport}}][tcp] provides communication over {{i:TCP/IP}} networks. diff --git a/docs/reference/src/tran/inproc.md b/docs/reference/src/tran/inproc.md new file mode 100644 index 00000000..bf5ae8d6 --- /dev/null +++ b/docs/reference/src/tran/inproc.md @@ -0,0 +1,49 @@ +# INPROC Transport + +The {{i:*inproc* transport}}{{hi:*inproc*}}{{intra-process}} provides communication support between +sockets within the same process. +This may be used as an alternative +to slower transports when data must be moved within the same process. + +This transport tries hard to avoid copying data, and thus is very +light-weight. + +## URI Format + +This transport uses URIs using the scheme {{i:`inproc://`}}, followed by +an arbitrary string of text, terminated by a `NUL` byte. + +Multiple URIs can be used within the +same application, and they will not interfere with one another. + +Two applications may also use the same URI without interfering with each +other, and they will be unable to communicate with each other using +that URI. + +## Socket Address + +When using an [`nng_sockaddr`](../api/nng_sockaddr.md) structure, +the actual structure is of type +[`nng_sockaddr_inproc`](../api/nng_sockaddr_inproc.md). + +## Transport Options + +The _inproc_ transport has no special options. + +> [!NOTE] +> While _inproc_ accepts the option [`NNG_OPT_RECVMAXSZ`] for +> compatibility, the value of the option is ignored with no enforcement. +> As _inproc_ peers are in the same address space, they are implicitly +> trusted, so the protection afforded by `NNG_OPT_RECVMAXSZ` is unnecessary. + +## Mixing Implementations + +When mixing the _NNG_ library with other implementations of these +protocols in the same process (such as the _mangos_ +or _libnanomsg_ implementations), it will not be possible to utilize +the _inproc_ transport to communicate across this boundary. + +This limitation also extends to using different instances of the _NNG_ +library within the same process. + +{{#include ../refs.md}} diff --git a/docs/reference/src/tran/tcp.md b/docs/reference/src/tran/tcp.md new file mode 100644 index 00000000..8085a978 --- /dev/null +++ b/docs/reference/src/tran/tcp.md @@ -0,0 +1,72 @@ +# TCP transport + +The {{i:*tcp* transport}}{{hi:*tcp*}} provides communication support between +sockets across a {{i:TCP/IP}} network. + +Both IPv4 and {{i:IPv6}} are supported when the underlying platform also supports it. + +## URI Format + +This transport uses URIs using the scheme {{i:`tcp://`}}, followed by +an IP address or hostname, followed by a colon and finally a +TCP {{i:port number}}. +For example, to contact port 80 on the localhost either of the following URIs +could be used: `tcp://127.0.0.1:80` or `tcp://localhost:80`. + +A URI may be restricted to IPv6 using the scheme `tcp6://`, and may +be restricted to IPv4 using the scheme `tcp4://`. + +> [!NOTE] +> Specifying `tcp6://` may not prevent IPv4 hosts from being used with +> IPv4-in-IPv6 addresses, particularly when using a wildcard hostname with +> listeners. +> The details of this varies across operating systems. + +> [!NOTE] +> Both `tcp6://` and `tcp4://` are specific to _NNG_, and might not +> be understood by other implementations. + +> [!TIP] +> We recommend using either numeric IP addresses, or names that are +> specific to either IPv4 or IPv6 to prevent confusion and surprises. + +When specifying IPv6 addresses, the address must be enclosed in +square brackets (`[]`) to avoid confusion with the final colon +separating the port. + +For example, the same port 80 on the IPv6 loopback address (`::1`) would +be specified as `tcp://[::1]:80`. + +The special value of 0 ({{i:`INADDR_ANY`}}) +can be used for a listener to indicate that it should listen on all +interfaces on the host. +A short-hand for this form is to either omit the address, or specify +the asterisk (`*`) character. +For example, the following three URIs are all equivalent, +and could be used to listen to port 9999 on the host: + +1. `tcp://0.0.0.0:9999` +2. `tcp://*:9999` +3. `tcp://:9999` + +The entire URI must be less than `NNG_MAXADDRLEN` bytes long. + +## Socket Address + +When using an [`nng_sockaddr`][sockaddr] structure, +the actual structure is either of type +[`nng_sockaddr_in`][sockaddr_in] (for IPv4) or +[`nng_sockaddr_in6`][sockaddr_in6] (for IPv6). + +## Transport Options + +The following transport options are supported by this transport, +where supported by the underlying platform. + +- [`NNG_OPT_LOCADDR`][NNG_OPT_LOCADDR] +- [`NNG_OPT_REMADDR`][NNG_OPT_REMADDR] +- [`NNG_OPT_TCP_KEEPALIVE`][NNG_OPT_TCP_KEEPALIVE] +- [`NNG_OPT_TCP_NODELAY`][NNG_OPT_TCP_NODELAY] +- [`NNG_OPT_URL`][NNG_OPT_URL] + +{{#include ../refs.md}} diff --git a/docs/reference/src/transports/index.md b/docs/reference/src/transports/index.md deleted file mode 100644 index c7d74d80..00000000 --- a/docs/reference/src/transports/index.md +++ /dev/null @@ -1,5 +0,0 @@ -# Transports - -This chapter provides information about the various transports that _NNG_ supports. -Transports may be thought of as different underlying communications -technologies, such as TCP, Websockets, and so forth. diff --git a/docs/reference/src/transports/inproc.md b/docs/reference/src/transports/inproc.md deleted file mode 100644 index 4f3e88b6..00000000 --- a/docs/reference/src/transports/inproc.md +++ /dev/null @@ -1,50 +0,0 @@ -# INPROC Transport - -{{hi:transport, _inproc_}} -{{hi:intra-process}} -The {{i:_inproc_ transport}} provides communication support between -sockets within the same process. -This may be used as an alternative -to slower transports when data must be moved within the same process. - -This transport tries hard to avoid copying data, and thus is very -light-weight. - -## URI Format - -{{hi:URI, `inproc://`}} -This transport uses URIs using the scheme `inproc://`, followed by -an arbitrary string of text, terminated by a `NUL` byte. - -Multiple URIs can be used within the -same application, and they will not interfere with one another. - -Two applications may also use the same URI without interfering with each -other, and they will be unable to communicate with each other using -that URI. - -## Socket Address - -When using an [`nng_sockaddr`](../api/nng_sockaddr.md) structure, -the actual structure is of type -[`nng_sockaddr_inproc`](../api/nng_sockaddr_inproc.md). - -## Transport Options - -The _inproc_ transport has no special options. - -> [!NOTE] -> While _inproc_ accepts the option [`NNG_OPT_RECVMAXSZ`] for -> compatibility, the value of the option is ignored with no enforcement. -> As _inproc_ peers are in the same address space, they are implicitly -> trusted, so the protection afforded by `NNG_OPT_RECVMAXSZ` is unnecessary. - -## Mixing Implementations - -When mixing the _NNG_ library with other implementations of these -protocols in the same process (such as the _mangos_ -or _libnanomsg_ implementations), it will not be possible to utilize -the _inproc_ transport to communicate across this boundary. - -This limitation also extends to using different instances of the _NNG_ -library within the same process. diff --git a/docs/reference/src/transports/tcp.md b/docs/reference/src/transports/tcp.md deleted file mode 100644 index a710ea23..00000000 --- a/docs/reference/src/transports/tcp.md +++ /dev/null @@ -1,70 +0,0 @@ -# TCP transport - -The {{i:*tcp* transport}}{{hi:*tcp*}} provides communication support between -sockets across a {{i:TCP/IP}} network. - -Both IPv4 and IPv6 are supported when the underlying platform also supports it. - -## URI Format - -This transport uses URIs using the scheme {{i:`tcp://`}}, followed by -an IP address or hostname, followed by a colon and finally a -TCP {{i:port number}}. -For example, to contact port 80 on the localhost either of the following URIs -could be used: `tcp://127.0.0.1:80` or `tcp://localhost:80`. - -A URI may be restricted to IPv6 using the scheme `tcp6://`, and may -be restricted to IPv4 using the scheme `tcp4://`. - -> [!NOTE] -> Specifying `tcp6://` may not prevent IPv4 hosts from being used with -> IPv4-in-IPv6 addresses, particularly when using a wildcard hostname with -> listeners. -> The details of this varies across operating systems. - -> [!NOTE] -> Both `tcp6://` and `tcp4://` are specific to _NNG_, and might not -> be understood by other implementations. - -> [!TIP] -> We recommend using either numeric IP addresses, or names that are -> specific to either IPv4 or IPv6 to prevent confusion and surprises. - -When specifying IPv6 addresses, the address must be enclosed in -square brackets (`[]`) to avoid confusion with the final colon -separating the port. - -For example, the same port 80 on the IPv6 loopback address (`::1`) would -be specified as `tcp://[::1]:80`. - -The special value of 0 ({{i:`INADDR_ANY`}}) -can be used for a listener to indicate that it should listen on all -interfaces on the host. -A short-hand for this form is to either omit the address, or specify -the asterisk (`*`) character. -For example, the following three URIs are all equivalent, -and could be used to listen to port 9999 on the host: - -1. `tcp://0.0.0.0:9999` -2. `tcp://*:9999` -3. `tcp://:9999` - -The entire URI must be less than `NNG_MAXADDRLEN` bytes long. - -## Socket Address - -When using an [`nng_sockaddr`](../api/nng_sockaddr.md) structure, -the actual structure is either of type -[`nng_sockaddr_in`](../api/nng_sockaddr_in.md) (for IPv4) or -[`nng_sockaddr_in6`](../api/nng_sockaddr_in6.md) (for IPv6). - -## Transport Options - -The following transport options are supported by this transport, -where supported by the underlying platform. - -- [`NNG_OPT_LOCADDR`](../api/nng_options.md#NNG_OPT_LOCADDR) -- [`NNG_OPT_REMADDR`](../api/nng_options.md#NNG_OPT_REMADDR) -- [`NNG_OPT_TCP_KEEPALIVE`](../api/nng_tcp_options.md#NNG_OPT_TCP_KEEPALIVE) -- [`NNG_OPT_TCP_NODELAY`](../api/nng_tcp_options.md#NNG_OPT_TCP_NODELAY) -- [`NNG_OPT_URL`](../api/nng_options.md#NNG_OPT_URL) -- cgit v1.2.3-70-g09d2