From 1a9bc072f8afa875c3add9d613d80efe884728dc Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Fri, 5 Apr 2024 19:46:02 -0700 Subject: Reorg nng_msg_* pages. --- docs/man/nng_msg_alloc.3.adoc | 55 --------------------------- docs/man/nng_msg_append.3.adoc | 58 ----------------------------- docs/man/nng_msg_body.3.adoc | 62 ------------------------------- docs/man/nng_msg_capacity.3.adoc | 46 ----------------------- docs/man/nng_msg_chop.3.adoc | 61 ------------------------------ docs/man/nng_msg_clear.3.adoc | 41 -------------------- docs/man/nng_msg_dup.3.adoc | 49 ------------------------ docs/man/nng_msg_free.3.adoc | 43 --------------------- docs/man/nng_msg_get_pipe.3.adoc | 60 ------------------------------ docs/man/nng_msg_header.3.adoc | 58 ----------------------------- docs/man/nng_msg_header_append.3.adoc | 58 ----------------------------- docs/man/nng_msg_header_chop.3.adoc | 58 ----------------------------- docs/man/nng_msg_header_clear.3.adoc | 42 --------------------- docs/man/nng_msg_header_insert.3.adoc | 60 ------------------------------ docs/man/nng_msg_header_len.3.adoc | 43 --------------------- docs/man/nng_msg_header_trim.3.adoc | 59 ----------------------------- docs/man/nng_msg_insert.3.adoc | 63 ------------------------------- docs/man/nng_msg_len.3.adoc | 43 --------------------- docs/man/nng_msg_realloc.3.adoc | 66 --------------------------------- docs/man/nng_msg_reserve.3.adoc | 63 ------------------------------- docs/man/nng_msg_set_pipe.3.adoc | 50 ------------------------- docs/man/nng_msg_trim.3.adoc | 60 ------------------------------ docs/ref/msg/nng_msg_alloc.adoc | 38 +++++++++++++++++++ docs/ref/msg/nng_msg_append.adoc | 41 ++++++++++++++++++++ docs/ref/msg/nng_msg_body.adoc | 34 +++++++++++++++++ docs/ref/msg/nng_msg_capacity.adoc | 27 ++++++++++++++ docs/ref/msg/nng_msg_chop.adoc | 37 ++++++++++++++++++ docs/ref/msg/nng_msg_clear.adoc | 15 ++++++++ docs/ref/msg/nng_msg_dup.adoc | 30 +++++++++++++++ docs/ref/msg/nng_msg_free.adoc | 20 ++++++++++ docs/ref/msg/nng_msg_get_pipe.adoc | 33 +++++++++++++++++ docs/ref/msg/nng_msg_header.adoc | 35 +++++++++++++++++ docs/ref/msg/nng_msg_header_append.adoc | 37 ++++++++++++++++++ docs/ref/msg/nng_msg_header_chop.adoc | 39 +++++++++++++++++++ docs/ref/msg/nng_msg_header_clear.adoc | 19 ++++++++++ docs/ref/msg/nng_msg_header_insert.adoc | 37 ++++++++++++++++++ docs/ref/msg/nng_msg_header_len.adoc | 23 ++++++++++++ docs/ref/msg/nng_msg_header_trim.adoc | 39 +++++++++++++++++++ docs/ref/msg/nng_msg_insert.adoc | 39 +++++++++++++++++++ docs/ref/msg/nng_msg_len.adoc | 25 +++++++++++++ docs/ref/msg/nng_msg_realloc.adoc | 41 ++++++++++++++++++++ docs/ref/msg/nng_msg_reserve.adoc | 38 +++++++++++++++++++ docs/ref/msg/nng_msg_set_pipe.adoc | 23 ++++++++++++ docs/ref/msg/nng_msg_trim.adoc | 37 ++++++++++++++++++ docs/ref/tweak.go | 2 +- 45 files changed, 708 insertions(+), 1199 deletions(-) delete mode 100644 docs/man/nng_msg_alloc.3.adoc delete mode 100644 docs/man/nng_msg_append.3.adoc delete mode 100644 docs/man/nng_msg_body.3.adoc delete mode 100644 docs/man/nng_msg_capacity.3.adoc delete mode 100644 docs/man/nng_msg_chop.3.adoc delete mode 100644 docs/man/nng_msg_clear.3.adoc delete mode 100644 docs/man/nng_msg_dup.3.adoc delete mode 100644 docs/man/nng_msg_free.3.adoc delete mode 100644 docs/man/nng_msg_get_pipe.3.adoc delete mode 100644 docs/man/nng_msg_header.3.adoc delete mode 100644 docs/man/nng_msg_header_append.3.adoc delete mode 100644 docs/man/nng_msg_header_chop.3.adoc delete mode 100644 docs/man/nng_msg_header_clear.3.adoc delete mode 100644 docs/man/nng_msg_header_insert.3.adoc delete mode 100644 docs/man/nng_msg_header_len.3.adoc delete mode 100644 docs/man/nng_msg_header_trim.3.adoc delete mode 100644 docs/man/nng_msg_insert.3.adoc delete mode 100644 docs/man/nng_msg_len.3.adoc delete mode 100644 docs/man/nng_msg_realloc.3.adoc delete mode 100644 docs/man/nng_msg_reserve.3.adoc delete mode 100644 docs/man/nng_msg_set_pipe.3.adoc delete mode 100644 docs/man/nng_msg_trim.3.adoc create mode 100644 docs/ref/msg/nng_msg_alloc.adoc create mode 100644 docs/ref/msg/nng_msg_append.adoc create mode 100644 docs/ref/msg/nng_msg_body.adoc create mode 100644 docs/ref/msg/nng_msg_capacity.adoc create mode 100644 docs/ref/msg/nng_msg_chop.adoc create mode 100644 docs/ref/msg/nng_msg_clear.adoc create mode 100644 docs/ref/msg/nng_msg_dup.adoc create mode 100644 docs/ref/msg/nng_msg_free.adoc create mode 100644 docs/ref/msg/nng_msg_get_pipe.adoc create mode 100644 docs/ref/msg/nng_msg_header.adoc create mode 100644 docs/ref/msg/nng_msg_header_append.adoc create mode 100644 docs/ref/msg/nng_msg_header_chop.adoc create mode 100644 docs/ref/msg/nng_msg_header_clear.adoc create mode 100644 docs/ref/msg/nng_msg_header_insert.adoc create mode 100644 docs/ref/msg/nng_msg_header_len.adoc create mode 100644 docs/ref/msg/nng_msg_header_trim.adoc create mode 100644 docs/ref/msg/nng_msg_insert.adoc create mode 100644 docs/ref/msg/nng_msg_len.adoc create mode 100644 docs/ref/msg/nng_msg_realloc.adoc create mode 100644 docs/ref/msg/nng_msg_reserve.adoc create mode 100644 docs/ref/msg/nng_msg_set_pipe.adoc create mode 100644 docs/ref/msg/nng_msg_trim.adoc (limited to 'docs') diff --git a/docs/man/nng_msg_alloc.3.adoc b/docs/man/nng_msg_alloc.3.adoc deleted file mode 100644 index 2754b67e..00000000 --- a/docs/man/nng_msg_alloc.3.adoc +++ /dev/null @@ -1,55 +0,0 @@ -= nng_msg_alloc(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_msg_alloc - allocate a message - -== SYNOPSIS - -[source, 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 - -[horizontal] -`NNG_ENOMEM`:: Insufficient free memory exists to allocate a message. - -== SEE ALSO - -[.text-left] -xref:nng_msg_free.3.adoc[nng_msg_free(3)], -xref:nng_msg_body.3.adoc[nng_msg_body(3)], -xref:nng_msg_dup.3.adoc[nng_msg_dup(3)], -xref:nng_msg_header.3.adoc[nng_msg_header(3)], -xref:nng_msg_header_len.3.adoc[nng_msg_header_len(3)], -xref:nng_msg_len.3.adoc[nng_msg_len(3)], -xref:nng_msg_capacity.3.adoc[nng_msg_capacity(3)], -xref:nng_msg_reserve.3.adoc[nng_msg_reserve(3)], -xref:nng_msg_realloc.3.adoc[nng_msg_realloc(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_msg.5.adoc[nng_msg(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_msg_append.3.adoc b/docs/man/nng_msg_append.3.adoc deleted file mode 100644 index 9ed3741d..00000000 --- a/docs/man/nng_msg_append.3.adoc +++ /dev/null @@ -1,58 +0,0 @@ -= nng_msg_append(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_msg_append - append to message body - -== SYNOPSIS - -[source, 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 - -[horizontal] -`NNG_ENOMEM`:: Insufficient free memory exists. - -== SEE ALSO - -[.text-left] -xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], -xref:nng_msg_body.3.adoc[nng_msg_body(3)], -xref:nng_msg_chop.3.adoc[nng_msg_chop(3)], -xref:nng_msg_free.3.adoc[nng_msg_free(3)], -xref:nng_msg_insert.3.adoc[nng_msg_insert(3)], -xref:nng_msg_len.3.adoc[nng_msg_len(3)], -xref:nng_msg_realloc.3.adoc[nng_msg_realloc(3)], -xref:nng_msg_trim.3.adoc[nng_msg_trim(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_msg.5.adoc[nng_msg(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_msg_body.3.adoc b/docs/man/nng_msg_body.3.adoc deleted file mode 100644 index ad0fa7b3..00000000 --- a/docs/man/nng_msg_body.3.adoc +++ /dev/null @@ -1,62 +0,0 @@ -= nng_msg_body(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_msg_body - return message body - -== SYNOPSIS - -[source, 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 -xref:nng_msg_free.3.adoc[`nng_msg_free()`], -xref:nng_msg_realloc.3.adoc[`nng_msg_realloc()`], -any of the xref:nng_msg_trim.3.adoc[`nng_msg_trim()`], -xref:nng_msg_chop.3.adoc[`nng_msg_chop()`], -xref:nng_msg_append.3.adoc[`nng_msg_append()`], -or xref:nng_msg_insert.3.adoc[`nng_msg_insert()`] variants. - -== RETURN VALUES - -Pointer to start of message body. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], -xref:nng_msg_append.3.adoc[nng_msg_append(3)], -xref:nng_msg_chop.3.adoc[nng_msg_chop(3)], -xref:nng_msg_free.3.adoc[nng_msg_free(3)], -xref:nng_msg_insert.3.adoc[nng_msg_insert(3)], -xref:nng_msg_len.3.adoc[nng_msg_len(3)], -xref:nng_msg_capacity.3.adoc[nng_msg_capacity(3)], -xref:nng_msg_reserve.3.adoc[nng_msg_reserve(3)], -xref:nng_msg_realloc.3.adoc[nng_msg_realloc(3)], -xref:nng_msg_trim.3.adoc[nng_msg_trim(3)], -xref:nng_msg.5.adoc[nng_msg(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_msg_capacity.3.adoc b/docs/man/nng_msg_capacity.3.adoc deleted file mode 100644 index ffc7f5d3..00000000 --- a/docs/man/nng_msg_capacity.3.adoc +++ /dev/null @@ -1,46 +0,0 @@ -= nng_msg_capacity(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_msg_capacity - return message body length - -== SYNOPSIS - -[source, 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. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_msg_reserve.3.adoc[nng_msg_reserve(3)], -xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], -xref:nng_msg_body.3.adoc[nng_msg_body(3)], -xref:nng_msg.5.adoc[nng_msg(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_msg_chop.3.adoc b/docs/man/nng_msg_chop.3.adoc deleted file mode 100644 index b945f0bb..00000000 --- a/docs/man/nng_msg_chop.3.adoc +++ /dev/null @@ -1,61 +0,0 @@ -= nng_msg_chop(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_msg_chop - remove data from end of message body - -== SYNOPSIS - -[source, 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 - -[horizontal] -`NNG_EINVAL`:: The message body is too short to remove the requested data. - -== SEE ALSO - -[.text-left] -xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], -xref:nng_msg_append.3.adoc[nng_msg_append(3)], -xref:nng_msg_body.3.adoc[nng_msg_body(3)], -xref:nng_msg_free.3.adoc[nng_msg_free(3)], -xref:nng_msg_insert.3.adoc[nng_msg_insert(3)], -xref:nng_msg_len.3.adoc[nng_msg_len(3)], -xref:nng_msg_capacity.3.adoc[nng_msg_capacity(3)], -xref:nng_msg_reserve.3.adoc[nng_msg_reserve(3)], -xref:nng_msg_realloc.3.adoc[nng_msg_realloc(3)], -xref:nng_msg_trim.3.adoc[nng_msg_trim(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_msg.5.adoc[nng_msg(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_msg_clear.3.adoc b/docs/man/nng_msg_clear.3.adoc deleted file mode 100644 index e5b3bf47..00000000 --- a/docs/man/nng_msg_clear.3.adoc +++ /dev/null @@ -1,41 +0,0 @@ -= nng_msg_clear(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_msg_clear - clear message body content - -== SYNOPSIS - -[source, c] ----- -#include - -void nng_msg_clear(nng_msg *msg); ----- - -== DESCRIPTION - -The `nng_msg_clear()` function resets the body length of _msg_ to zero. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_msg.5.adoc[nng_msg(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_msg_dup.3.adoc b/docs/man/nng_msg_dup.3.adoc deleted file mode 100644 index b985d5bb..00000000 --- a/docs/man/nng_msg_dup.3.adoc +++ /dev/null @@ -1,49 +0,0 @@ -= nng_msg_dup(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_msg_dup - duplicate a message - -== SYNOPSIS - -[source, 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 - -[horizontal] -`NNG_ENOMEM`:: Insufficient free memory exists to duplicate a message. - -== SEE ALSO - -[.text-left] -xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], -xref:nng_msg_free.3.adoc[nng_msg_free(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_msg.5.adoc[nng_msg(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_msg_free.3.adoc b/docs/man/nng_msg_free.3.adoc deleted file mode 100644 index 1ee045c0..00000000 --- a/docs/man/nng_msg_free.3.adoc +++ /dev/null @@ -1,43 +0,0 @@ -= nng_msg_free(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_msg_free - free a message - -== SYNOPSIS - -[source, c] ----- -#include - -void nng_msg_free(nng_msg *msg); ----- - -== DESCRIPTION - -The `nng_msg_free()` function deallocates the message _msg_ entirely. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], -xref:nng_msg_realloc.3.adoc[nng_msg_realloc(3)], -xref:nng_msg.5.adoc[nng_msg(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_msg_get_pipe.3.adoc b/docs/man/nng_msg_get_pipe.3.adoc deleted file mode 100644 index 154f4c43..00000000 --- a/docs/man/nng_msg_get_pipe.3.adoc +++ /dev/null @@ -1,60 +0,0 @@ -= nng_msg_get_pipe(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_msg_get_pipe - get pipe for message - -== SYNOPSIS - -[source, c] ----- -#include - -nng_pipe nng_msg_get_pipe(nng_msg *msg); ----- - -== DESCRIPTION - -The `nng_msg_get_pipe()` returns the xref:nng_pipe.5.adoc[`nng_pipe`] object -associated with message _msg_. -On receive, this is the pipe from which a message was received. -On transmit, this would be the pipe that the message should be delivered -to, if a specific peer is required. - -NOTE: Not all protocols support overriding the destination pipe. - -The most usual use case for this is to obtain information about the peer -from which the message was received. -This can be used to provide different behaviors for different peers, such as -a higher level of authentication for peers located on an untrusted network. -The xref:nng_pipe_getopt.3.adoc[`nng_pipe_getopt()`] function -is useful in this situation. - - -== RETURN VALUES - -This function returns the pipe associated with this message, which will -be a positive value. -If the pipe is non-positive, then that indicates that -no specific pipe is associated with the message. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], -xref:nng_msg_set_pipe.3.adoc[nng_msg_set_pipe(3)], -xref:nng_pipe_getopt.3.adoc[nng_pipe_getopt(3)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_msg_header.3.adoc b/docs/man/nng_msg_header.3.adoc deleted file mode 100644 index eac45ffd..00000000 --- a/docs/man/nng_msg_header.3.adoc +++ /dev/null @@ -1,58 +0,0 @@ -= nng_msg_header(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_msg_header - return message header - -== SYNOPSIS - -[source, c] ----- -#include - -void *nng_msg_header(nng_msg *msg); ----- - -== DESCRIPTION - -The `nng_msg_header()` function returns a pointer to the start of the header -content of the message _msg_. - -NOTE: The message header contains protocol-specific header content. Most -applications should not need to access this content, but it is available -for raw mode sockets (set with the -xref:nng_options.5.adoc#NNG_OPT_RAW[`NNG_OPT_RAW`] option.) - -NOTE: The value returned by this is invalidated by a call to any of the -functions that modify the message or the header content. - -== RETURN VALUES - -Pointer to start of message header. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], -xref:nng_msg_body.3.adoc[nng_msg_body(3)], -xref:nng_msg_free.3.adoc[nng_msg_free(3)], -xref:nng_msg_header_append.3.adoc[nng_msg_header_append(3)], -xref:nng_msg_header_chop.3.adoc[nng_msg_header_chop(3)], -xref:nng_msg_header_insert.3.adoc[nng_msg_header_insert(3)] -xref:nng_msg_header_len.3.adoc[nng_msg_header_len(3)], -xref:nng_msg_header_trim.3.adoc[nng_msg_header_trim(3)], -xref:nng_msg.5.adoc[nng_msg(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_msg_header_append.3.adoc b/docs/man/nng_msg_header_append.3.adoc deleted file mode 100644 index 16badf0b..00000000 --- a/docs/man/nng_msg_header_append.3.adoc +++ /dev/null @@ -1,58 +0,0 @@ -= nng_msg_header_append(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_msg_header_append - append to message header - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_msg_header_append(nng_msg *msg, const void *val, size_t size); -int nng_msg_header_append_u16(nng_msg *msg, uint16_t val16); -int nng_msg_header_append_u32(nng_msg *msg, uint32_t val32); -int nng_msg_header_append_u64(nng_msg *msg, uint64_t val64); ----- - -== DESCRIPTION - -The `nng_msg_header_append()` family of functions appends data to -the end of the headers of message _msg_, reallocating it if necessary. -The first function appends _size_ bytes, copying them from _val_. - -The remaining functions append the value (such as _val32_) in -network-byte order (big-endian). - - -== RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient free memory exists. - -== SEE ALSO - -[.text-left] -xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], -xref:nng_msg_header.3.adoc[nng_msg_header(3)], -xref:nng_msg_header_chop.3.adoc[nng_msg_header_chop(3)], -xref:nng_msg_header_insert.3.adoc[nng_msg_header_insert(3)], -xref:nng_msg_header_len.3.adoc[nng_msg_header_len(3)], -xref:nng_msg_header_trim.3.adoc[nng_msg_header_trim(3)], -xref:nng_msg_free.3.adoc[nng_msg_free(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_msg_header_chop.3.adoc b/docs/man/nng_msg_header_chop.3.adoc deleted file mode 100644 index 454e9e51..00000000 --- a/docs/man/nng_msg_header_chop.3.adoc +++ /dev/null @@ -1,58 +0,0 @@ -= nng_msg_header_chop(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_msg_header_chop - remove data from end of message header - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_msg_header_chop(nng_msg *msg, size_t size); -int nng_msg_header_chop_u16(nng_msg *msg, uint16_t *val16); -int nng_msg_header_chop_u32(nng_msg *msg, uint32_t *val32); -int nng_msg_header_chop_u64(nng_msg *msg, uint64_t *val64); ----- - -== DESCRIPTION - -The `nng_msg_header_chop()` family of functions removes -data from the end of the header of message _msg_. -The first function removes _size_ bytes. -The remaining functions remove 2, 4, or 8 bytes, and stores them in the value -(such as _val32_), -after converting them from network-byte order (big-endian) to native -byte order. - -== RETURN VALUES - -These function return 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_EINVAL`:: The message header is too short to remove the requested data. - -== SEE ALSO - -[.text-left] -xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], -xref:nng_msg_header.3.adoc[nng_msg_header(3)], -xref:nng_msg_header_append.3.adoc[nng_msg_header_append(3)], -xref:nng_msg_header_insert.3.adoc[nng_msg_header_insert(3)], -xref:nng_msg_header_len.3.adoc[nng_msg_header_len(3)], -xref:nng_msg_header_trim.3.adoc[nng_msg_header_trim(3)], -xref:nng_msg_free.3.adoc[nng_msg_free(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_msg_header_clear.3.adoc b/docs/man/nng_msg_header_clear.3.adoc deleted file mode 100644 index d00286ed..00000000 --- a/docs/man/nng_msg_header_clear.3.adoc +++ /dev/null @@ -1,42 +0,0 @@ -= nng_msg_header_clear(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_msg_header_clear - clear message header - -== SYNOPSIS - -[source, c] ----- -#include - -void nng_msg_header_clear(nng_msg *msg); ----- - -== DESCRIPTION - -The `nng_msg_clear()` function resets the header length of _msg_ to zero. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], -xref:nng_msg_free.3.adoc[nng_msg_free(3)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_msg_header_insert.3.adoc b/docs/man/nng_msg_header_insert.3.adoc deleted file mode 100644 index a2bf0d63..00000000 --- a/docs/man/nng_msg_header_insert.3.adoc +++ /dev/null @@ -1,60 +0,0 @@ -= nng_msg_header_insert(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_msg_header_insert - prepend to message header - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_msg_header_insert(nng_msg *msg, const void *val, size_t size); -int nng_msg_header_insert_u16(nng_msg *msg, uint16_t val16); -int nng_msg_header_insert_u32(nng_msg *msg, uint32_t val32); -int nng_msg_header_insert_u64(nng_msg *msg, uint64_t val64); ----- - -== DESCRIPTION - -The `nng_msg_header_insert()` family of functions -prepends data to the front of the headers of message _msg_, reallocating -if necessary. -The first function prepends _size_ bytes, copying them from _val_. -The remaining functions prepend the specified value (such as _val32_) in -network-byte order (big-endian). - -== RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient free memory exists. - -== SEE ALSO - -[.text-left] -xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], -xref:nng_msg_header.3.adoc[nng_msg_header(3)], -xref:nng_msg_header_append.3.adoc[nng_msg_header_append(3)], -xref:nng_msg_header_chop.3.adoc[nng_msg_header_chop(3)], -xref:nng_msg_header_len.3.adoc[nng_msg_header_len(3)], -xref:nng_msg_header_trim.3.adoc[nng_msg_header_trim(3)], -xref:nng_msg_free.3.adoc[nng_msg_free(3)], -xref:nng_msg_capacity.3.adoc[nng_msg_capacity(3)], -xref:nng_msg_reserve.3.adoc[nng_msg_reserve(3)], -xref:nng_msg_realloc.3.adoc[nng_msg_realloc(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_msg_header_len.3.adoc b/docs/man/nng_msg_header_len.3.adoc deleted file mode 100644 index 0a7b3613..00000000 --- a/docs/man/nng_msg_header_len.3.adoc +++ /dev/null @@ -1,43 +0,0 @@ -= nng_msg_header_len(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_msg_header_len - return message header length - -== SYNOPSIS - -[source, c] ----- -#include - -size_t nng_msg_header_len(nng_msg *msg); ----- - -== DESCRIPTION - -The `nng_msg_header_len()` returns the length of message header of _msg_. - -== RETURN VALUES - -Length of message header. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], -xref:nng_msg_header.3.adoc[nng_msg_header(3)], -xref:nng_msg.5.adoc[nng_msg(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_msg_header_trim.3.adoc b/docs/man/nng_msg_header_trim.3.adoc deleted file mode 100644 index 6df504ff..00000000 --- a/docs/man/nng_msg_header_trim.3.adoc +++ /dev/null @@ -1,59 +0,0 @@ -= nng_msg_header_trim(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_msg_header_trim - remove data from start of message header - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_msg_header_trim(nng_msg *msg, size_t size); -int nng_msg_header_trim_u16(nng_msg *msg, uint16_t *val16); -int nng_msg_header_trim_u32(nng_msg *msg, uint32_t *val32); -int nng_msg_header_trim_u64(nng_msg *msg, uint64_t *val64); ----- - -== DESCRIPTION - -The `nng_msg_header_trim()` family of functions remove -data from the start of the header of message _msg_. -The first function removes _size_ bytes. -The remaining functions removes 2, 4, or 8 bytes, and stores them in the -value (such as _val32_), -after converting them from network-byte order (big-endian) to native -byte order. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_EINVAL`:: The message header is too short to remove the requested data. - -== SEE ALSO - -[.text-left] -xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], -xref:nng_msg_header.3.adoc[nng_msg_header(3)], -xref:nng_msg_header_append.3.adoc[nng_msg_header_append(3)], -xref:nng_msg_header_chop.3.adoc[nng_msg_header_chop(3)], -xref:nng_msg_header_insert.3.adoc[nng_msg_header_insert(3)], -xref:nng_msg_header_len.3.adoc[nng_msg_header_len(3)], -xref:nng_msg_free.3.adoc[nng_msg_free(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_msg.5.adoc[nng_msg(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_msg_insert.3.adoc b/docs/man/nng_msg_insert.3.adoc deleted file mode 100644 index 25f98fce..00000000 --- a/docs/man/nng_msg_insert.3.adoc +++ /dev/null @@ -1,63 +0,0 @@ -= nng_msg_insert(3) -// -// Copyright 2020 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_msg_insert - prepend to message body - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_msg_insert(nng_msg *msg, const void *val, size_t size); -int nng_msg_insert_u16(nng_msg *msg, uint16_t val16); -int nng_msg_insert_u32(nng_msg *msg, uint32_t val32); -int nng_msg_insert_u64(nng_msg *msg, uint64_t val64); ----- - -== DESCRIPTION - -The `nng_msg_insert()` family of functions prepends data to -the front of the body of message _msg_, reallocating it if necessary. -The first function prepends _size_ bytes, copying them from _val_. -The remaining functions prepend the specified value (such as _val32_) -in network-byte order (big-endian). - -TIP: These functions make use of space pre-allocated in front of the -message body if available, so they can often avoid performing any reallocation. -Applications should use these instead of reallocating and copying message -content themselves, in order to benefit from this capability. - -== RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient free memory exists. - -== SEE ALSO - -[.text-left] -xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], -xref:nng_msg_append.3.adoc[nng_msg_append(3)], -xref:nng_msg_body.3.adoc[nng_msg_body(3)], -xref:nng_msg_chop.3.adoc[nng_msg_chop(3)], -xref:nng_msg_free.3.adoc[nng_msg_free(3)], -xref:nng_msg_len.3.adoc[nng_msg_len(3)], -xref:nng_msg_realloc.3.adoc[nng_msg_realloc(3)], -xref:nng_msg_trim.3.adoc[nng_msg_trim(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_msg.5.adoc[nng_msg(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_msg_len.3.adoc b/docs/man/nng_msg_len.3.adoc deleted file mode 100644 index 2a3dfe67..00000000 --- a/docs/man/nng_msg_len.3.adoc +++ /dev/null @@ -1,43 +0,0 @@ -= nng_msg_len(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_msg_len - return message body length - -== SYNOPSIS - -[source, c] ----- -#include - -size_t nng_msg_len(nng_msg *msg); ----- - -== DESCRIPTION - -The `nng_msg_len()` returns the length of the body of message _msg_. - -== RETURN VALUES - -Length of message body. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], -xref:nng_msg_body.3.adoc[nng_msg_body(3)], -xref:nng_msg.5.adoc[nng_msg(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_msg_realloc.3.adoc b/docs/man/nng_msg_realloc.3.adoc deleted file mode 100644 index bf407289..00000000 --- a/docs/man/nng_msg_realloc.3.adoc +++ /dev/null @@ -1,66 +0,0 @@ -= nng_msg_realloc(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_msg_realloc - reallocate a message - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_msg_realloc(nng_msg *msg, size_t size); ----- - -== DESCRIPTION - -The `nng_msg_realloc()` function re-allocates a message so that it has -a body of length _size_. -This message attempts to avoid extra allocations, -and will reuse the existing memory when possible. - -TIP: `nng_msg_realloc` is suitable for creating space for direct writing of data. -When appending many small pieces of data to a message using xref:nng_msg_append.3.adoc[`nng_msg_append()`], -allocations may be reduced by first using xref:nng_msg_reserve.3.adoc[`nng_msg_reserve()`] -to create sufficient space. -In any case, reallocating or appending to a message is guaranteed to succeed if the resulting -body length is less than xref:nng_msg_capacity.3.adoc[`nng_msg_capacity()`]. - -NOTE: Pointers to message body and header content obtained prior to this -function must not be in use, as the underlying memory used for the message -may have changed, particularly if the message size is increasing. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient free memory exists to reallocate a message. - -== SEE ALSO - -[.text-left] -xref:nng_msg_reserve.3.adoc[nng_msg_reserve(3)], -xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], -xref:nng_msg_append.3.adoc[nng_msg_append(3)], -xref:nng_msg_body.3.adoc[nng_msg_body(3)], -xref:nng_msg_chop.3.adoc[nng_msg_chop(3)], -xref:nng_msg_free.3.adoc[nng_msg_free(3)], -xref:nng_msg_insert.3.adoc[nng_msg_insert(3)], -xref:nng_msg_len.3.adoc[nng_msg_len(3)], -xref:nng_msg_trim.3.adoc[nng_msg_trim(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_msg.5.adoc[nng_msg(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_msg_reserve.3.adoc b/docs/man/nng_msg_reserve.3.adoc deleted file mode 100644 index 254c1e94..00000000 --- a/docs/man/nng_msg_reserve.3.adoc +++ /dev/null @@ -1,63 +0,0 @@ -= nng_msg_reserve(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_msg_reserve - reserve storage for a message - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_msg_reserve(nng_msg *msg, size_t capacity); ----- - -== DESCRIPTION - -The `nng_msg_reserve()` function ensures a message has allocated enough storage -to accommodate a body of the given length. -This message attempts to avoid extra allocations, -and will reuse the existing memory when possible. - -TIP: Using this message before xref:nng_msg_append.3.adoc[`nng_msg_append()`] -will prevent additional memory allocations until the message's length exceeds -the alotted capacity. - -NOTE: Pointers to message body and header content obtained prior to this -function must not be in use, as the underlying memory used for the message -may have changed, particularly if the message capacity is increasing. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient free memory exists to reallocate a message. - -== SEE ALSO - -[.text-left] -xref:nng_msg_capacity.3.adoc[nng_msg_capacity(3)], -xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], -xref:nng_msg_append.3.adoc[nng_msg_append(3)], -xref:nng_msg_body.3.adoc[nng_msg_body(3)], -xref:nng_msg_chop.3.adoc[nng_msg_chop(3)], -xref:nng_msg_free.3.adoc[nng_msg_free(3)], -xref:nng_msg_insert.3.adoc[nng_msg_insert(3)], -xref:nng_msg_len.3.adoc[nng_msg_len(3)], -xref:nng_msg_trim.3.adoc[nng_msg_trim(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_msg.5.adoc[nng_msg(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_msg_set_pipe.3.adoc b/docs/man/nng_msg_set_pipe.3.adoc deleted file mode 100644 index c95cc83f..00000000 --- a/docs/man/nng_msg_set_pipe.3.adoc +++ /dev/null @@ -1,50 +0,0 @@ -= nng_msg_set_pipe(3) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_msg_set_pipe - set pipe for message - -== SYNOPSIS - -[source, c] ----- -#include - -void nng_msg_set_pipe(nng_msg *msg, nng_pipe p); ----- - -== DESCRIPTION - -The `nng_msg_set_pipe()` sets the pipe associated with message _m_ to _p_. -This is most often useful when used with protocols that support directing -a message to a specific peer. -For example the xref:nng_pair.7.adoc[_pair_] version 1 protocol can do -this when `NNG_OPT_PAIR1_POLY` mode is set. - -NOTE: Not all protocols support overriding the destination pipe. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], -xref:nng_msg_get_pipe.3.adoc[nng_msg_get_pipe(3)], -xref:nng_pipe_getopt.3.adoc[nng_pipe_getopt(3)], -xref:nng_msg.5.adoc[nng_msg(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_msg_trim.3.adoc b/docs/man/nng_msg_trim.3.adoc deleted file mode 100644 index aa482958..00000000 --- a/docs/man/nng_msg_trim.3.adoc +++ /dev/null @@ -1,60 +0,0 @@ -= nng_msg_trim(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_msg_trim - remove data from start of message body - -== SYNOPSIS - -[source, 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 - -[horizontal] -`NNG_EINVAL`:: The message body is too short to remove the requested data. - -== SEE ALSO - -[.text-left] -xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], -xref:nng_msg_append.3.adoc[nng_msg_append(3)], -xref:nng_msg_body.3.adoc[nng_msg_body(3)], -xref:nng_msg_chop.3.adoc[nng_msg_chop(3)], -xref:nng_msg_free.3.adoc[nng_msg_free(3)], -xref:nng_msg_insert.3.adoc[nng_msg_insert(3)], -xref:nng_msg_len.3.adoc[nng_msg_len(3)], -xref:nng_msg_realloc.3.adoc[nng_msg_realloc(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_msg.5.adoc[nng_msg(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/ref/msg/nng_msg_alloc.adoc b/docs/ref/msg/nng_msg_alloc.adoc new file mode 100644 index 00000000..ae0e9184 --- /dev/null +++ b/docs/ref/msg/nng_msg_alloc.adoc @@ -0,0 +1,38 @@ +## 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 + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists to allocate a message. + +### See Also + +xref:nng_msg_free.adoc[nng_msg_free], +xref:nng_msg_body.adoc[nng_msg_body], +xref:nng_msg_dup.adoc[nng_msg_dup], +xref:nng_msg_header.adoc[nng_msg_header], +xref:nng_msg_header_len.adoc[nng_msg_header_len], +xref:nng_msg_len.adoc[nng_msg_len], +xref:nng_msg_capacity.adoc[nng_msg_capacity], +xref:nng_msg_reserve.adoc[nng_msg_reserve], +xref:nng_msg_realloc.adoc[nng_msg_realloc], diff --git a/docs/ref/msg/nng_msg_append.adoc b/docs/ref/msg/nng_msg_append.adoc new file mode 100644 index 00000000..2c425267 --- /dev/null +++ b/docs/ref/msg/nng_msg_append.adoc @@ -0,0 +1,41 @@ +## 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 + +These functions append data to the end of the body of message _msg_, reallocating it if necessary. + +The `nng_msg_append` 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 + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists. + +### See Also + +xref:nng_msg_alloc.adoc[nng_msg_alloc], +xref:nng_msg_body.adoc[nng_msg_body], +xref:nng_msg_chop.adoc[nng_msg_chop], +xref:nng_msg_free.adoc[nng_msg_free], +xref:nng_msg_insert.adoc[nng_msg_insert], +xref:nng_msg_len.adoc[nng_msg_len], +xref:nng_msg_realloc.adoc[nng_msg_realloc], +xref:nng_msg_trim.adoc[nng_msg_trim], diff --git a/docs/ref/msg/nng_msg_body.adoc b/docs/ref/msg/nng_msg_body.adoc new file mode 100644 index 00000000..77c850c8 --- /dev/null +++ b/docs/ref/msg/nng_msg_body.adoc @@ -0,0 +1,34 @@ +## 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_. + +The returned message body is invalidated by a call to any of the functions that modify the message itself. +Such functions are xref:nng_msg_free.adoc[`nng_msg_free`], xref:nng_msg_realloc.adoc[`nng_msg_realloc`], any of the xref:nng_msg_trim.adoc[`nng_msg_trim`], xref:nng_msg_append.adoc[`nng_msg_append`], or xref:nng_msg_insert.adoc[`nng_msg_insert`] variants. + +### Return Values + +Pointer to start of message body. + +### See Also + +xref:nng_msg_append.adoc[nng_msg_append], +xref:nng_msg_free.adoc[nng_msg_free], +xref:nng_msg_insert.adoc[nng_msg_insert], +xref:nng_msg_len.adoc[nng_msg_len], +xref:nng_msg_capacity.adoc[nng_msg_capacity], +xref:nng_msg_reserve.adoc[nng_msg_reserve], +xref:nng_msg_realloc.adoc[nng_msg_realloc], +xref:nng_msg_trim.adoc[nng_msg_trim] diff --git a/docs/ref/msg/nng_msg_capacity.adoc b/docs/ref/msg/nng_msg_capacity.adoc new file mode 100644 index 00000000..3ee76e2c --- /dev/null +++ b/docs/ref/msg/nng_msg_capacity.adoc @@ -0,0 +1,27 @@ +## 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 + +xref:nng_msg_reserve.adoc[nng_msg_reserve], +xref:nng_msg_alloc.adoc[nng_msg_alloc], +xref:nng_msg_body.adoc[nng_msg_body] diff --git a/docs/ref/msg/nng_msg_chop.adoc b/docs/ref/msg/nng_msg_chop.adoc new file mode 100644 index 00000000..6a67fb0e --- /dev/null +++ b/docs/ref/msg/nng_msg_chop.adoc @@ -0,0 +1,37 @@ +## 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 + +These functions remove data from the end of the body of message _msg_. + +The `nng_msg_chop` 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 + +[horizontal] +`NNG_EINVAL`:: The message body is too short to remove the requested data. + +### See Also + +xref:nng_msg_append.adoc[nng_msg_append], +xref:nng_msg_body.adoc[nng_msg_body], +xref:nng_msg_len.adoc[nng_msg_len], +xref:nng_msg_trim.adoc[nng_msg_trim] diff --git a/docs/ref/msg/nng_msg_clear.adoc b/docs/ref/msg/nng_msg_clear.adoc new file mode 100644 index 00000000..3800e69e --- /dev/null +++ b/docs/ref/msg/nng_msg_clear.adoc @@ -0,0 +1,15 @@ +## 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. diff --git a/docs/ref/msg/nng_msg_dup.adoc b/docs/ref/msg/nng_msg_dup.adoc new file mode 100644 index 00000000..4ad83181 --- /dev/null +++ b/docs/ref/msg/nng_msg_dup.adoc @@ -0,0 +1,30 @@ +## 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 + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists to duplicate a message. + +### See Also + +xref:nng_msg_alloc.adoc[nng_msg_alloc], +xref:nng_msg_free.adoc[nng_msg_free] diff --git a/docs/ref/msg/nng_msg_free.adoc b/docs/ref/msg/nng_msg_free.adoc new file mode 100644 index 00000000..84b18db8 --- /dev/null +++ b/docs/ref/msg/nng_msg_free.adoc @@ -0,0 +1,20 @@ +## 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 + +xref:nng_msg_alloc.adoc[nng_msg_alloc], +xref:nng_msg_realloc.adoc[nng_msg_realloc] diff --git a/docs/ref/msg/nng_msg_get_pipe.adoc b/docs/ref/msg/nng_msg_get_pipe.adoc new file mode 100644 index 00000000..fa816d2b --- /dev/null +++ b/docs/ref/msg/nng_msg_get_pipe.adoc @@ -0,0 +1,33 @@ +## 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` function returns the xref:../pipe/index.adoc[pipe] object associated with message _msg_. +On receive, this is the pipe from which a message was received. +On transmit, this would be the pipe that the message should be delivered to, if a specific peer is required. + +Not all protocols support overriding the destination pipe. + +The most usual use case for this is to obtain information about the peer from which the message was received. +This can be used to provide different behaviors for different peers such as a higher level of authentication for peers located on an untrusted network. +The xref:../pipe/nng_pipe_get.adoc[`nng_pipe_get`] function is useful in this situation. + +### Return Values + +This function returns the pipe associated with this message. +If the message is not associated with a pipe, then xref:nng_pipe_id.adoc[`nng_pipe_id`] on the return value will return a negative number. + +### See Also + +xref:nng_msg_set_pipe.adoc[nng_msg_set_pipe], +xref:../pipe/nng_pipe_get.adoc[nng_pipe_get] diff --git a/docs/ref/msg/nng_msg_header.adoc b/docs/ref/msg/nng_msg_header.adoc new file mode 100644 index 00000000..cfb3d4d8 --- /dev/null +++ b/docs/ref/msg/nng_msg_header.adoc @@ -0,0 +1,35 @@ +## 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 access this content, but it is available for xref:../socket/raw.adoc[raw mode] sockets. +Specifcially applications should not attempt to store their own private data in the message header. + +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 + +xref:nng_msg_body.adoc[nng_msg_body], +xref:nng_msg_header_append.adoc[nng_msg_header_append], +xref:nng_msg_header_chop.adoc[nng_msg_header_chop], +xref:nng_msg_header_insert.adoc[nng_msg_header_insert] +xref:nng_msg_header_len.adoc[nng_msg_header_len], +xref:nng_msg_header_trim.adoc[nng_msg_header_trim] diff --git a/docs/ref/msg/nng_msg_header_append.adoc b/docs/ref/msg/nng_msg_header_append.adoc new file mode 100644 index 00000000..4e7feef4 --- /dev/null +++ b/docs/ref/msg/nng_msg_header_append.adoc @@ -0,0 +1,37 @@ +## 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 + +These functions append data to the end of the headers of message _msg_, reallocating it if necessary. + +The `nng_msg_header_append` function appends _size_ bytes, copying them from _val_. +The remaining functions append the value (such as _val32_) in network-byte order (big-endian). + +### Return Values + +These functions return 0 on success, and non-zero otherwise. + +### Errors + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists. + +### See Also + +xref:nng_msg_header.adoc[nng_msg_header], +xref:nng_msg_header_chop.adoc[nng_msg_header_chop], +xref:nng_msg_header_insert.adoc[nng_msg_header_insert], +xref:nng_msg_header_trim.adoc[nng_msg_header_trim] \ No newline at end of file diff --git a/docs/ref/msg/nng_msg_header_chop.adoc b/docs/ref/msg/nng_msg_header_chop.adoc new file mode 100644 index 00000000..d252ae13 --- /dev/null +++ b/docs/ref/msg/nng_msg_header_chop.adoc @@ -0,0 +1,39 @@ +## 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 + +Theses functions remove data from the end of the header of message _msg_. + +The `nng_msg_header_chop` function removes _size_ bytes. +The remaining functions remove 2, 4, or 8 bytes, and stores them in the value (such as _val32_), +after converting them from network-byte order (big-endian) to native byte order. + +### Return Values + +These function return 0 on success, and non-zero otherwise. + +### Errors + +[horizontal] +`NNG_EINVAL`:: The message header is too short to remove the requested data. + +### See Also + +xref:nng_msg_header.adoc[nng_msg_header], +xref:nng_msg_header_append.adoc[nng_msg_header_append], +xref:nng_msg_header_insert.adoc[nng_msg_header_insert], +xref:nng_msg_header_len.adoc[nng_msg_header_len], +xref:nng_msg_header_trim.adoc[nng_msg_header_trim] diff --git a/docs/ref/msg/nng_msg_header_clear.adoc b/docs/ref/msg/nng_msg_header_clear.adoc new file mode 100644 index 00000000..c8eff60b --- /dev/null +++ b/docs/ref/msg/nng_msg_header_clear.adoc @@ -0,0 +1,19 @@ +## 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 + +xref:nng_msg_header.adoc[nng_msg_header] diff --git a/docs/ref/msg/nng_msg_header_insert.adoc b/docs/ref/msg/nng_msg_header_insert.adoc new file mode 100644 index 00000000..0ef19acd --- /dev/null +++ b/docs/ref/msg/nng_msg_header_insert.adoc @@ -0,0 +1,37 @@ +## 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 + +These function prependsdata to the front of the headers of message _msg_, reallocating if necessary. + +The `nng_msg_header_insert` function prepends _size_ bytes, copying them from _val_. +The remaining functions prepend the specified value (such as _val32_) in network-byte order (big-endian). + +### Return Values + +These functions return 0 on success, and non-zero otherwise. + +### Errors + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists. + +### See Also + +xref:nng_msg_header.adoc[nng_msg_header], +xref:nng_msg_header_append.adoc[nng_msg_header_append], +xref:nng_msg_header_trim.adoc[nng_msg_header_trim], +xref:nng_msg_realloc.adoc[nng_msg_realloc], diff --git a/docs/ref/msg/nng_msg_header_len.adoc b/docs/ref/msg/nng_msg_header_len.adoc new file mode 100644 index 00000000..75b46cd7 --- /dev/null +++ b/docs/ref/msg/nng_msg_header_len.adoc @@ -0,0 +1,23 @@ +## 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 + +xref:nng_msg_header.adoc[nng_msg_header] diff --git a/docs/ref/msg/nng_msg_header_trim.adoc b/docs/ref/msg/nng_msg_header_trim.adoc new file mode 100644 index 00000000..bad67793 --- /dev/null +++ b/docs/ref/msg/nng_msg_header_trim.adoc @@ -0,0 +1,39 @@ +## 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 + +These functions remove data from the start of the header of message _msg_. + +The `nng_msg_header_trim` function removes _size_ bytes. +The remaining functions removes 2, 4, or 8 bytes, and stores them in the value (such as _val32_), +after converting them from network-byte order (big-endian) to native byte order. + +### Return Values + +This function returns 0 on success, and non-zero otherwise. + +### Errors + +[horizontal] +`NNG_EINVAL`:: The message header is too short to remove the requested data. + +### See Also + +xref:nng_msg_header.adoc[nng_msg_header], +xref:nng_msg_header_append.adoc[nng_msg_header_append], +xref:nng_msg_header_chop.adoc[nng_msg_header_chop], +xref:nng_msg_header_insert.adoc[nng_msg_header_insert], +xref:nng_msg_header_len.adoc[nng_msg_header_len], diff --git a/docs/ref/msg/nng_msg_insert.adoc b/docs/ref/msg/nng_msg_insert.adoc new file mode 100644 index 00000000..7787a0a4 --- /dev/null +++ b/docs/ref/msg/nng_msg_insert.adoc @@ -0,0 +1,39 @@ +## 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 + +These functions prepend data to the front of the body of message _msg_, reallocating it if necessary.footnote:[These functions make use of space pre-allocated in front of the message body if available. +Thus, they can often avoid performing any reallocation.] + +The `nng_msg_insert` function prepends _size_ bytes, copying them from _val_. +The remaining functions prepend the specified value (such as _val32_) in network-byte order (big-endian). + + +### Return Values + +These functions return 0 on success, and non-zero otherwise. + +### Errors + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists. + +### See Also + +xref:nng_msg_append.adoc[nng_msg_append], +xref:nng_msg_body.adoc[nng_msg_body], +xref:nng_msg_trim.adoc[nng_msg_trim], +xref:nng_msg_realloc.adoc[nng_msg_realloc] diff --git a/docs/ref/msg/nng_msg_len.adoc b/docs/ref/msg/nng_msg_len.adoc new file mode 100644 index 00000000..0f2d1ed0 --- /dev/null +++ b/docs/ref/msg/nng_msg_len.adoc @@ -0,0 +1,25 @@ +## 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 + +xref:nng_msg_alloc.adoc[nng_msg_alloc], +xref:nng_msg_body.adoc[nng_msg_body], +xref:nng_msg_capacity.adoc[nng_msg_capacity] diff --git a/docs/ref/msg/nng_msg_realloc.adoc b/docs/ref/msg/nng_msg_realloc.adoc new file mode 100644 index 00000000..bf6e4831 --- /dev/null +++ b/docs/ref/msg/nng_msg_realloc.adoc @@ -0,0 +1,41 @@ +## 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. + +Reallocation is guaranteed to succeeed new length is less than xref:nng_msg_capacity.adoc[`nng_msg_capacity`]. + +TIP: `nng_msg_realloc` is suitable for creating space for direct writing of data. +When appending many small pieces of data to a message using xref:nng_msg_append.adoc[`nng_msg_append`], allocations may be reduced by first using xref:nng_msg_reserve.adoc[`nng_msg_reserve`] to create sufficient space. + +NOTE: Reallocation invalidates any previously obtained pointers to the message body or header. + +### Return Values + +This function returns 0 on success, and non-zero otherwise. + +### Errors + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists to reallocate a message. + +### See Also + +xref:nng_msg_append.adoc[nng_msg_append], +xref:nng_msg_body.adoc[nng_msg_body], +xref:nng_msg_insert.adoc[nng_msg_insert], +xref:nng_msg_len.adoc[nng_msg_len], +xref:nng_msg_reserve.adoc[nng_msg_reserve], +xref:nng_msg_trim.adoc[nng_msg_trim] diff --git a/docs/ref/msg/nng_msg_reserve.adoc b/docs/ref/msg/nng_msg_reserve.adoc new file mode 100644 index 00000000..6f9eff50 --- /dev/null +++ b/docs/ref/msg/nng_msg_reserve.adoc @@ -0,0 +1,38 @@ +## 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 xref:nng_msg_append.adoc[`nng_msg_append`] will prevent additional memory allocations until the message's length exceeds the alotted capacity. + +NOTE: Reallocation invalidates any previously obtained pointers to the message body or header. + +### Return Values + +This function returns 0 on success, and non-zero otherwise. + +### Errors + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists to reallocate a message. + +### See Also + +xref:nng_msg_alloc.adoc[nng_msg_alloc], +xref:nng_msg_append.adoc[nng_msg_append], +xref:nng_msg_body.adoc[nng_msg_body], +xref:nng_msg_capacity.adoc[nng_msg_capacity], +xref:nng_msg_insert.adoc[nng_msg_insert], +xref:nng_msg_len.adoc[nng_msg_len] diff --git a/docs/ref/msg/nng_msg_set_pipe.adoc b/docs/ref/msg/nng_msg_set_pipe.adoc new file mode 100644 index 00000000..693cb584 --- /dev/null +++ b/docs/ref/msg/nng_msg_set_pipe.adoc @@ -0,0 +1,23 @@ +## 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` function sets the xref:../pipe/index.adoc[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. + +Not all protocols support overriding the destination pipe. + +### See Also + +xref:nng_msg_get_pipe.adoc[nng_msg_get_pipe], +xref:../pipe/nng_pipe_get.adoc[nng_pipe_getopt] diff --git a/docs/ref/msg/nng_msg_trim.adoc b/docs/ref/msg/nng_msg_trim.adoc new file mode 100644 index 00000000..58efff62 --- /dev/null +++ b/docs/ref/msg/nng_msg_trim.adoc @@ -0,0 +1,37 @@ +## 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 + +These functions remove data from the start of the body of message _msg_. + +The `nng_msg_trim` 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 + +[horizontal] +`NNG_EINVAL`:: The message body is too short to remove the requested data. + +### See Also + +xref:nng_msg_body.adoc[nng_msg_body], +xref:nng_msg_chop.adoc[nng_msg_chop], +xref:nng_msg_free.adoc[nng_msg_free], +xref:nng_msg_insert.adoc[nng_msg_insert] diff --git a/docs/ref/tweak.go b/docs/ref/tweak.go index b1710e0a..d1f2ae3c 100644 --- a/docs/ref/tweak.go +++ b/docs/ref/tweak.go @@ -23,7 +23,7 @@ func dofile(file string) { continue case strings.HasPrefix(line, "[.text-left]"): continue - case strings.HasPrefix(line, "[source, c]"): + case strings.HasPrefix(line, "[source, c]") || strings.HasPrefix(line,"[source,c]"): out.WriteString("```c\n") scanner.Scan() // eat the next line continue -- cgit v1.2.3-70-g09d2