nng_msg_alloc(3)

From 3330ebfc2f33f761650f3792077ad45327e14f2f Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Tue, 23 Jan 2018 15:50:21 -0800 Subject: man page updates for 0.2.0 --- man/v0.2.0/README.html | 72 ++++ man/v0.2.0/libnng.html | 210 ++++++++++-- man/v0.2.0/nng.html | 152 ++++++++- man/v0.2.0/nng_inproc.html | 5 +- man/v0.2.0/nng_ipc.html | 12 +- man/v0.2.0/nng_msg_alloc.html | 595 ++++++++++++++++++++++++++++++++ man/v0.2.0/nng_msg_append.html | 597 ++++++++++++++++++++++++++++++++ man/v0.2.0/nng_msg_body.html | 605 ++++++++++++++++++++++++++++++++ man/v0.2.0/nng_msg_chop.html | 599 ++++++++++++++++++++++++++++++++ man/v0.2.0/nng_msg_clear.html | 581 +++++++++++++++++++++++++++++++ man/v0.2.0/nng_msg_dup.html | 590 ++++++++++++++++++++++++++++++++ man/v0.2.0/nng_msg_free.html | 581 +++++++++++++++++++++++++++++++ man/v0.2.0/nng_msg_header.html | 616 +++++++++++++++++++++++++++++++++ man/v0.2.0/nng_msg_header_append.html | 597 ++++++++++++++++++++++++++++++++ man/v0.2.0/nng_msg_header_chop.html | 598 ++++++++++++++++++++++++++++++++ man/v0.2.0/nng_msg_header_clear.html | 581 +++++++++++++++++++++++++++++++ man/v0.2.0/nng_msg_header_insert.html | 598 ++++++++++++++++++++++++++++++++ man/v0.2.0/nng_msg_header_len.html | 581 +++++++++++++++++++++++++++++++ man/v0.2.0/nng_msg_header_trim.html | 598 ++++++++++++++++++++++++++++++++ man/v0.2.0/nng_msg_insert.html | 612 +++++++++++++++++++++++++++++++++ man/v0.2.0/nng_msg_len.html | 581 +++++++++++++++++++++++++++++++ man/v0.2.0/nng_msg_realloc.html | 626 ++++++++++++++++++++++++++++++++++ man/v0.2.0/nng_msg_trim.html | 599 ++++++++++++++++++++++++++++++++ man/v0.2.0/nng_strerror.html | 2 +- man/v0.2.0/nng_tls.html | 69 ++-- man/v0.2.0/nng_ws.html | 108 ++++-- man/v0.2.0/nng_zerotier.html | 24 +- 27 files changed, 11273 insertions(+), 116 deletions(-) create mode 100644 man/v0.2.0/nng_msg_alloc.html create mode 100644 man/v0.2.0/nng_msg_append.html create mode 100644 man/v0.2.0/nng_msg_body.html create mode 100644 man/v0.2.0/nng_msg_chop.html create mode 100644 man/v0.2.0/nng_msg_clear.html create mode 100644 man/v0.2.0/nng_msg_dup.html create mode 100644 man/v0.2.0/nng_msg_free.html create mode 100644 man/v0.2.0/nng_msg_header.html create mode 100644 man/v0.2.0/nng_msg_header_append.html create mode 100644 man/v0.2.0/nng_msg_header_chop.html create mode 100644 man/v0.2.0/nng_msg_header_clear.html create mode 100644 man/v0.2.0/nng_msg_header_insert.html create mode 100644 man/v0.2.0/nng_msg_header_len.html create mode 100644 man/v0.2.0/nng_msg_header_trim.html create mode 100644 man/v0.2.0/nng_msg_insert.html create mode 100644 man/v0.2.0/nng_msg_len.html create mode 100644 man/v0.2.0/nng_msg_realloc.html create mode 100644 man/v0.2.0/nng_msg_trim.html diff --git a/man/v0.2.0/README.html b/man/v0.2.0/README.html index 9cf429c9..bd006bbb 100644 --- a/man/v0.2.0/README.html +++ b/man/v0.2.0/README.html @@ -428,6 +428,78 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b .hide-for-print{display:none!important} .show-for-print{display:inherit!important}} + +

