diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/libnng.adoc | 85 | ||||
| -rw-r--r-- | docs/nng.adoc | 95 | ||||
| -rw-r--r-- | docs/nng_msg_alloc.adoc | 64 | ||||
| -rw-r--r-- | docs/nng_msg_append.adoc | 63 | ||||
| -rw-r--r-- | docs/nng_msg_body.adoc | 66 | ||||
| -rw-r--r-- | docs/nng_msg_chop.adoc | 64 | ||||
| -rw-r--r-- | docs/nng_msg_clear.adoc | 50 | ||||
| -rw-r--r-- | docs/nng_msg_dup.adoc | 54 | ||||
| -rw-r--r-- | docs/nng_msg_free.adoc | 50 | ||||
| -rw-r--r-- | docs/nng_msg_header.adoc | 65 | ||||
| -rw-r--r-- | docs/nng_msg_header_append.adoc | 62 | ||||
| -rw-r--r-- | docs/nng_msg_header_chop.adoc | 62 | ||||
| -rw-r--r-- | docs/nng_msg_header_clear.adoc | 50 | ||||
| -rw-r--r-- | docs/nng_msg_header_insert.adoc | 62 | ||||
| -rw-r--r-- | docs/nng_msg_header_len.adoc | 50 | ||||
| -rw-r--r-- | docs/nng_msg_header_trim.adoc | 62 | ||||
| -rw-r--r-- | docs/nng_msg_insert.adoc | 66 | ||||
| -rw-r--r-- | docs/nng_msg_len.adoc | 50 | ||||
| -rw-r--r-- | docs/nng_msg_realloc.adoc | 70 | ||||
| -rw-r--r-- | docs/nng_msg_trim.adoc | 63 | ||||
| -rw-r--r-- | docs/nng_strerror.adoc | 28 |
21 files changed, 1169 insertions, 112 deletions
diff --git a/docs/libnng.adoc b/docs/libnng.adoc index e5fd24ec..179b9a0e 100644 --- a/docs/libnng.adoc +++ b/docs/libnng.adoc @@ -1,9 +1,7 @@ -libnng(3) -========= += libnng(3) :doctype: manpage :manmanual: nng :mansource: nng -:icons: font :copyright: Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> \ Copyright 2018 Capitar IT Group BV <info@capitar.com> \ This software is supplied under the terms of the MIT License, a \ @@ -11,28 +9,26 @@ libnng(3) file was obtained (LICENSE.txt). A copy of the license may also \ be found online at https://opensource.org/licenses/MIT. -NAME ----- +== NAME + libnng - nanomsg next generation library -SYNOPSIS --------- +== SYNOPSIS + *cc* ['flags'] 'files' *-lnng* ['libraries'] -DESCRIPTION ------------ +== DESCRIPTION The <<nng#,nng(7)>> library provides a common messaging framework intended to solve common communication problems in distributed applications. It provides a C language API. -Common Functions -~~~~~~~~~~~~~~~~ +=== Common Functions + The following common functions exist in _libnng_. -[cols="1,4"] |=== |<<nng_alloc#,nng_alloc(3)>>|allocate memory |<<nng_dial#,nng_dial(3)>>|create and start a dialer @@ -40,12 +36,10 @@ The following common functions exist in _libnng_. |<<nng_strerror#,nng_strerror(3)>>|return an error description |=== -Socket Functions -~~~~~~~~~~~~~~~~ +=== Socket Functions The following functions operate on sockets. -[cols="1,4"] |=== |<<nng_close#,nng_close(3)>>|close a socket |<<nng_closeall#,nng_closeall(3)>>|close all open sockets @@ -57,8 +51,7 @@ The following functions operate on sockets. |<<nng_setopt#,nng_setopt(3)>>|set a socket option |=== -Message Functions -~~~~~~~~~~~~~~~~~ +=== Message Handling Functions Applications desiring to use the richest part of _libnng_ will want to use the message API, where a message structure is passed between functions. @@ -68,21 +61,39 @@ Messages are divided into a header and body, where the body generally carries user-payload and the header carries protocol specific header information. Most applications will only interact with the body. -[cols="1,4"] |=== |<<nng_msg_alloc#,nng_msg_alloc(3)>>|allocate a message -|<<nng_msg_body#,nng_msg_body(3)>>|return the message body +|<<nng_msg_append#,nng_msg_append(3)>>|append to message body +|<<nng_msg_body#,nng_msg_body(3)>>|return message body +|<<nng_msg_chop#,nng_msg_chop(3)>>|remove data from end of message body +|<<nng_msg_clear#,nng_msg_clear(3)>>|clear message body +|<<nng_msg_dup#,nng_msg_len(3)>>|duplicate a message |<<nng_msg_free#,nng_msg_free(3)>>|free a message -|<<nng_msg_header#,nng_msg_header(3)>>|return the message header -|<<nng_msg_header_len#,nng_msg_header_len(3)>>|return the message header length +|<<nng_msg_insert#,nng_msg_insert(3)>>|prepend to message body |<<nng_msg_len#,nng_msg_len(3)>>|return the message body length |<<nng_msg_realloc#,nng_msg_realloc(3)>>|reallocate a message +|<<nng_msg_trim#,nng_msg_trim(3)>>|remove data from start of message body |<<nng_recv_msg#,nng_recvmsg(3)>>|receive a message |<<nng_sendmsg#,nng_sendmsg(3)>>|send a message |=== -Asynchronous Operations -~~~~~~~~~~~~~~~~~~~~~~~ +==== Message Header Handling + +TIP: Few applications will need these functions, as message headers are only +used to carry protocol-specific content. However, applications which use raw +mode may need to access the header of messages. + +|=== +|<<nng_msg_header#,nng_msg_header(3)>>|return message header +|<<nng_msg_header_append#,nng_msg_header_append(3)>>|append to message header +|<<nng_msg_header_chop#,nng_msg_header_chop(3)>>|remove data from end of message header +|<<nng_msg_header_clear#,nng_msg_header_clear(3)>>|clear message header +|<<nng_msg_header_insert#,nng_msg_header_insert(3)>>|prepend to message header +|<<nng_msg_header_len#,nng_msg_header_len(3)>>|return the message header length +|<<nng_msg_header_trim#,nng_msg_header_trim(3)>>|remove data from start of message header +|=== + +=== Asynchronous Operations Most applications will interact with _nng_ synchronously; that is that functions such as <<nng_send#,nng_send()>> will block the calling @@ -105,7 +116,6 @@ be associated with an _aio_ at any time. The following functions are used in the asynchronous model: -[cols="1,4"] |=== |<<nng_aio_alloc#,nng_aio_alloc(3)>>|allocate asynchronous I/O context |<<nng_aio_cancel#,nng_aio_cancel(3)>>|cancel asynchronous I/O operation @@ -120,13 +130,11 @@ The following functions are used in the asynchronous model: |<<nng_send_aio#,nng_send_aio(3)>>|send a message asynchronously |=== -Protocols -~~~~~~~~~ +=== Protocols The following functions are used to construct a socket with a specific protocol: -[cols="1,4"] |=== | <<nng_bus#,nng_bus_open(3)>>|open a bus socket | <<nng_pair#,nng_pair_open(3)>>|open a pair socket @@ -138,12 +146,10 @@ protocol: | <<nng_surveyor#,nng_surveyor_open(3)>>|open a surveyor socket |=== -Transports -~~~~~~~~~~ +=== Transports The following functions are used to register a transport for use. -[cols="1,4"] |=== | <<nng_inproc#,nng_inproc_register(3)>>|register inproc transport | <<nng_ipc#,nng_ipc_register(3)>>|register IPC transport @@ -154,12 +160,14 @@ The following functions are used to register a transport for use. | <<nng_zerotier#,nng_zerotier_register(3)>>|register ZeroTier transport |=== -TLS Configuration Objects -~~~~~~~~~~~~~~~~~~~~~~~~ +=== TLS Configuration Objects + +The following functions are used to manipulate transport layer security +(TLS) configuration objects. -The following functions are used to manipulate TLS configuration objects. +NOTE: These functions will only be present if the library has been built +with TLS support. -[cols="1,4"] |=== | <<nng_tls_config_auth_alloc#,nng_tls_config_alloc(3)>>|allocate TLS configuration | <<nng_tls_config_auth_mode#,nng_tls_config_auth_mode(3)>>|set authentication mode @@ -167,18 +175,17 @@ The following functions are used to manipulate TLS configuration objects. | <<nng_tls_config_ca_file#,nng_tls_config_ca_file(3)>>|load certificate authority from file | <<nng_tls_config_cert_key_file#,nng_tls_config_cert_key_file_cert(3)>>|load own certificate and key from file | <<nng_tls_config_own_cert#,nng_tls_config_own_cert(3)>>|set own certificate and key -| <<nng_tls_config_free#,nng_tls_config_free(3)>>}free TLS configuration +| <<nng_tls_config_free#,nng_tls_config_free(3)>>|free TLS configuration | <<nng_tls_config_server_name#,nng_tls_config_server_name(3)>>|set remote server name |=== -SEE ALSO --------- +== SEE ALSO + <<nng#,nng(7)>>, <<nng_compat#,nng_compat(3)>> -COPYRIGHT ---------- +== COPYRIGHT Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] diff --git a/docs/nng.adoc b/docs/nng.adoc index 2da365de..62482d09 100644 --- a/docs/nng.adoc +++ b/docs/nng.adoc @@ -1,9 +1,7 @@ -nng(7) -====== += nng(7) :doctype: manpage :manmanual: nng :mansource: nng -:icons: font :copyright: Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> \ Copyright 2018 Capitar IT Group BV <info@capitar.com> \ This software is supplied under the terms of the MIT License, a \ @@ -11,17 +9,14 @@ nng(7) file was obtained (LICENSE.txt). A copy of the license may also \ be found online at https://opensource.org/licenses/MIT. -NAME ----- +== NAME nng - nanomsg next generation -SYNOPSIS --------- +== SYNOPSIS *cc* ['flags'] 'files' *-lnng* ['libraries'] -DESCRIPTION ------------ +== DESCRIPTION The _nng_ library provides a common messaging framework intended to solve common communication problems in distributed applications. @@ -53,40 +48,7 @@ application developer to use the new-style API. The _nng_ library is implemented in pure C; if you need bindings for other languages please check the http://nanomsg.org/[website]. -URLs -~~~~ - -The _nng_ library uses universal resource locators (URLs) -following the format specified in -https://tools.ietf.org/html/rfc3986[RFC 3986], -including some schemes that are unique -to SP. -The URLs used in _nng_ are canonicalized as follows, mostly in -accordance with -https://tools.ietf.org/html/rfc3986#section-6.2.2[RFC 3986 6.2.2]: - - 1. The URL is parsed into scheme, userinfo, host, port, path, query and - fragment components. (Not all of these members are necessarily present.) - 2. The scheme, hostname, and port if present, are converted to lower case. - 3. Percent-encoded values for - https://tools.ietf.org/html/rfc3986#section-2.3[unreserved characters] - converted to their unencoded forms. - 4. Additionally URL percent-encoded values for characters in the path - and with numeric values larger than 127 (i.e. not ASCII) are decoded. - 5. The resulting path is checked for invalid UTF-8 sequences, consisting - of surrogate pairs, illegal byte sequences, or overlong encodings. - If this check fails, then the entire URL is considered invalid. - 6. Path segments consisting of `.` and `..` are resolved as per - https://tools.ietf.org/html/rfc3986#section-6.2.2.3[RFC 3986 6.2.2.3]. - 7. Further, empty path segments are removed, meaning that duplicate - slash (`/`) separators are removed from the path. - -Note that steps 4, 5, and 7 are not specified by RFC 3986, but performing -them is believed to improve both the usability and security of _nng_ -applications, without violating RFC 3986 itself. - -Protocols -~~~~~~~~~ +== Protocols * <<nng_bus#,nng_bus(7)>> - Bus protocol * <<nng_pair#,nng_pair(7)>> - Pair protocol @@ -99,8 +61,7 @@ Protocols * <<nng_respondent#,nng_respondent(7)>> - Respondent side of survey protocol * <<nng_surveyor#,nng_surveyor(7)>> - Surveyor side of survey protocol -Transports -~~~~~~~~~~ +== Transports * <<nng_inproc#,nng_inproc(7)>> - Intra-process transport * <<nng_ipc#,nng_ipc(7)>> - Inter-process transport @@ -109,8 +70,7 @@ Transports * <<nng_ws#,nng_ws(7)>> - WebSocket transport * <<nng_zerotier#,nng_zerotier(7)>> - ZeroTier transport -Conceptual Overview -~~~~~~~~~~~~~~~~~~~ +== Conceptual Overview _nng_ presents a _socket_ view of networking. The sockets are constructed using protocol-specific functions, as a given socket implements precisely @@ -152,18 +112,47 @@ Most applications should not have to worry about endpoints or pipes at all; the socket abstraction should provide all the functionality needed other than in a few specific circumstances. -API -~~~ +=== URLs + +The _nng_ library uses universal resource locators (URLs) +following the format specified in +https://tools.ietf.org/html/rfc3986[RFC 3986], +including some schemes that are unique +to SP. +The URLs used in _nng_ are canonicalized as follows, mostly in +accordance with +https://tools.ietf.org/html/rfc3986#section-6.2.2[RFC 3986 6.2.2]: + + 1. The URL is parsed into scheme, userinfo, host, port, path, query and + fragment components. (Not all of these members are necessarily present.) + 2. The scheme, hostname, and port if present, are converted to lower case. + 3. Percent-encoded values for + https://tools.ietf.org/html/rfc3986#section-2.3[unreserved characters] + converted to their unencoded forms. + 4. Additionally URL percent-encoded values for characters in the path + and with numeric values larger than 127 (i.e. not ASCII) are decoded. + 5. The resulting path is checked for invalid UTF-8 sequences, consisting + of surrogate pairs, illegal byte sequences, or overlong encodings. + If this check fails, then the entire URL is considered invalid. + 6. Path segments consisting of `.` and `..` are resolved as per + https://tools.ietf.org/html/rfc3986#section-6.2.2.3[RFC 3986 6.2.2.3]. + 7. Further, empty path segments are removed, meaning that duplicate + slash (`/`) separators are removed from the path. + +Note that steps 4, 5, and 7 are not specified by RFC 3986, but performing +them is believed to improve both the usability and security of _nng_ +applications, without violating RFC 3986 itself. + +== API The library API is documented at <<libnng#,libnng(3)>>. -SEE ALSO --------- +== SEE ALSO + <<libnng#,libnng(3)>>, <<nng_compat#,nng_compat(3)>> -COPYRIGHT ---------- +== COPYRIGHT Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc] + Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] diff --git a/docs/nng_msg_alloc.adoc b/docs/nng_msg_alloc.adoc new file mode 100644 index 00000000..8446c358 --- /dev/null +++ b/docs/nng_msg_alloc.adoc @@ -0,0 +1,64 @@ += nng_msg_alloc(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> \ + Copyright 2018 Capitar IT Group BV <info@capitar.com> \ + This software 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 <nng/nng.h> + +int nng_msg_alloc(nng_msg **msgp, size_t size); +----------- + + +== DESCRIPTION + +The `nng_msg_alloc()` function allocates a new message with body length _size_ +and stores the result in __msgp__. +Messages allocated with this function contain a body and optionally a header. +They are used with receive and transmit functions. + + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + + +== ERRORS + +`NNG_ENOMEM`:: Insufficient free memory exists to allocate a message. + + +== SEE ALSO + +<<nng_msg_free#,nng_msg_free(3)>>, +<<nng_msg_body#,nng_msg_body(3)>>, +<<nng_msg_dup#,nng_msg_dup(3)>>, +<<nng_msg_header#,nng_msg_header(3)>>, +<<nng_msg_header_len#,nng_msg_header_len(3)>>, +<<nng_msg_len#,nng_msg_len(3)>>, +<<nng_msg_realloc#,nng_msg_realloc(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> + + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_msg_append.adoc b/docs/nng_msg_append.adoc new file mode 100644 index 00000000..205863d7 --- /dev/null +++ b/docs/nng_msg_append.adoc @@ -0,0 +1,63 @@ += nng_msg_append(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> \ + Copyright 2018 Capitar IT Group BV <info@capitar.com> \ + This software 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, nng_msg_append_u32 - append to message body + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_msg_append(nng_msg *msg, const void *val, size_t size); +int nng_msg_append_u32(nng_msg *msg, uint32_t val32); +----------- + +== DESCRIPTION + +The `nng_msg_append()` and `nng_msg_append_u32()` functions append 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 +second function appends the value _val32_ in network-byte order (big-endian). + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOMEM`:: Insufficient free memory exists. + + +== SEE ALSO + +<<nng_msg_alloc#,nng_msg_alloc(3)>>, +<<nng_msg_body#,nng_msg_body(3)>>, +<<nng_msg_chop#,nng_msg_chop(3)>>, +<<nng_msg_free#,nng_msg_free(3)>>, +<<nng_msg_insert#,nng_msg_insert(3)>>, +<<nng_msg_len#,nng_msg_len(3)>>, +<<nng_msg_realloc#,nng_msg_realloc(3)>>, +<<nng_msg_trim#,nng_msg_trim(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> + + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_msg_body.adoc b/docs/nng_msg_body.adoc new file mode 100644 index 00000000..a5b1e536 --- /dev/null +++ b/docs/nng_msg_body.adoc @@ -0,0 +1,66 @@ += nng_msg_body(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> \ + Copyright 2018 Capitar IT Group BV <info@capitar.com> \ + This software 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 <nng/nng.h> + +void *nng_msg_body(nng_msg *msg); +----------- + +== DESCRIPTION + +The `nng_msg_body()` function returns a pointer to the start of the body +content of the message _msg_. + +NOTE: The value returned by this is invalidated by a call to any of the +functions that modify the message itself. Such functions are +<<nng_msg_free#,nng_msg_free(3)>>, <<nng_msg_realloc#,nng_msg_realloc(3)>>, +any of the <<nng_msg_trim#,nng_msg_trim(3)>>, +<<nng_msg_chop#,nng_msg_chop(3)>>, <<nng_msg_append#,nng_msg_append(3)>>, +or <<nng_msg_insert#,nng_msg_insert(3)>> variants. + + +== RETURN VALUES + +Pointer to start of message body. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_msg_alloc#,nng_msg_alloc(3)>>, +<<nng_msg_append#,nng_msg_append(3)>>, +<<nng_msg_chop#,nng_msg_chop(3)>>, +<<nng_msg_free#,nng_msg_free(3)>>, +<<nng_msg_insert#,nng_msg_insert(3)>>, +<<nng_msg_len#,nng_msg_len(3)>>, +<<nng_msg_realloc#,nng_msg_realloc(3)>>, +<<nng_msg_trim#,nng_msg_trim(3)>>, +<<nng#,nng(7)>> + + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_msg_chop.adoc b/docs/nng_msg_chop.adoc new file mode 100644 index 00000000..547ed8d0 --- /dev/null +++ b/docs/nng_msg_chop.adoc @@ -0,0 +1,64 @@ += nng_msg_chop(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> \ + Copyright 2018 Capitar IT Group BV <info@capitar.com> \ + This software 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, nng_msg_chop_u32 - remove data from end of message body + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_msg_chop(nng_msg *msg, size_t size); +int nng_msg_chop_u32(nng_msg *msg, uint32_t *val32); +----------- + +== DESCRIPTION + +The `nng_msg_chop()` and `nng_msg_chop_u32()` functions remove data from +the end of the body of message _msg_. +The first function removes _size_ bytes. +The second function removes 4 bytes, and stores them in the value _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 body is too short to remove the requested data. + +== SEE ALSO + +<<nng_msg_alloc#,nng_msg_alloc(3)>>, +<<nng_msg_append#,nng_msg_append(3)>>, +<<nng_msg_body#,nng_msg_body(3)>>, +<<nng_msg_free#,nng_msg_free(3)>>, +<<nng_msg_insert#,nng_msg_insert(3)>>, +<<nng_msg_len#,nng_msg_len(3)>>, +<<nng_msg_realloc#,nng_msg_realloc(3)>>, +<<nng_msg_trim#,nng_msg_trim(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> + + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_msg_clear.adoc b/docs/nng_msg_clear.adoc new file mode 100644 index 00000000..b84f024a --- /dev/null +++ b/docs/nng_msg_clear.adoc @@ -0,0 +1,50 @@ += nng_msg_clear(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> \ + Copyright 2018 Capitar IT Group BV <info@capitar.com> \ + This software 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 <nng/nng.h> + +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 + +<<nng_msg_alloc#,nng_msg_alloc(3)>>, +<<nng_msg_free#,nng_msg_free(3)>>, +<<nng#,nng(7)>> + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_msg_dup.adoc b/docs/nng_msg_dup.adoc new file mode 100644 index 00000000..7da8b7b0 --- /dev/null +++ b/docs/nng_msg_dup.adoc @@ -0,0 +1,54 @@ += nng_msg_dup(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> \ + Copyright 2018 Capitar IT Group BV <info@capitar.com> \ + This software 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 <nng/nng.h> + +int nng_msg_dup(nng_msg **dup, nng_msg_t *orig); +----------- + +== DESCRIPTION + +The `nng_msg_dup()` makes a duplicate of the original message _orig_, and +saves the result in the location pointed by _dup_. The actual message +body and header content is copied, but the duplicate may contain a +different amount of unused space than the original message. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOMEM`:: Insufficient free memory exists to duplicate a message. + +== SEE ALSO + +<<nng_msg_alloc#,nng_msg_alloc(3)>>, +<<nng_msg_free#,nng_msg_free(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_msg_free.adoc b/docs/nng_msg_free.adoc new file mode 100644 index 00000000..f1f66cd1 --- /dev/null +++ b/docs/nng_msg_free.adoc @@ -0,0 +1,50 @@ += nng_msg_free(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> \ + Copyright 2018 Capitar IT Group BV <info@capitar.com> \ + This software 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 <nng/nng.h> + +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 + +<<nng_msg_alloc#,nng_msg_alloc(3)>>, +<<nng_msg_realloc#,nng_msg_realloc(3)>>, +<<nng#,nng(7)>> + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_msg_header.adoc b/docs/nng_msg_header.adoc new file mode 100644 index 00000000..46efd6d5 --- /dev/null +++ b/docs/nng_msg_header.adoc @@ -0,0 +1,65 @@ += nng_msg_header(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> \ + Copyright 2018 Capitar IT Group BV <info@capitar.com> \ + This software is supplied under the terms of the MIT License, a \ + copy of which should be located in the distribution where this \ + file was obtained (LICENSE.txt). A copy of the license may also \ + be found online at https://opensource.org/licenses/MIT. + +== NAME + +nng_msg_header - return message header + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +void *nng_msg_header(nng_msg *msg); +----------- + +== DESCRIPTION + +The `nng_msg_header()` function returns a pointer to the start of the header +content of the message _msg_. + +NOTE: The message header contains protocol-specific header content. Most +applications should not need to access this content, but it is available +for raw mode sockets (set with the `NNG_OPT_RAW` option -- see +<<nng_setopt#,nng_setopt(3)>> for more details.) + +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 + +<<nng_msg_alloc#,nng_msg_alloc(3)>>, +<<nng_msg_body#,nng_msg_body(3)>>, +<<nng_msg_free#,nng_msg_free(3)>>, +<<nng_msg_header_append#,nng_msg_header_append(3)>>, +<<nng_msg_header_chop#,nng_msg_header_chop(3)>>, +<<nng_msg_header_insert#,nng_msg_header_insert(3)>> +<<nng_msg_header_len#,nng_msg_header_len(3)>>, +<<nng_msg_header_trim#,nng_msg_header_trim(3)>>, +<<nng#,nng(7)>> + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_msg_header_append.adoc b/docs/nng_msg_header_append.adoc new file mode 100644 index 00000000..2b839759 --- /dev/null +++ b/docs/nng_msg_header_append.adoc @@ -0,0 +1,62 @@ += nng_msg_header_append(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> \ + Copyright 2018 Capitar IT Group BV <info@capitar.com> \ + This software 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, nng_msg_header_append_u32 - append to message header + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_msg_header_append(nng_msg *msg, const void *val, size_t size); +int nng_msg_header_append_u32(nng_msg *msg, uint32_t val32); +----------- + +== DESCRIPTION + +The `nng_msg_header_append()` and `nng_msg_header_append_u32()` +functions append 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 +second function appends the value _val32_ in network-byte order (big-endian). + + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOMEM`:: Insufficient free memory exists. + +== SEE ALSO + +<<nng_msg_alloc#,nng_msg_alloc(3)>>, +<<nng_msg_header#,nng_msg_header(3)>>, +<<nng_msg_header_chop#,nng_msg_header_chop(3)>>, +<<nng_msg_header_insert#,nng_msg_header_insert(3)>>, +<<nng_msg_header_len#,nng_msg_header_len(3)>>, +<<nng_msg_header_trim#,nng_msg_header_trim(3)>>, +<<nng_msg_free#,nng_msg_free(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_msg_header_chop.adoc b/docs/nng_msg_header_chop.adoc new file mode 100644 index 00000000..cafd1995 --- /dev/null +++ b/docs/nng_msg_header_chop.adoc @@ -0,0 +1,62 @@ += nng_msg_header_chop(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> \ + Copyright 2018 Capitar IT Group BV <info@capitar.com> \ + This software 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, nng_msg_header_chop_u32 - remove data from end of message header + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_msg_header_chop(nng_msg *msg, size_t size); +int nng_msg_header_chop_u32(nng_msg *msg, uint32_t *val32); +----------- + +== DESCRIPTION + +The `nng_msg_header_chop()` and `nng_msg_header_chop_u32()` functions remove +data from the end of the header of message _msg_. +The first function removes _size_ bytes. +The second function removes 4 bytes, and stores them in the value _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_alloc#,nng_msg_alloc(3)>>, +<<nng_msg_header#,nng_msg_header(3)>>, +<<nng_msg_header_append#,nng_msg_header_append(3)>>, +<<nng_msg_header_insert#,nng_msg_header_insert(3)>>, +<<nng_msg_header_len#,nng_msg_header_len(3)>>, +<<nng_msg_header_trim#,nng_msg_header_trim(3)>>, +<<nng_msg_free#,nng_msg_free(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_msg_header_clear.adoc b/docs/nng_msg_header_clear.adoc new file mode 100644 index 00000000..3880ed6d --- /dev/null +++ b/docs/nng_msg_header_clear.adoc @@ -0,0 +1,50 @@ += nng_msg_header_clear(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> \ + Copyright 2018 Capitar IT Group BV <info@capitar.com> \ + This software is supplied under the terms of the MIT License, a \ + copy of which should be located in the distribution where this \ + file was obtained (LICENSE.txt). A copy of the license may also \ + be found online at https://opensource.org/licenses/MIT. + +== NAME + +nng_msg_header_clear - clear message header + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +void nng_msg_header_clear(nng_msg *msg); +----------- + +== DESCRIPTION + +The `nng_msg_clear()` function resets the header length of _msg_ to zero. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_msg_alloc#,nng_msg_alloc(3)>>, +<<nng_msg_free#,nng_msg_free(3)>>, +<<nng#,nng(7)>> + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_msg_header_insert.adoc b/docs/nng_msg_header_insert.adoc new file mode 100644 index 00000000..87c8428f --- /dev/null +++ b/docs/nng_msg_header_insert.adoc @@ -0,0 +1,62 @@ += nng_msg_header_insert(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> \ + Copyright 2018 Capitar IT Group BV <info@capitar.com> \ + This software 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, nng_msg_header_insert_u32 - prepend to message header + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_msg_header_insert(nng_msg *msg, const void *val, size_t size); +int nng_msg_header_insert_u32(nng_msg *msg, uint32_t val32); +----------- + +== DESCRIPTION + +The `nng_msg_header_insert()` and `nng_msg_header_insert_u32()` functions +prepend data to the front of the headers of message _msg_, reallocating +if necessary. +The first function prepends _size_ bytes, copying them from _val_. The +second function prepends the value _val32_ in network-byte order (big-endian). + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOMEM`:: Insufficient free memory exists. + +== SEE ALSO + +<<nng_msg_alloc#,nng_msg_alloc(3)>>, +<<nng_msg_header_append#,nng_msg_header_append(3)>>, +<<nng_msg_header_body#,nng_msg_header_body(3)>>, +<<nng_msg_header_chop#,nng_msg_header_chop(3)>>, +<<nng_msg_header_len#,nng_msg_header_len(3)>>, +<<nng_msg_header_trim#,nng_msg_header_trim(3)>>, +<<nng_msg_free#,nng_msg_free(3)>>, +<<nng_msg_realloc#,nng_msg_realloc(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_msg_header_len.adoc b/docs/nng_msg_header_len.adoc new file mode 100644 index 00000000..48c411c2 --- /dev/null +++ b/docs/nng_msg_header_len.adoc @@ -0,0 +1,50 @@ += nng_msg_header_len(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> \ + Copyright 2018 Capitar IT Group BV <info@capitar.com> \ + This software is supplied under the terms of the MIT License, a \ + copy of which should be located in the distribution where this \ + file was obtained (LICENSE.txt). A copy of the license may also \ + be found online at https://opensource.org/licenses/MIT. + +== NAME + +nng_msg_header_len - return message header length + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +size_t nng_msg_header_len(nng_msg *msg); +----------- + +== DESCRIPTION + +The `nng_msg_header_len()` returns the length of message header of _msg_. + +== RETURN VALUES + +Length of message header. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_msg_alloc#,nng_msg_alloc(3)>>, +<<nng_msg_header#,nng_msg_header(3)>>, +<<nng#,nng(7)>> + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_msg_header_trim.adoc b/docs/nng_msg_header_trim.adoc new file mode 100644 index 00000000..8c59272c --- /dev/null +++ b/docs/nng_msg_header_trim.adoc @@ -0,0 +1,62 @@ += nng_msg_header_trim(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> \ + Copyright 2018 Capitar IT Group BV <info@capitar.com> \ + This software 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, nng_msg_header_trim_u32 - remove data from start of message header + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_msg_header_trim(nng_msg *msg, size_t size); +int nng_msg_header_trim_u32(nng_msg *msg, uint32_t *val32); +----------- + +== DESCRIPTION + +The `nng_msg_header_trim()` and `nng_msg_header_trim_u32()` functions remove +data from the start of the header of message _msg_. +The first function removes _size_ bytes. +The second function removes 4 bytes, and stores them in the value _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_alloc#,nng_msg_alloc(3)>>, +<<nng_msg_header#,nng_msg_header(3)>>, +<<nng_msg_header_append#,nng_msg_header_append(3)>>, +<<nng_msg_header_chop#,nng_msg_header_chop(3)>>, +<<nng_msg_header_insert#,nng_msg_header_insert(3)>>, +<<nng_msg_header_len#,nng_msg_header_len(3)>>, +<<nng_msg_free#,nng_msg_free(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_msg_insert.adoc b/docs/nng_msg_insert.adoc new file mode 100644 index 00000000..5b4377f5 --- /dev/null +++ b/docs/nng_msg_insert.adoc @@ -0,0 +1,66 @@ += nng_msg_insert(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> \ + Copyright 2018 Capitar IT Group BV <info@capitar.com> \ + This software 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, nng_msg_insert_u32 - prepend to message body + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_msg_insert(nng_msg *msg, const void *val, size_t size); +int nng_msg_insert(nng_msg *msg, uint32_t val32); +----------- + +== DESCRIPTION + +The `nng_msg_insert()` and `nng_msg_insert_u32()` functions prepend 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 +second function prepends the value _val32_ in network-byte order (big-endian). + +TIP: This function makes use of pre-allocated "headroom" in the message if +available, so it can often avoid performing any reallocation. Applications +should use this instead of reallocating and copying message content themselves, +in order to benefit from this capabilitiy. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOMEM`:: Insufficient free memory exists. + +== SEE ALSO + +<<nng_msg_alloc#,nng_msg_alloc(3)>>, +<<nng_msg_append#,nng_msg_append(3)>>, +<<nng_msg_body#,nng_msg_body(3)>>, +<<nng_msg_chop#,nng_msg_chop(3)>>, +<<nng_msg_free#,nng_msg_free(3)>>, +<<nng_msg_len#,nng_msg_len(3)>>, +<<nng_msg_realloc#,nng_msg_realloc(3)>>, +<<nng_msg_trim#,nng_msg_trim(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_msg_len.adoc b/docs/nng_msg_len.adoc new file mode 100644 index 00000000..5629f091 --- /dev/null +++ b/docs/nng_msg_len.adoc @@ -0,0 +1,50 @@ += nng_msg_len(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> \ + Copyright 2018 Capitar IT Group BV <info@capitar.com> \ + This software is supplied under the terms of the MIT License, a \ + copy of which should be located in the distribution where this \ + file was obtained (LICENSE.txt). A copy of the license may also \ + be found online at https://opensource.org/licenses/MIT. + +== NAME + +nng_msg_len - return message body length + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +size_t nng_msg_len(nng_msg *msg); +----------- + +== DESCRIPTION + +The `nng_msg_len()` returns the length of the body of message _msg_. + +== RETURN VALUES + +Length of message body. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_msg_alloc#,nng_msg_alloc(3)>>, +<<nng_msg_body#,nng_msg_body(3)>>, +<<nng#,nng(7)>> + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_msg_realloc.adoc b/docs/nng_msg_realloc.adoc new file mode 100644 index 00000000..3693eca2 --- /dev/null +++ b/docs/nng_msg_realloc.adoc @@ -0,0 +1,70 @@ += nng_msg_alloc(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> \ + Copyright 2018 Capitar IT Group BV <info@capitar.com> \ + This software 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 <nng/nng.h> + +int nng_msg_realloc(nng_msg *msg, size_t size); +----------- + +== DESCRIPTION + +The `nng_msg_realloc()` function re-allocates a message so that it has +a body of length _size_. This message attempts to avoid extra allocations, +and will reuse the existing memory when possible. + +TIP: One way to further reduce message allocations is to allocate a message +larger than needed, then use this function or <<nng_msg_chop#,nng_msg_chop(3)>> +to reduce the message size to that actually needed. The extra space left +over will still be present in the message, so that when the message size +needs to grow due to this function or <<nng_msg_append#,nng_msg_append(3)>> +no actual memory allocations need to take place. + +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(3)>>, +<<nng_msg_append#,nng_msg_append(3)>>, +<<nng_msg_body#,nng_msg_body(3)>>, +<<nng_msg_chop#,nng_msg_chop(3)>>, +<<nng_msg_free#,nng_msg_free(3)>>, +<<nng_msg_insert#,nng_msg_insert(3)>>, +<<nng_msg_len#,nng_msg_len(3)>>, +<<nng_msg_trim#,nng_msg_trim(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_msg_trim.adoc b/docs/nng_msg_trim.adoc new file mode 100644 index 00000000..1b1a166e --- /dev/null +++ b/docs/nng_msg_trim.adoc @@ -0,0 +1,63 @@ += nng_msg_trim(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> \ + Copyright 2018 Capitar IT Group BV <info@capitar.com> \ + This software 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, nng_msg_trim_u32 - remove data from start of message body + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +int nng_msg_trim(nng_msg *msg, size_t size); +int nng_msg_trim_u32(nng_msg *msg, uint32_t *val32); +----------- + +== DESCRIPTION + +The `nng_msg_trim()` and `nng_msg_trim_u32()` functions remove data from +the start of the body of message _msg_. +The first function removes _size_ bytes. +The second function removes 4 bytes, and stores them in the value _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 body is too short to remove the requested data. + +== SEE ALSO + +<<nng_msg_alloc#,nng_msg_alloc(3)>>, +<<nng_msg_append#,nng_msg_append(3)>>, +<<nng_msg_body#,nng_msg_body(3)>>, +<<nng_msg_chop#,nng_msg_chop(3)>>, +<<nng_msg_free#,nng_msg_free(3)>>, +<<nng_msg_insert#,nng_msg_insert(3)>>, +<<nng_msg_len#,nng_msg_len(3)>>, +<<nng_msg_realloc#,nng_msg_realloc(3)>>, +<<nng_strerror#,nng_strerror(3)>>, +<<nng#,nng(7)>> + +== COPYRIGHT + +Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + +Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/MIT[MIT License]. diff --git a/docs/nng_strerror.adoc b/docs/nng_strerror.adoc index c78a1279..568f1150 100644 --- a/docs/nng_strerror.adoc +++ b/docs/nng_strerror.adoc @@ -1,10 +1,7 @@ -nng_strerror(3) -=============== += nng_strerror(3) :doctype: manpage :manmanual: nng :mansource: nng -:icons: font -:source-highlighter: pygments :copyright: Copyright 2018 Garrett D'Amore <garrett@damore.org> \ Copyright 2018 Capitar IT Group BV <info@capitar.com> \ This software is supplied under the terms of the MIT License, a \ @@ -12,12 +9,11 @@ nng_strerror(3) file was obtained (LICENSE.txt). A copy of the license may also \ be found online at https://opensource.org/licenses/MIT. -NAME ----- +== NAME + nng_strerror - return an error description -SYNOPSIS --------- +== SYNOPSIS [source, c] ----------- @@ -26,9 +22,7 @@ SYNOPSIS const char * nng_strerror(int err); ----------- - -DESCRIPTION ------------ +== DESCRIPTION The `nng_strerror()` returns the human-readable description of the given _nng_ error in `err`. @@ -41,23 +35,17 @@ subject to change. Therefore applications must not depend on the message, but may use them verbatim when supplying information to end-users, such as in diagnostic messages or log entries. - -RETURN VALUES -------------- +== RETURN VALUES This function returns the human-readable error message, terminated by a `NUL` byte. - -SEE ALSO --------- +== SEE ALSO <<libnng#,libnng(3)>>, <<nng#,nng(7)>> - -COPYRIGHT ---------- +== COPYRIGHT Copyright 2018 mailto:garrett@damore.org[Garrett D'Amore] + Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] |