diff --git a/man/v0.2.0/libnng.html b/man/v0.2.0/libnng.html index 6aa420fa..4906dac7 100644 --- a/man/v0.2.0/libnng.html +++ b/man/v0.2.0/libnng.html @@ -430,6 +430,77 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b .show-for-print{display:inherit!important}} + @@ -465,8 +536,8 @@ intended to solve common communication problems in distributed applications.

--++ @@ -495,8 +566,8 @@ intended to solve common communication problems in distributed applications.

--++ @@ -535,7 +606,7 @@ intended to solve common communication problems in distributed applications.

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. @@ -548,8 +619,8 @@ Most applications will only interact with the body.

--++ @@ -557,20 +628,32 @@ Most applications will only interact with the body.

+ + + + - + - - + + - - + + - - + + + + + + + + + + @@ -581,6 +664,10 @@ Most applications will only interact with the body.

+ + + + @@ -590,6 +677,59 @@ Most applications will only interact with the body.

allocate a message

nng_msg_append(3)

append to message body

nng_msg_body(3)

return the message body

return message body

nng_msg_free(3)

free a message

nng_msg_chop(3)

remove data from end of message body

nng_msg_header(3)

return the message header

nng_msg_clear(3)

clear message body

nng_msg_header_len(3)

return the message header length

nng_msg_len(3)

duplicate a message

nng_msg_free(3)

free a message

nng_msg_insert(3)

prepend to message body

nng_msg_len(3)

reallocate a message

nng_msg_trim(3)

remove data from start of message body

nng_recvmsg(3)

receive a message

Message Header Handling

+ + + + + +

+ +	+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(3)

return message header

nng_msg_header_append(3)

append to message header

nng_msg_header_chop(3)

remove data from end of message header

nng_msg_header_clear(3)

clear message header

nng_msg_header_insert(3)

prepend to message header

nng_msg_header_len(3)

return the message header length

nng_msg_header_trim(3)

remove data from start of message header

Asynchronous Operations

@@ -630,8 +770,8 @@ be associated with an aio at any time.

--++ @@ -689,8 +829,8 @@ protocol:

--++ @@ -735,8 +875,8 @@ protocol:

--++ @@ -773,12 +913,26 @@ protocol:

TLS Configuration Objects

The following functions are used to manipulate TLS configuration objects.

The following functions are used to manipulate transport layer security +(TLS) configuration objects.

+ + + + +

+ +	+These functions will only be present if the library has been built +with TLS support. +

--++ @@ -806,8 +960,12 @@ protocol:

- + + + + +

set own certificate and key

nng_tls_config_free(3)}free TLS configuration

nng_tls_config_free(3)

free TLS configuration

nng_tls_config_server_name(3)

set remote server name

diff --git a/man/v0.2.0/nng.html b/man/v0.2.0/nng.html index 45ed09e9..7c79274d 100644 --- a/man/v0.2.0/nng.html +++ b/man/v0.2.0/nng.html @@ -430,6 +430,77 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b .show-for-print{display:inherit!important}} + @@ -488,8 +559,11 @@ 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 website.

Protocols

+ +

Protocols

@@ -525,8 +599,10 @@ other languages please check the website.

Transports

@@ -550,8 +626,10 @@ other languages please check the website.

Conceptual Overview

nng presents a socket view of networking. The sockets are constructed using protocol-specific functions, as a given socket implements precisely @@ -600,13 +678,65 @@ then wait for it to disconnect before reconnecting.

all; the socket abstraction should provide all the functionality needed other than in a few specific circumstances.

API

URLs

The library API is documented at libnng(3).

The nng library uses universal resource locators (URLs) +following the format specified in +RFC 3986, +including some schemes that are unique +to SP. +The URLs used in nng are canonicalized as follows, mostly in +accordance with +RFC 3986 6.2.2:

+
The URL is parsed into scheme, userinfo, host, port, path, query and +fragment components. (Not all of these members are necessarily present.)
+
+
The scheme, hostname, and port if present, are converted to lower case.
+
+
Percent-encoded values for +unreserved characters +converted to their unencoded forms.
+
+
Additionally URL percent-encoded values for characters in the path +and with numeric values larger than 127 (i.e. not ASCII) are decoded.
+
+
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.
+
+
Path segments consisting of . and .. are resolved as per +RFC 3986 6.2.2.3.
+
+
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(3).

diff --git a/man/v0.2.0/nng_inproc.html b/man/v0.2.0/nng_inproc.html index 3007aca9..03d73d89 100644 --- a/man/v0.2.0/nng_inproc.html +++ b/man/v0.2.0/nng_inproc.html @@ -546,8 +546,7 @@ no extra steps to use it should be necessary.

URI Format

This transport uses URIs using the scheme inproc://, followed by -an arbitrary string of text, terminated by a NUL byte. The -entire URI must be less than NNG_MAXADDRLEN bytes long.

+an arbitrary string of text, terminated by a NUL byte.

diff --git a/man/v0.2.0/nng_ipc.html b/man/v0.2.0/nng_ipc.html index 07f3cc96..4f9247fd 100644 --- a/man/v0.2.0/nng_ipc.html +++ b/man/v0.2.0/nng_ipc.html @@ -544,7 +544,7 @@ no extra steps to use it should be necessary.

URI Format

This transport uses URIs using the scheme ipc://, followed by -a path name in the file system where the socket or named pipe +a an absolute path name in the file system where the socket or named pipe should be created.

@@ -556,17 +556,11 @@ should be created.

On Windows, all names are prefixed by \.\pipe\ and do not occupy the normal file system. On POSIX platforms, the path is -taken literally, and is relative to the current directory, unless -an extra leading / is provided. For example, ipc://myname refers -to the name myname in the current directory, whereas ipc:///tmp/myname -refers to myname located in /tmp. +taken literally, and is relative to the root directory.

The entire URI must be less than NNG_MAXADDRLEN bytes long.

Socket Address

diff --git a/man/v0.2.0/nng_msg_alloc.html b/man/v0.2.0/nng_msg_alloc.html new file mode 100644 index 00000000..65e64cdd --- /dev/null +++ b/man/v0.2.0/nng_msg_alloc.html @@ -0,0 +1,595 @@ +--- +version: 0.2.0 +layout: default +--- + + + + + + + + +nng_msg_alloc(3) + + + + + + + +

SYNOPSIS

#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.
+

COPYRIGHT

This document is supplied under the terms of the +MIT License.

+ + + diff --git a/man/v0.2.0/nng_msg_append.html b/man/v0.2.0/nng_msg_append.html new file mode 100644 index 00000000..0862358e --- /dev/null +++ b/man/v0.2.0/nng_msg_append.html @@ -0,0 +1,597 @@ +--- +version: 0.2.0 +layout: default +--- + + + + + + + + +nng_msg_append(3) + + + + + + + +

SYNOPSIS

#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.
+

COPYRIGHT

This document is supplied under the terms of the +MIT License.

+ + + diff --git a/man/v0.2.0/nng_msg_body.html b/man/v0.2.0/nng_msg_body.html new file mode 100644 index 00000000..2793e1ce --- /dev/null +++ b/man/v0.2.0/nng_msg_body.html @@ -0,0 +1,605 @@ +--- +version: 0.2.0 +layout: default +--- + + + + + + + + +nng_msg_body(3) + + + + + + + +

SYNOPSIS

#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.

+ + + + + +

+ +	+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(3), nng_msg_realloc(3), +any of the nng_msg_trim(3), +nng_msg_chop(3), nng_msg_append(3), +or nng_msg_insert(3) variants. +

RETURN VALUES

Pointer to start of message body.

ERRORS

None.

COPYRIGHT

This document is supplied under the terms of the +MIT License.

+ + + diff --git a/man/v0.2.0/nng_msg_chop.html b/man/v0.2.0/nng_msg_chop.html new file mode 100644 index 00000000..bbf698df --- /dev/null +++ b/man/v0.2.0/nng_msg_chop.html @@ -0,0 +1,599 @@ +--- +version: 0.2.0 +layout: default +--- + + + + + + + + +nng_msg_chop(3) + + + + + + + +

SYNOPSIS

#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.
+

COPYRIGHT

This document is supplied under the terms of the +MIT License.

+ + + diff --git a/man/v0.2.0/nng_msg_clear.html b/man/v0.2.0/nng_msg_clear.html new file mode 100644 index 00000000..6e7e9622 --- /dev/null +++ b/man/v0.2.0/nng_msg_clear.html @@ -0,0 +1,581 @@ +--- +version: 0.2.0 +layout: default +--- + + + + + + + + +nng_msg_clear(3) + + + + + + + +

SYNOPSIS

#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.

COPYRIGHT

This document is supplied under the terms of the +MIT License.

+ + + diff --git a/man/v0.2.0/nng_msg_dup.html b/man/v0.2.0/nng_msg_dup.html new file mode 100644 index 00000000..05ac0033 --- /dev/null +++ b/man/v0.2.0/nng_msg_dup.html @@ -0,0 +1,590 @@ +--- +version: 0.2.0 +layout: default +--- + + + + + + + + +nng_msg_dup(3) + + + + + + + +

SYNOPSIS

#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.
+

COPYRIGHT

This document is supplied under the terms of the +MIT License.

+ + + diff --git a/man/v0.2.0/nng_msg_free.html b/man/v0.2.0/nng_msg_free.html new file mode 100644 index 00000000..69321405 --- /dev/null +++ b/man/v0.2.0/nng_msg_free.html @@ -0,0 +1,581 @@ +--- +version: 0.2.0 +layout: default +--- + + + + + + + + +nng_msg_free(3) + + + + + + + +

SYNOPSIS

#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.

COPYRIGHT

This document is supplied under the terms of the +MIT License.

+ + + diff --git a/man/v0.2.0/nng_msg_header.html b/man/v0.2.0/nng_msg_header.html new file mode 100644 index 00000000..b45731e7 --- /dev/null +++ b/man/v0.2.0/nng_msg_header.html @@ -0,0 +1,616 @@ +--- +version: 0.2.0 +layout: default +--- + + + + + + + + +nng_msg_header(3) + + + + + + + +

SYNOPSIS

#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.

+ + + + + +

+ +	+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(3) for more details.) +

+ + + + + +

+ +	+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.

COPYRIGHT

This document is supplied under the terms of the +MIT License.

+ + + diff --git a/man/v0.2.0/nng_msg_header_append.html b/man/v0.2.0/nng_msg_header_append.html new file mode 100644 index 00000000..372b6e1d --- /dev/null +++ b/man/v0.2.0/nng_msg_header_append.html @@ -0,0 +1,597 @@ +--- +version: 0.2.0 +layout: default +--- + + + + + + + + +nng_msg_header_append(3) + + + + + + + +

SYNOPSIS

#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.
+

COPYRIGHT

This document is supplied under the terms of the +MIT License.

+ + + diff --git a/man/v0.2.0/nng_msg_header_chop.html b/man/v0.2.0/nng_msg_header_chop.html new file mode 100644 index 00000000..7c157c34 --- /dev/null +++ b/man/v0.2.0/nng_msg_header_chop.html @@ -0,0 +1,598 @@ +--- +version: 0.2.0 +layout: default +--- + + + + + + + + +nng_msg_header_chop(3) + + + + + + + +

SYNOPSIS

#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.
+

COPYRIGHT

This document is supplied under the terms of the +MIT License.

+ + + diff --git a/man/v0.2.0/nng_msg_header_clear.html b/man/v0.2.0/nng_msg_header_clear.html new file mode 100644 index 00000000..44ca5aec --- /dev/null +++ b/man/v0.2.0/nng_msg_header_clear.html @@ -0,0 +1,581 @@ +--- +version: 0.2.0 +layout: default +--- + + + + + + + + +nng_msg_header_clear(3) + + + + + + + +

SYNOPSIS

#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.

COPYRIGHT

This document is supplied under the terms of the +MIT License.

+ + + diff --git a/man/v0.2.0/nng_msg_header_insert.html b/man/v0.2.0/nng_msg_header_insert.html new file mode 100644 index 00000000..f9cddfd8 --- /dev/null +++ b/man/v0.2.0/nng_msg_header_insert.html @@ -0,0 +1,598 @@ +--- +version: 0.2.0 +layout: default +--- + + + + + + + + +nng_msg_header_insert(3) + + + + + + + +

SYNOPSIS

#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.
+

COPYRIGHT

This document is supplied under the terms of the +MIT License.

+ + + diff --git a/man/v0.2.0/nng_msg_header_len.html b/man/v0.2.0/nng_msg_header_len.html new file mode 100644 index 00000000..b2bf29c4 --- /dev/null +++ b/man/v0.2.0/nng_msg_header_len.html @@ -0,0 +1,581 @@ +--- +version: 0.2.0 +layout: default +--- + + + + + + + + +nng_msg_header_len(3) + + + + + + + +

SYNOPSIS

#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.

COPYRIGHT

This document is supplied under the terms of the +MIT License.

+ + + diff --git a/man/v0.2.0/nng_msg_header_trim.html b/man/v0.2.0/nng_msg_header_trim.html new file mode 100644 index 00000000..aaaaca7f --- /dev/null +++ b/man/v0.2.0/nng_msg_header_trim.html @@ -0,0 +1,598 @@ +--- +version: 0.2.0 +layout: default +--- + + + + + + + + +nng_msg_header_trim(3) + + + + + + + +

SYNOPSIS

#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.
+

COPYRIGHT

This document is supplied under the terms of the +MIT License.

+ + + diff --git a/man/v0.2.0/nng_msg_insert.html b/man/v0.2.0/nng_msg_insert.html new file mode 100644 index 00000000..fda67b54 --- /dev/null +++ b/man/v0.2.0/nng_msg_insert.html @@ -0,0 +1,612 @@ +--- +version: 0.2.0 +layout: default +--- + + + + + + + + +nng_msg_insert(3) + + + + + + + +

SYNOPSIS

#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).

+ + + + + +

+ +	+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.
+

COPYRIGHT

This document is supplied under the terms of the +MIT License.

+ + + diff --git a/man/v0.2.0/nng_msg_len.html b/man/v0.2.0/nng_msg_len.html new file mode 100644 index 00000000..4572aae2 --- /dev/null +++ b/man/v0.2.0/nng_msg_len.html @@ -0,0 +1,581 @@ +--- +version: 0.2.0 +layout: default +--- + + + + + + + + +nng_msg_len(3) + + + + + + + +

SYNOPSIS

#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.

COPYRIGHT

This document is supplied under the terms of the +MIT License.

+ + + diff --git a/man/v0.2.0/nng_msg_realloc.html b/man/v0.2.0/nng_msg_realloc.html new file mode 100644 index 00000000..c7eda897 --- /dev/null +++ b/man/v0.2.0/nng_msg_realloc.html @@ -0,0 +1,626 @@ +--- +version: 0.2.0 +layout: default +--- + + + + + + + + +nng_msg_alloc(3) + + + + + + + +

SYNOPSIS

#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.

+ + + + + +

+ +

+One way to further reduce message allocations is to allocate a message +larger than needed, then use this function or 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(3) +no actual memory allocations need to take place. +

+ + + + + +

+ +	+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.
+

COPYRIGHT

This document is supplied under the terms of the +MIT License.

+ + + diff --git a/man/v0.2.0/nng_msg_trim.html b/man/v0.2.0/nng_msg_trim.html new file mode 100644 index 00000000..89f15ae4 --- /dev/null +++ b/man/v0.2.0/nng_msg_trim.html @@ -0,0 +1,599 @@ +--- +version: 0.2.0 +layout: default +--- + + + + + + + + +nng_msg_trim(3) + + + + + + + +

SYNOPSIS

#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.
+

COPYRIGHT

This document is supplied under the terms of the +MIT License.

+ + + diff --git a/man/v0.2.0/nng_strerror.html b/man/v0.2.0/nng_strerror.html index 8e9b5913..bce94770 100644 --- a/man/v0.2.0/nng_strerror.html +++ b/man/v0.2.0/nng_strerror.html @@ -595,7 +595,7 @@ Copyright 2018 Capitar IT Group BV

diff --git a/man/v0.2.0/nng_tls.html b/man/v0.2.0/nng_tls.html index be9d8854..5ab0b419 100644 --- a/man/v0.2.0/nng_tls.html +++ b/man/v0.2.0/nng_tls.html @@ -709,16 +709,6 @@ network byte order (most significant byte is first).

X.509 Formats

The tls transport supports certificates and key material provided -in either PEM or DER encoding. When using PEM format data, the -encoding must be at the start of the data, with no intervening -content. Furthermore, PEM encoded objects may have a terminating -NUL byte, which will be ignored if present.

Transport Options

The following transport options are available. Note that @@ -728,29 +718,54 @@ setting these must be done before the transport is started.

NNG_OPT_TLS_CONFIG

This option is used to set or obtain the TLS configuration -object (type nng_tls_config *), which is passed as a pointer. -Setting this option adds a reference to the object; obtaining the -object pointer does not. (Therefore when retrieving this option, -care must be taken not to access it after the endpoint is closed.)

This option is used on an endpoint to access the underlying TLS +configuration object. The value is of type nng_tls_config *.

Note that configuration object is not modifiable once it has been -used in a running TLS stream.

+ + + + + +

+ +	+Use this option when advanced TLS configuration is required. +

NNG_OPT_TLS_AUTH_VERIFIED

NNG_OPT_TLS_CA_FILE

This is a write-only option used to load certificates associated +associated private key from a file. +See nng_tls_config_ca_file(3) for more +information.

NNG_OPT_TLS_CERT_KEY_FILE

This is a write-only option used to load the local certificate and +associated private key from a file. The private key used must be +unencrypted. (Use the NNG_OPT_TLS_CONFIG option to access the underlying +TLS configuration if more advanced configuration is needed.) +See nng_tls_config_own_cert(3) for more +information.

NNG_OPT_TLS_AUTH_MODE

This is a write-only option used to configure the authentication mode +used. It can take an integer with value NNG_TLS_AUTH_MODE_NONE, +NNG_TLS_AUTH_MODE_REQUIRED, or NNG_TLS_AUTH_MODE_OPTIONAL. See +nng_tls_config_auth_mode(3) for more details.

NNG_OPT_TLS_VERIFIED

This is a read-only boolean option available only for -pipes, indicating whether the peer certificate was -valdiated or not. This is only set when the pipe -has completed the handshake with the peer (which always -occurs before exchanging data), and will only be set -if the NNG_OPT_TLS_AUTH_MODE option is set to -nng_tls_auth_mode_optional or nng_tls_auth_mode_required.

This is a read-only option which returns a boolean value (integer 0 or 1). +It will true (1) if the remote peer has been properly verified using TLS +authentication, or false (0) otherwise. This option may return incorrect +results if peer authentication is disabled with NNG_TLS_AUTH_MODE_NONE.

diff --git a/man/v0.2.0/nng_ws.html b/man/v0.2.0/nng_ws.html index c0a2d72b..dfca9505 100644 --- a/man/v0.2.0/nng_ws.html +++ b/man/v0.2.0/nng_ws.html @@ -665,11 +665,49 @@ network byte order (most significant byte is first).

Server Instances

This transport makes use of shared HTTP server instances, permitting multiple +sockets or listeners to be configured with the same hostname and port. When +creating a new listener, it is registered with an existing HTTP server instance +if one can be found. Note that the matching algorithm is somewhat simple, +using only a string based hostname or IP address and port to match. Therefore +it is recommended to use only IP addresses or the empty string as the hostname +in listener URLs.

Likewise, when sharing a server instance, it may not be possible to alter +TLS configuration if the server is already running, as there is only a single +TLS configuration context for the entire server instance.

All sharing of server instances is only typically possible within the same +process.

The server may also be used by other things (for example to serve static +content), in the same process.

Transport Options

The following transport options are available. Note that setting these must be done before the transport is started.

+ + + + + +

+ +	+The TLS specific options (beginning with `NNG_OPT_TLS_`) are +only available for `wss://` endpoints. +

NNG_OPT_WS_REQUEST_HEADERS

NNG_OPT_WSS_TLS_CONFIG

NNG_OPT_TLS_CONFIG

This option is used on an endpoint to access the underlying TLS -configuration object. The value is of type nng_tls_config *. -Note that attempts to set this object may fail on a listener if -the server is already running. Furthermore, attempts to modify the -configuration object will fail if it is already in active use. -This object is only available for wss:// endpoints.

+configuration object. The value is of type nng_tls_config *.

NNG_OPT_WSS_TLS_CA_FILE

+ + + + + +

+ +	+Use this option when advanced TLS configuration is required. +

NNG_OPT_TLS_CA_FILE

This is a write-only option used to load certificates associated -associated private key from a file. The value is a C string -containing the path name of the file. The file itself must contain -PEM format objects for one or more -X.509 certificates. It may also contain certificate revocation list (CRL) -objects well. Note that attempts to call this will fail if the -configuration associated with the underlying endpoint -is already in use. This option is only available for wss:// endpoints.

+associated private key from a file. +See nng_tls_config_ca_file(3) for more +information.

NNG_OPT_WSS_TLS_CERT_KEY_FILE

NNG_OPT_TLS_CERT_KEY_FILE

This is a write-only option used to load the local certificate and -associated private key from a file. The value is a C string -containing the path name of the file. The file itself must contain PEM -format objects for the X.509 certificate and private key. Multiple -certificates may be listed in the file, to provide a validation chain, -with the leaf certificate listed first, and subsequent certificates listed -afterwards. Note that attempts to call this will fail if the -configuration associated with the underlying endpoint -is already in use. This option is only available for wss:// endpoints. -The private key must not be encrypted. (Use the NNG_OPT_WSS_TLS_CONFIG -option to get the underlying TLS configuration if more advanced -configuration is needed.)

+associated private key from a file. The private key used must be +unencrypted. (Use the NNG_OPT_TLS_CONFIG option to access the underlying +TLS configuration if more advanced configuration is needed.) +See nng_tls_config_own_cert(3) for more +information.

NNG_OPT_TLS_AUTH_MODE

NNG_OPT_TLS_VERIFIED

diff --git a/man/v0.2.0/nng_zerotier.html b/man/v0.2.0/nng_zerotier.html index dac67f8c..a33d9032 100644 --- a/man/v0.2.0/nng_zerotier.html +++ b/man/v0.2.0/nng_zerotier.html @@ -595,21 +595,21 @@ cannot be initialized for any reason.

URI Format

This transport uses URIs using the scheme zt://, followed by a network -address (sixteen hexadecimal digits), followed by a / delimiter, -followed by the node number (ten hexadecimal digits) of the listening -node, followed by a service or port number (decimal value, up to 24-bits). -For example, the URI zt://0123456789abdef/fedcba9876:999 indicates -that node fedcba9876 on network 0123456789abcdef listening on port 999.

This transport uses URIs using the scheme zt://, followed by a node +number (ten hexadecimal digits) followed by a . delimited, and then +a network address (sixteen hexadecimal digits), followed by a colon (.) +and service or port number (decimal value, up to 24-bits). +For example, the URI zt://fedcba9876.0123456789abdef:999 indicates +that node fedcba9876 on network 0123456789abcdef is listening on port 999.

Listening nodes may use port 0, or *, to indicate that a suitable port -number be selected automatically. Applications using this must get the -selected port address using the nng_listener_getopt function.

The special value * can be used in lieu of a node number to represent +the node’s own node number.

Listening nodes may also elide their own node number, as well as the -delimiter separating the node number.

Listeners may use port 0 to indicate that a suitable port +number be selected automatically. Applications using this must determine the +selected port number using the nng_listener_getopt function.

-- cgit v1.2.3-70-g09d2

SYNOPSIS

Message Functions

Message Handling Functions

Message Header Handling

Asynchronous Operations

TLS Configuration Objects

SYNOPSIS

Protocols

Protocols

Transports

Transports

Conceptual Overview

Conceptual Overview

API

URLs

API

URI Format

URI Format

Socket Address

nng_msg_alloc(3) Manual Page

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

ERRORS

SEE ALSO

COPYRIGHT

nng_msg_append(3) Manual Page

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

ERRORS

SEE ALSO

COPYRIGHT

nng_msg_body(3) Manual Page

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

ERRORS

SEE ALSO

COPYRIGHT

nng_msg_chop(3) Manual Page

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

ERRORS

SEE ALSO

COPYRIGHT

nng_msg_clear(3) Manual Page

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

ERRORS

SEE ALSO

COPYRIGHT

nng_msg_dup(3) Manual Page

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

ERRORS

SEE ALSO

COPYRIGHT

nng_msg_free(3) Manual Page

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

ERRORS

SEE ALSO

COPYRIGHT

nng_msg_header(3) Manual Page

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES