From 3db63c95b3b5cc8853fa6a3a19afe34a8ba20dd2 Mon Sep 17 00:00:00 2001 From: gdamore Date: Thu, 9 Oct 2025 00:01:13 +0000 Subject: deploy: d006acfdd44af4210e39f571fa32314bcd36bb40 --- ref/api/aio.html | 75 ++-- ref/api/args.html | 7 +- ref/api/ctx.html | 69 +-- ref/api/errors.html | 17 +- ref/api/http.html | 245 +++++----- ref/api/id_map.html | 19 +- ref/api/init.html | 11 +- ref/api/memory.html | 21 +- ref/api/misc.html | 7 +- ref/api/msg.html | 25 +- ref/api/pipe.html | 23 +- ref/api/sock.html | 129 +++--- ref/api/stats.html | 41 +- ref/api/stream.html | 67 +-- ref/api/synch.html | 35 +- ref/api/thread.html | 13 +- ref/api/time.html | 17 +- ref/api/url.html | 13 +- ref/migrate/nanomsg.html | 113 ++--- ref/migrate/nng1.html | 95 ++-- ref/print.html | 1116 +++++++++++++++++++++++++--------------------- ref/searchindex.js | 2 +- ref/tran/inproc.html | 7 +- ref/tran/ipc.html | 25 +- ref/tran/socket.html | 21 +- ref/tran/udp.html | 21 +- 26 files changed, 1237 insertions(+), 997 deletions(-) (limited to 'ref') diff --git a/ref/api/aio.html b/ref/api/aio.html index 5219033f..e171e0d4 100644 --- a/ref/api/aio.html +++ b/ref/api/aio.html @@ -247,7 +247,7 @@

In order to obtain significant scalability, with low-latency, and minimal overheads, NNG supports performing operations asynchronously.

One way that applications can perform work asynchronously and concurrently -is by using threads, but threads carry significant resource overheads +is by using threads, but threads carry significant resource overheads and frequently there are limits on the number that can easily be created.

Additionally, with most network applications, the flow of execution will spend the bulk of its time waiting for traffic from a peer.

@@ -272,17 +272,17 @@ can only be used with a single operation at a time.

Instead the application registers a callback function to be executed when the operation is complete (whether successfully or not). This callback will be executed exactly once.

-

The asynchronous I/O framework also supports cancellation of +

The asynchronous I/O framework also supports cancellation of operations that are already in progress as well setting a maximum -timeout for them to complete.

-

It is also possible to initiate an asynchronous operation, and wait for it to +timeout for them to complete.

+

It is also possible to initiate an asynchronous operation, and wait for it to complete, creating a synchronous flow from an asynchronous one.

Create Handle

nng_err nng_aio_alloc(nng_aio **aiop, void (*callb)(void *), void *arg);
-

The nng_aio_alloc function creates an nng_aio object, with the +

The nng_aio_alloc function creates an nng_aio object, with the callback callb taking the argument arg, and returns it in aiop.

-

If this succeeds, the function returns zero. Otherwise it may return NNG_ENOMEM.

+

If this succeeds, the function returns zero. Otherwise it may return NNG_ENOMEM.

@@ -290,15 +290,15 @@ complete, creating a synchronous flow from an asynchronous one.

The arg should normally be a structure that contains a pointer to the aiop, or from which it can be located. This allows callb to check the handle for -success using nng_aio_result, as well access other properties of aiop.

+success using nng_aio_result, as well access other properties of aiop.

tip

-

The callb may be executed on another thread, so it may be necessary to use -synchronization methods in callb to avoid data races.

+

The callb may be executed on another thread, so it may be necessary to use +synchronization methods in callb to avoid data races.

Destroy Handle

void nng_aio_free(nng_aio *aio);
@@ -307,7 +307,7 @@ void nng_aio_reap(nng_aio *aio);
 
The nng_aio_free handle destroys the handle aio, waiting for any operations
 and associated callbacks to complete before doing so.

 
The nng_aio_reap handle destroys the handle aio asynchronously, using a reaper
-thread to do so. It does not wait for the object to be destroyed. Thus this function
+thread to do so. It does not wait for the object to be destroyed. Thus this function
 is safe to call from aio’s own callback.

 

 

@@ -330,13 +330,13 @@ If the operation is successfully canceled or aborted, then the callback
 will still be called.

 
The nng_aio_abort function aborts the operation associated with aio
 and returns immediately without waiting. If cancellation was successful,
-then nng_aio_result will return err.

+then nng_aio_result will return err.

 
The nng_aio_cancel function acts like nng_aio_abort, but uses the error code
-NNG_ECANCELED.

-
The nng_aio_stop function aborts the aio operation with NNG_ESTOPPED,
+NNG_ECANCELED.

+
The nng_aio_stop function aborts the aio operation with NNG_ESTOPPED,
 and then waits the operation and any associated callback to complete.
 This function also marks aio itself permanently stopped, so that any
-new operations scheduled by I/O providers using nng_aio_start
+new operations scheduled by I/O providers using nng_aio_start
 return false. Thus this function should be used to teardown operations.

 

 

@@ -345,7 +345,7 @@ return false. Thus this function should be used to teardown operations.

 

 
When multiple asynchronous I/O handles are in use and need to be
 deallocated, it is safest to stop all of them using nng_aio_stop,
-before deallocating any of them with nng_aio_free,
+before deallocating any of them with nng_aio_free,
 particularly if the callbacks might attempt to reschedule further operations.

 

 
Set Timeout

@@ -356,15 +356,15 @@ void nng_aio_set_expire(nng_aio *aio, nng_time expiration);
 for the asynchronous operation associated with aio.
 This causes a timer to be started when the operation is actually started.
 If the timer expires before the operation is completed, then it is
-aborted with an error of NNG_ETIMEDOUT.
-The timeout duration is specified as a relative number of milliseconds.

-
If the timeout is NNG_DURATION_INFINITE, then no timeout is used.
-If the timeout is NNG_DURATION_DEFAULT, then a “default” or socket-specific
+aborted with an error of NNG_ETIMEDOUT.
+The timeout duration is specified as a relative number of milliseconds.

+
If the timeout is NNG_DURATION_INFINITE, then no timeout is used.
+If the timeout is NNG_DURATION_DEFAULT, then a “default” or socket-specific
 timeout is used.
-(This is frequently the same as NNG_DURATION_INFINITE.)

+(This is frequently the same as NNG_DURATION_INFINITE.)

 
The nng_aio_set_expire function is similar to nng_aio_set_timeout, but sets
 an expiration time based on the system clock. The expiration
-time is a clock timestamp, such as would be returned by nng_clock.

+time is a clock timestamp, such as would be returned by nng_clock.

 
Wait for Completion

 
void nng_aio_wait(nng_aio *aio);
 

@@ -378,7 +378,7 @@ function will not be called until the callback has completed.

   important
 

 
The nng_aio_wait function should never be called from a function that itself
-is a callback of an nng_aio, either this one or any other.
+is a callback of an nng_aio, either this one or any other.
 Doing so may result in a deadlock.

 

 
Test for Completion

@@ -386,7 +386,7 @@ Doing so may result in a deadlock.

The nng_aio_busy function returns true if the aio is currently busy performing an operation or is executing a completion callback. Otherwise it return false. -This is the same test used internally by nng_aio_wait.

+This is the same test used internally by nng_aio_wait.

@@ -402,7 +402,7 @@ size_t nng_aio_count(nng_aio *aio);

The nng_aio_result function returns the result of the operation associated with the handle aio. If the operation was successful, then 0 is returned. -Otherwise a non-zero error code, such as NNG_ECANCELED or NNG_ETIMEDOUT, is returned.

+Otherwise a non-zero error code, such as NNG_ECANCELED or NNG_ETIMEDOUT, is returned.

For operations that transfer data, nng_aio_count returns the number of bytes transferred by the operation associated with the handle aio. Operations that do not transfer data, or do not keep a count, may return zero for this function.

@@ -413,13 +413,13 @@ Operations that do not transfer data, or do not keep a count, may return zero fo

The return value from these functions is undefined if the operation has not completed yet. Either call these from the handle’s completion callback, or after waiting for the -operation to complete with nng_aio_wait.

+operation to complete with nng_aio_wait.

Messages

nng_msg *nng_aio_get_msg(nng_aio *aio);
 void nng_aio_set_msg(nng_aio *aio, nng_msg *msg);
-

The nng_aio_get_msg and nng_aio_set_msg functions retrieve and store a message +

The nng_aio_get_msg and nng_aio_set_msg functions retrieve and store a message in aio. For example, if a function to receive data is called, that function can generally be expected to store a message on the associated aio, for the application to retrieve with @@ -445,7 +445,7 @@ then no message is stored on the aio.

int nng_aio_set_iov(nng_aio *aio, unsigned int niov, nng_iov *iov); -

For some operations, the unit of data transferred is not a message, but +

For some operations, the unit of data transferred is not a message, but rather a stream of bytes.

For these operations, an array of niov nng_iov structures can be passed to the nng_aio_set_iov function to provide a scatter/gather array of @@ -462,14 +462,14 @@ The values pointed to by the iov_buf members are not copie

Most functions using nng_iov do not guarantee to transfer all of the data that they are requested to. To be sure that correct amount of data is transferred, as well as to start an attempt to complete any partial transfer, check the amount of data transferred by -calling nng_aio_count.

+calling nng_aio_count.

Inputs and Outputs

void nng_aio_set_input(nng_aio *aio, unsigned int index, void *param);
 void *nng_aio_get_output(nng_aio *aio, unsigned int index);

Asynchronous operations can take additional input parameters, and -provide additional result outputs besides the result code.

+provide additional result outputs besides the result code.

The nng_aio_set_input function sets the input parameter at index to param for the operation associated with aio.

The nng_aio_get_output function returns the output result at index @@ -505,7 +505,7 @@ in use by an active asynchronous operation.

void nng_aio_set_iov(nng_aio *aio, unsigned nio, const nng_iov *iov);

-Some asynchronous operations, such as those dealing with streams, use scatter or gather +Some asynchronous operations, such as those dealing with streams, use scatter or gather vectors, where data to be transferred is either gathered from multiple separate regions of memory, or scattered into separate regions of memory. For example a message may have a header located at one location in memory, and a payload located in another.

@@ -515,16 +515,21 @@ the elements in iov. For each of these, the segment of size iov_len on the stack or another temporary location. The locations referenced by it, must remain valid for the duration of the operation, of course.

Note that many of these operations are not guaranteed to perform a full transfer of data, so even a -successful operation should check the amount of data actually transferred using nng_aio_count, +successful operation should check the amount of data actually transferred using nng_aio_count, and if necessary resubmit the operation with a suitably updated vector of nng_iov using this function.

See Also

-

Synchronization, -Threads, -Streams, -Time

+

Synchronization, +Threads, +Streams, +Time

+ + diff --git a/ref/api/args.html b/ref/api/args.html index c3aff98f..addb05b2 100644 --- a/ref/api/args.html +++ b/ref/api/args.html @@ -254,7 +254,7 @@ and for this purpose a header library is supplied.

The functionality described here is entirely contained in the nng/args.h header file, and may be used without previously -initializing the library with nng_init, and may even be used +initializing the library with nng_init, and may even be used in programs that are not linked against the NNG library.

Parse Command Line Arguments

@@ -415,9 +415,14 @@ unambiguously (meaning it must not match any other option specification.)

exit(1); } + + diff --git a/ref/api/ctx.html b/ref/api/ctx.html index 11e8e8aa..0aa22a6e 100644 --- a/ref/api/ctx.html +++ b/ref/api/ctx.html @@ -246,33 +246,33 @@

Contexts

Contexts in Scalability Protocols provide for isolation of protocol-specific state machines and associated data, allowing multiple concurrent state machines (or transactions) -to coexist on a single socket.

-

For example, a REP server may wish to allow many requests to be serviced concurrently, +to coexist on a single socket.

+

For example, a REP server may wish to allow many requests to be serviced concurrently, even though some jobs may take significant time to process. Contexts provide for this ability.

Not all protocols have contexts, because many protocols simply have no state to manage. The following protocols support contexts:

For these protocols, the socket will also have a single, default, context that is used when performing send or receive operations on the socket directly.

Other protocols are stateless, at least with respect to message processing, and have no use for -contexts. For the same reason, raw mode sockets do not support contexts.

+contexts. For the same reason, raw mode sockets do not support contexts.

tip

-

Developers with experience with [libnanomsg] may be used to using raw sockets for concurrency. +

Developers with experience with [libnanomsg] may be used to using raw sockets for concurrency. Contexts provide a superior solution, as they are much easier to use, less error prone, and allow for easy control of the amount of concurrency used on any given socket.

One drawback of contexts is that they cannot be used with file descriptor polling using -nng_socket_get_recv_poll_fd or nng_socket_get_send_poll_fd.

+nng_socket_get_recv_poll_fd or nng_socket_get_send_poll_fd.

Context Structure

#define NNG_CTX_INITIALIZER // opaque value
 
@@ -285,15 +285,15 @@ to ensure that it cannot be confused with a valid open context.

 
Creating a Context

 
int nng_ctx_open(nng_ctx *ctxp, nng_socket s);
 

-
The nng_ctx_open function creates a separate context to be used with the socket s,
+
The nng_ctx_open function creates a separate context to be used with the socket s,
 and returns it at the location pointed by ctxp.

 
Context Identity

 
int nng_ctx_id(nng_ctx c);
 

 
The nng_ctx_id function returns a positive identifier for the context c if it is valid.
 Otherwise it returns -1.

-
A context is considered valid if it was ever opened with nng_ctx_open function.
-Contexts that are allocated on the stack or statically should be initialized with the macro NNG_CTX_INITIALIZER
+
A context is considered valid if it was ever opened with nng_ctx_open function.
+Contexts that are allocated on the stack or statically should be initialized with the macro NNG_CTX_INITIALIZER
 to ensure that they cannot be confused with a valid context before they are opened.

 
Closing a Context

 
int nng_ctx_close(nng_ctx ctx);
@@ -309,7 +309,7 @@ call is executed may also return with an NNG_ECLOSED result.

   
   note
 

-
Closing the socket associated with ctx using nng_socket_close also closes this context.

+
Closing the socket associated with ctx using nng_socket_close also closes this context.

 
 
Sending Messages

 
int nng_ctx_sendmsg(nng_ctx ctx, nng_msg *msg, int flags);
@@ -325,21 +325,21 @@ messages over the socket s. The differences in their behaviors are as f
 
The semantics of what sending a message means varies from protocol to
 protocol, so examination of the protocol documentation is encouraged.
 Additionally, some protocols may not support sending at all or may require other pre-conditions first.
-(For example, REP sockets cannot normally send data until they have first received a request,
-while SUB sockets can only receive data and never send it.)

+(For example, REP sockets cannot normally send data until they have first received a request,
+while SUB sockets can only receive data and never send it.)

 
 
nng_ctx_sendmsg

 
The nng_ctx_sendmsg function sends the msg over the context ctx.

 
If this function returns zero, then the socket will dispose of msg when the transmission is complete.
 If the function returns a non-zero status, then the call retains the responsibility for disposing of msg.

-
The flags can contain the value NNG_FLAG_NONBLOCK, indicating that the function should not wait if the socket
-cannot accept more data for sending. In such a case, it will return NNG_EAGAIN.

+
The flags can contain the value NNG_FLAG_NONBLOCK, indicating that the function should not wait if the socket
+cannot accept more data for sending. In such a case, it will return NNG_EAGAIN.

 
nng_ctx_send

-
The nng_ctx_send function sends a message asynchronously, using the nng_aio aio, over the context ctx.
-The message to send must have been set on aio using the nng_aio_set_msg function.

+
The nng_ctx_send function sends a message asynchronously, using the nng_aio aio, over the context ctx.
+The message to send must have been set on aio using the nng_aio_set_msg function.

 
If the operation completes successfully, then the context will have disposed of the message.
 However, if it fails, then callback of aio should arrange for a final disposition of the message.
-(The message can be retrieved from aio with nng_aio_get_msg.)

+(The message can be retrieved from aio with nng_aio_get_msg.)

 
Note that callback associated with aio may be called before the message is finally delivered to the recipient.
 For example, the message may be sitting in queue, or located in TCP buffers, or even in flight.

 

@@ -349,7 +349,7 @@ For example, the message may be sitting in queue, or located in TCP buffers, or
 

 
This is the preferred function to use for sending data on a context. While it does require a few extra
 steps on the part of the application, the lowest latencies and highest performance will be achieved by using
-this function instead of nng_ctx_sendmsg.

+this function instead of nng_ctx_sendmsg.

 

 
Receiving Messages

 
int nng_ctx_recvmsg(nng_ctx ctx, nng_msg **msgp, int flags);
@@ -365,15 +365,15 @@ messages over the context ctx. The differences in their behaviors are a
 
The semantics of what receiving a message means varies from protocol to
 protocol, so examination of the protocol documentation is encouraged.
 Additionally, some protocols may not support receiving at all or may require other pre-conditions first.
-(For example, REQ sockets cannot normally receive data until they have first sent a request.)

+(For example, REQ sockets cannot normally receive data until they have first sent a request.)

 
 
nng_recvmsg

-
The nng_ctx_recvmsg function receives a message and stores a pointer to the nng_msg for that message in msgp.

-
The flags can contain the value NNG_FLAG_NONBLOCK, indicating that the function should not wait if the socket
-has no messages available to receive. In such a case, it will return NNG_EAGAIN.

+
The nng_ctx_recvmsg function receives a message and stores a pointer to the nng_msg for that message in msgp.

+
The flags can contain the value NNG_FLAG_NONBLOCK, indicating that the function should not wait if the socket
+has no messages available to receive. In such a case, it will return NNG_EAGAIN.

 
nng_socket_recv

-
The nng_ctx_send function receives a message asynchronously, using the nng_aio aio, over the context ctx.
-On success, the received message can be retrieved from the aio using the nng_aio_get_msg function.

+
The nng_ctx_send function receives a message asynchronously, using the nng_aio aio, over the context ctx.
+On success, the received message can be retrieved from the aio using the nng_aio_get_msg function.

 

 

   
@@ -389,7 +389,7 @@ Failure to do so will leak the memory.

 

 
This is the preferred function to use for receiving data on a context. While it does require a few extra
 steps on the part of the application, the lowest latencies and highest performance will be achieved by using
-this function instead of nng_ctx_recvmsg.

+this function instead of nng_ctx_recvmsg.

 

 
Context Options

 
int nng_ctx_get_bool(nng_ctx ctx, const char *opt, bool *valp);
@@ -414,7 +414,7 @@ are available for contexts, whether they can be read or written, and the appropr
 
These examples show building blocks for a concurrent service based on contexts.

 
Example 1: Context Echo Server

 
The following program fragment demonstrates the use of contexts to implement
-a concurrent REP service that simply echos messages back
+a concurrent REP service that simply echos messages back
 to the sender.

 
struct echo_context {
     nng_ctx ctx;
@@ -452,8 +452,8 @@ echo(void *arg)
 

 
Example 2: Starting the Echo Service

 
Given the above fragment, the following example shows setting up the service.
-It assumes that the socket has already been
-created and any transports set up as well with functions such as nng_dial or nng_listen.

+It assumes that the socket has already been
+created and any transports set up as well with functions such as nng_dial or nng_listen.

 

 #define CONCURRENCY 1024
 
@@ -471,9 +471,14 @@ start_echo_service(nng_socket rep_socket)
     }
 }
 

+
 
 
 
+
 
 
 
diff --git a/ref/api/errors.html b/ref/api/errors.html
index 88aff196..ce682ab1 100644
--- a/ref/api/errors.html
+++ b/ref/api/errors.html
@@ -289,20 +289,20 @@ as in diagnostic messages or log entries.

 NNG_EBUSY4Resource busy.
 NNG_ETIMEDOUT5Timed out. The operation took longer than the allotted time.
 NNG_ECONNREFUSED6Connection refused. Usually indicates the wrong address or a server is running.
-NNG_ECLOSED7Object closed. Typically the socket is closed.
+NNG_ECLOSED7Object closed. Typically the socket is closed.
 NNG_EAGAIN8Try again. Typcally for a non-blocking operation that might succeed later.
 NNG_ENOTSUP9Not supported. Perhaps the protocol or transport is not supported, or the operation is not not supported with the transport or protocol.
-NNG_EADDRINUSE10Address in use. The network address is already used by another process. Most often this is seen for listeners.
+NNG_EADDRINUSE10Address in use. The network address is already used by another process. Most often this is seen for listeners.
 NNG_ESTATE11Incorrect state. The operation cannot be performed in the current state, such as trying to send a response when no request has yet been received.
 NNG_ENOENT12Entry not found (no such object.) Can also indicate that a file does not exist.
 NNG_EPROTO13Protocol error. Typically this indicates incorrect messages over a network.
 NNG_EUNREACHABLE14Destination unreachable.
-NNG_EADDRINVAL15Address invalid. Like NNG_EINVAL, but only for network addresses.
+NNG_EADDRINVAL15Address invalid. Like NNG_EINVAL, but only for network addresses.
 NNG_EPERM16Permission denied.
 NNG_EMSGSIZE17Message too large.
 NNG_ECONNABORTED18Connection aborted. A connection attempt was aborted locally.
 NNG_ECONNRESET19Connection reset. The remote peer reset the connection unexpectedly.
-NNG_ECANCELED20Operation canceled. Typically as a result of nng_aio_cancel or similar.
+NNG_ECANCELED20Operation canceled. Typically as a result of nng_aio_cancel or similar.
 NNG_ENOFILES21Out of files. Either the destination file system cannot store files, or all available file handles are used.
 NNG_ENOSPC22Out of space. Destination table or filesystem is full.
 NNG_EEXIST23Resource already exists.
@@ -312,14 +312,19 @@ as in diagnostic messages or log entries.

 NNG_EPEERAUTH27Peer could not be authenticated.
 NNG_EBADTYPE30Incorrect type. A type-specific function was used for an object of the wrong type.
 NNG_ECONNSHUT31Connection shutdown. The connection was shut down and cannot be used.
-NNG_ESTOPPED1000Operation stopped. The operation was stopped with nng_aio_stop or [nng_aio_close].
+NNG_ESTOPPED1000Operation stopped. The operation was stopped with nng_aio_stop or [nng_aio_close].
 NNG_EINTERNAL1000An unidentifier internal error occurred.
 NNG_ESYSERR0x10000000 - 0x1FFFFFFFAn unidentified system error occurred. These are errors reported by the operating system.
 NNG_ETRANERR0x20000000 - 0x2FFFFFFFAn unidentified transport error occurred.
 
-
+
+
 
 
+
 
 
 
diff --git a/ref/api/http.html b/ref/api/http.html
index 1d137541..b8db5c8c 100644
--- a/ref/api/http.html
+++ b/ref/api/http.html
@@ -265,8 +265,8 @@ request headers, response status, response headers, and so forth.

 performed after the first transaction is complete.

 
At any given point in time, an nng_http object can only refer to a single HTTP transaction.
 In NNG, these nng_http objects are used in both the client and server APIs.

-
The nng_http object is created by either nng_http_client_connect or by an HTTP server
-object which then passes it to an nng_http_handler callback function.

+
The nng_http object is created by either nng_http_client_connect or by an HTTP server
+object which then passes it to an nng_http_handler callback function.

 
HTTP Method

 
void nng_http_set_method(nng_http *conn, const char *method);
 const char *nng_http_get_method(nng_http *conn);
@@ -285,8 +285,8 @@ const char *nng_http_get_uri(nng_http *conn);
 
The nng_http_set_uri function sets the URI, which normally appears like a path such as “/docs/index.html”,
 for the next transaction on conn. It sets the URI to uri, and, if query is not NULL, also appends the
 contents of query, separated by either the ‘?’ or ‘&’ character, depending on whether uri already
-contains a query string. It may return NNG_ENOMEM, or NNG_EMSGSIZE if the the result is too long,
-or NNG_EINVAL if there is some other problem with the URI.

+contains a query string. It may return NNG_ENOMEM, or NNG_EMSGSIZE if the the result is too long,
+or NNG_EINVAL if there is some other problem with the URI.

 

 

   
@@ -304,7 +304,7 @@ const char *nng_http_get_version(nng_http *conn);
 
The nng_http_set_version function is used to select the HTTP protocol version to use for the
 exchange. At present, only the values NNG_HTTP_VERSION_1_0 and NNG_HTTP_VERSION_1_1 (corresponding to
 “HTTP/1.0” and “HTTP/1.1”) are supported. NNG will default to using “HTTP/1.1” if this function is not called.
-If an unsupported version is supplied, NNG_ENOTSUP will be returned, otherwise zero.

+If an unsupported version is supplied, NNG_ENOTSUP will be returned, otherwise zero.

 
The nng_http_get_version function is used to determine the version the client selected. Normally
 there is little need to use this, but there are some subtle semantic differences between HTTP/1.0 and HTTP/1.1.

 

@@ -340,72 +340,72 @@ then a built in reason based on the status will be used instead.

   
   tip
 

-
Callbacks used on the server may wish to use nng_http_server_set_error or nng_http_server_set_redirect instead of
+
Callbacks used on the server may wish to use nng_http_server_set_error or nng_http_server_set_redirect instead of
 nng_http_set_status, because those functions will also set the response body to a suitable HTML document
 for display to users.

 

 
Status codes are defined by the IETF. Here are definitions that NNG provides for convenience:

 

-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
NameCodeReason TextNotes
NNG_HTTP_STATUS_CONTINUE100ContinuePartial transfer, client may send body.
NNG_HTTP_STATUS_SWITCHING101Switching ProtocolsUsed when upgrading or hijacking a connection.
NNG_HTTP_STATUS_PROCESSING102Processing
NNG_HTTP_STATUS_OK200OKSuccessful result.
NNG_HTTP_STATUS_CREATED201CreatedResource created successfully.
NNG_HTTP_STATUS_ACCEPTED202CreatedRequest accepted for future processing.
NNG_HTTP_STATUS_NOT_AUTHORITATIVE203Not AuthoritativeRequest successful, but modified by proxy.
NNG_HTTP_STATUS_NO_CONTENT204No ContentRequest successful, no content returned.
NNG_HTTP_STATUS_RESET_CONTENT205Reset ContentRequest successful, client should reload content.
NNG_HTTP_STATUS_PARTIAL_CONTENT206Partial ContentResponse to a range request.
NNG_HTTP_STATUS_MULTI_STATUS207Multi-StatusUsed with WebDAV.
NNG_HTTP_STATUS_ALREADY_REPORTED208Already ReportedUsed with WebDAV.
NNG_HTTP_STATUS_IM_USED226IM UsedUsed with delta encodings, rarely supported.
NNG_HTTP_STATUS_MULTIPLE_CHOICES300Multiple ChoicesMultiple responses possible, client should choose.
NNG_HTTP_STATUS_MOVED_PERMANENTLY301Moved PermanentlyPermanent redirection, may be saved by client.
NNG_HTTP_STATUS_FOUND302FoundTemporary redirection, client may switch to GET.
NNG_HTTP_STATUS_SEE_OTHER303See OtherRedirect, perhaps after a success POST or PUT.
NNG_HTTP_STATUS_NOT_MODIFIED304Not ModifiedResource not modified, client may use cached version.
NNG_HTTP_STATUS_USE_PROXY305Use Proxy
NNG_HTTP_STATUS_TEMPORARY_REDIRECT307Temporary RedirectTemporary redirect, preserves method.
NNG_HTTP_STATUS_PERMANENT_REDIRECT308Permanent RedirectPermanent redirect.
NNG_HTTP_STATUS_BAD_REQUEST400Bad RequestGeneric problem with the request.
NNG_HTTP_STATUS_UNAUTHORIZED401UnauthorizedIndicates a problem with authentication.
NNG_HTTP_STATUS_PAYMENT_REQUIRED402Payment Required
NNG_HTTP_STATUS_FORBIDDEN403ForbiddenNo permission to access resource.
NNG_HTTP_STATUS_NOT_FOUND404Not FoundResource does not exist.
NNG_HTTP_STATUS_METHOD_NOT_ALLOWED405Method Not AllowedResource does not support the method.
NNG_HTTP_STATUS_METHOD_NOT_ACCEPTABLE406Not AcceptableCould not satisfy accept requirements.
NNG_HTTP_STATUS_PROXY_AUTH_REQUIRED407Proxy Authentication RequiredProxy requires authentication.
NNG_HTTP_STATUS_REQUEST_TIMEOUT408Request TimeoutTimed out waiting for request.
NNG_HTTP_STATUS_CONFLICT409ConflictConflicting request.
NNG_HTTP_STATUS_GONE410GoneResource no longer exists.
NNG_HTTP_STATUS_LENGTH_REQUIRED411Length RequiredMissing Content-Length.
NNG_HTTP_STATUS_PRECONDITION_FAILED412Precondition Failed
NNG_HTTP_STATUS_CONTENT_TOO_LARGE413Content Too Large
NNG_HTTP_STATUS_URI_TOO_LONG414URI Too Long
NNG_HTTP_STATUS_UNSUPPORTED_MEDIA_TYPE415Unsupported Media Type
NNG_HTTP_STATUS_RANGE_NOT_SATISFIABLE416Range Not Satisfiable
NNG_HTTP_STATUS_EXPECTATION_FAILED417Expectation Failed
NNG_HTTP_STATUS_TEAPOT418I Am A TeapotRFC 2324.
NNG_HTTP_STATUS_UNPROCESSABLE_ENTITY422Unprocessable Entity
NNG_HTTP_STATUS_LOCKED423Locked
NNG_HTTP_STATUS_FAILED_DEPENDENCY424Failed Dependency
NNG_HTTP_STATUS_TOO_EARLY425Too Early
NNG_HTTP_STATUS_UPGRADE_REQUIRED426Upgrade Required
NNG_HTTP_STATUS_PRECONDITION_REQUIRED428Precondition Required
NNG_HTTP_STATUS_TOO_MANY_REQUESTS429Too Many Requests
NNG_HTTP_STATUS_HEADERS_TOO_LARGE431Headers Too Large
NNG_HTTP_STATUS_UNAVAIL_LEGAL_REASONS451Unavailable For Legal Reasons
NNG_HTTP_STATUS_INTERNAL_SERVER_ERROR500Internal Server Error
NNG_HTTP_STATUS_NOT_IMPLEMENTED501Not ImplementedServer does not implement method.
NNG_HTTP_STATUS_BAD_GATEWAY502Bad Gateway
NNG_HTTP_STATUS_SERVICE_UNAVAILALE503Service Unavailable
NNG_HTTP_STATUS_GATEWAY_TIMEOUT504Gateway TImeout
NNG_HTTP_STATUS_HTTP_VERSION_NOT_SUPP505HTTP Version Not Supported
NNG_HTTP_STATUS_VARIANT_ALSO_NEGOTIATES506Variant Also Negotiates
NNG_HTTP_STATUS_INSUFFICIENT_STORAGE507Variant Also Negotiates
NNG_HTTP_STATUS_LOOP_DETECTED508Loop Detected
NNG_HTTP_STATUS_NOT_EXTENDED510Not Extended
NNG_HTTP_STATUS_NETWORK_AUTH_REQUIRED511Network Authentication Required
NNG_HTTP_STATUS_CONTINUE100ContinuePartial transfer, client may send body.
NNG_HTTP_STATUS_SWITCHING101Switching ProtocolsUsed when upgrading or hijacking a connection.
NNG_HTTP_STATUS_PROCESSING102Processing
NNG_HTTP_STATUS_OK200OKSuccessful result.
NNG_HTTP_STATUS_CREATED201CreatedResource created successfully.
NNG_HTTP_STATUS_ACCEPTED202CreatedRequest accepted for future processing.
NNG_HTTP_STATUS_NOT_AUTHORITATIVE203Not AuthoritativeRequest successful, but modified by proxy.
NNG_HTTP_STATUS_NO_CONTENT204No ContentRequest successful, no content returned.
NNG_HTTP_STATUS_RESET_CONTENT205Reset ContentRequest successful, client should reload content.
NNG_HTTP_STATUS_PARTIAL_CONTENT206Partial ContentResponse to a range request.
NNG_HTTP_STATUS_MULTI_STATUS207Multi-StatusUsed with WebDAV.
NNG_HTTP_STATUS_ALREADY_REPORTED208Already ReportedUsed with WebDAV.
NNG_HTTP_STATUS_IM_USED226IM UsedUsed with delta encodings, rarely supported.
NNG_HTTP_STATUS_MULTIPLE_CHOICES300Multiple ChoicesMultiple responses possible, client should choose.
NNG_HTTP_STATUS_MOVED_PERMANENTLY301Moved PermanentlyPermanent redirection, may be saved by client.
NNG_HTTP_STATUS_FOUND302FoundTemporary redirection, client may switch to GET.
NNG_HTTP_STATUS_SEE_OTHER303See OtherRedirect, perhaps after a success POST or PUT.
NNG_HTTP_STATUS_NOT_MODIFIED304Not ModifiedResource not modified, client may use cached version.
NNG_HTTP_STATUS_USE_PROXY305Use Proxy
NNG_HTTP_STATUS_TEMPORARY_REDIRECT307Temporary RedirectTemporary redirect, preserves method.
NNG_HTTP_STATUS_PERMANENT_REDIRECT308Permanent RedirectPermanent redirect.
NNG_HTTP_STATUS_BAD_REQUEST400Bad RequestGeneric problem with the request.
NNG_HTTP_STATUS_UNAUTHORIZED401UnauthorizedIndicates a problem with authentication.
NNG_HTTP_STATUS_PAYMENT_REQUIRED402Payment Required
NNG_HTTP_STATUS_FORBIDDEN403ForbiddenNo permission to access resource.
NNG_HTTP_STATUS_NOT_FOUND404Not FoundResource does not exist.
NNG_HTTP_STATUS_METHOD_NOT_ALLOWED405Method Not AllowedResource does not support the method.
NNG_HTTP_STATUS_METHOD_NOT_ACCEPTABLE406Not AcceptableCould not satisfy accept requirements.
NNG_HTTP_STATUS_PROXY_AUTH_REQUIRED407Proxy Authentication RequiredProxy requires authentication.
NNG_HTTP_STATUS_REQUEST_TIMEOUT408Request TimeoutTimed out waiting for request.
NNG_HTTP_STATUS_CONFLICT409ConflictConflicting request.
NNG_HTTP_STATUS_GONE410GoneResource no longer exists.
NNG_HTTP_STATUS_LENGTH_REQUIRED411Length RequiredMissing Content-Length.
NNG_HTTP_STATUS_PRECONDITION_FAILED412Precondition Failed
NNG_HTTP_STATUS_CONTENT_TOO_LARGE413Content Too Large
NNG_HTTP_STATUS_URI_TOO_LONG414URI Too Long
NNG_HTTP_STATUS_UNSUPPORTED_MEDIA_TYPE415Unsupported Media Type
NNG_HTTP_STATUS_RANGE_NOT_SATISFIABLE416Range Not Satisfiable
NNG_HTTP_STATUS_EXPECTATION_FAILED417Expectation Failed
NNG_HTTP_STATUS_TEAPOT418I Am A TeapotRFC 2324.
NNG_HTTP_STATUS_UNPROCESSABLE_ENTITY422Unprocessable Entity
NNG_HTTP_STATUS_LOCKED423Locked
NNG_HTTP_STATUS_FAILED_DEPENDENCY424Failed Dependency
NNG_HTTP_STATUS_TOO_EARLY425Too Early
NNG_HTTP_STATUS_UPGRADE_REQUIRED426Upgrade Required
NNG_HTTP_STATUS_PRECONDITION_REQUIRED428Precondition Required
NNG_HTTP_STATUS_TOO_MANY_REQUESTS429Too Many Requests
NNG_HTTP_STATUS_HEADERS_TOO_LARGE431Headers Too Large
NNG_HTTP_STATUS_UNAVAIL_LEGAL_REASONS451Unavailable For Legal Reasons
NNG_HTTP_STATUS_INTERNAL_SERVER_ERROR500Internal Server Error
NNG_HTTP_STATUS_NOT_IMPLEMENTED501Not ImplementedServer does not implement method.
NNG_HTTP_STATUS_BAD_GATEWAY502Bad Gateway
NNG_HTTP_STATUS_SERVICE_UNAVAILALE503Service Unavailable
NNG_HTTP_STATUS_GATEWAY_TIMEOUT504Gateway TImeout
NNG_HTTP_STATUS_HTTP_VERSION_NOT_SUPP505HTTP Version Not Supported
NNG_HTTP_STATUS_VARIANT_ALSO_NEGOTIATES506Variant Also Negotiates
NNG_HTTP_STATUS_INSUFFICIENT_STORAGE507Variant Also Negotiates
NNG_HTTP_STATUS_LOOP_DETECTED508Loop Detected
NNG_HTTP_STATUS_NOT_EXTENDED510Not Extended
NNG_HTTP_STATUS_NETWORK_AUTH_REQUIRED511Network Authentication Required

 

 

 
Retrieving Headers

@@ -432,11 +432,11 @@ void nng_http_del_header(nng_http *conn, const char *key);
 

 
The nng_http_add_header, nng_http_set_header, and nng_http_del_header functions are
 used to add a modify either the request or response headers for conn prior to sending to the connected peer on conn.

-
Thus, if the conn is a client connection created by nng_http_client_connect, then the request headers are modified.
+
Thus, if the conn is a client connection created by nng_http_client_connect, then the request headers are modified.
 Conversely, if it is a connection created by an HTTP server and used in a callback function, then the response headers are modified.

 
The nng_http_add_header function adds a header with the name key, and the value val, to the list of headers.
 In so doing, it may bring collapse multiple headers with the same name into a comma separated list, following
-the syntax specified in RFC 9110. The function may return NNG_ENOMEM, NNG_EMSGSIZE, or NNG_EINVAL.

+the syntax specified in RFC 9110. The function may return NNG_ENOMEM, NNG_EMSGSIZE, or NNG_EINVAL.

 
The nng_http_set_header function adds the header if it does not already exist, but replaces any and all previously existing
 headers with the same name key, if they exist. In all other respects it behaves similarly to nng_http_add_header.

 
The nng_http_del_header removes all headers with name key.

@@ -495,7 +495,7 @@ including any disposing of any underlying file descriptors or related resources.
 

 
The nng_http_reset function resets the request and response state of the
 the connection conn, so that it is just as if it had been freshly created with
-nng_http_client_connect or passed into a handler function for a server callback.

+nng_http_client_connect or passed into a handler function for a server callback.

 
The intended purpose of this function is to clear the object state before reusing the conn for
 subsequent transactions.

 
Direct Read and Write

@@ -505,11 +505,11 @@ void nng_http_read_all(nng_http *conn, nng_aio *aio);
 void nng_http_write_all(nng_http *conn, nng_aio *aio);
 

 
The nng_http_read and nng_http_write functions read or write data asynchronously from or to the
-connection conn, using the nng_iov that is set in aio with nng_aio_set_iov.
+connection conn, using the nng_iov that is set in aio with nng_aio_set_iov.
 These functions will complete as soon as any data is transferred.
-Use nng_aio_count to determine how much data was actually transferred.

+Use nng_aio_count to determine how much data was actually transferred.

 
The nng_http_read_all and nng_http_write_all functions perform the same task, but will keep resubmitting
-operations until the the entire amount of data requested by the nng_iov is transferred.

+operations until the the entire amount of data requested by the nng_iov is transferred.

 

 

   
@@ -517,7 +517,7 @@ operations until the the entire amount of data requested by the nng_http_hijack.
+
These functions are most likely to be useful after hijacking the connection with nng_http_hijack.
 They can be used to transfer request or response body data as well.

 
Hijacking Connections

 
nng_err nng_http_hijack(nng_http *conn);
@@ -529,7 +529,7 @@ to be disassociated from the HTTP server where it was created.

 WebSocket), where the underlying HTTP connection will be taken over for
 some other purpose, and should not be used any further by the server.

 
This function is most useful when called from a handler function.
-(See nng_http_handler_alloc.)

+(See nng_http_handler_alloc.)

 

 

   
@@ -537,7 +537,7 @@ some other purpose, and should not be used any further by the server.

 

 
It is the responsibility of the caller to dispose of the underlying connection when it is no longer needed.
 Furthermore, the HTTP server will no longer send any responses to the hijacked connection, so the caller should do that as well if appropriate.
-(See nng_http_write_response.)

+(See nng_http_write_response.)

 

 

 

@@ -554,7 +554,7 @@ Most applications will never need to use this function.

 
The nng_http_peer_cert function will obtain the TLS certificate object for the peer, if one is available.
 This can then be used for additional authentication or identity specific logic.

 
The certificate must be released with [nng_tls_cert_free] when no longer in use.
-See [nng_tls_cert] for more information about working with TLS certificates.

+See nng_tls_cert for more information about working with TLS certificates.

 

 

   
@@ -571,8 +571,8 @@ transactions on those connections.

 
Client Object

 
typedef struct nng_http_client nng_http_client;
 

-
The nng_http_client object is the client side creator for nng_http objects.
-It is analogous to a dialer object used elsewhere in NNG, but it specifically is only for HTTP.

+
The nng_http_client object is the client side creator for nng_http objects.
+It is analogous to a dialer object used elsewhere in NNG, but it specifically is only for HTTP.

 
Create a Client

 
void nng_http_client_alloc(nng_http_client *clientp, const nng_url *url);
 

@@ -589,7 +589,7 @@ of its resources.

   
   note
 

-
Any connections created by nng_http_client_connect are not affected by this function,
+
Any connections created by nng_http_client_connect are not affected by this function,
 and must be closed explicitly as needed.

 

 
Client TLS

@@ -597,10 +597,10 @@ and must be closed explicitly as needed.

 nng_err nng_http_client_set_tls(nng_http_client *client, nng_tls_config *tls);
 

 
The nng_http_client_get_tls and nng_http_client_set_tls functions are used to
-retrieve or change the TLS configuration used when making outbound connections, enabling
+retrieve or change the TLS configuration used when making outbound connections, enabling
 TLS as a result.

-
If TLS has not been previously configured on client, then nng_http_client_get_tls will return NNG_EINVAL.
-Both functions will return NNG_ENOTSUP if either HTTP or TLS is not supported.

+
If TLS has not been previously configured on client, then nng_http_client_get_tls will return NNG_EINVAL.
+Both functions will return NNG_ENOTSUP if either HTTP or TLS is not supported.

 
Calling nng_http_client_set_tls invalidates any client previously obtained with
 nng_http_client_get_tls, unless a separate hold on the object was obtained.

 
Once TLS is enabled for an nng_http_client, it is not possible to disable TLS.

@@ -610,7 +610,7 @@ Both functions will return NNG_ENOT
   note
 

 
The TLS configuration itself cannot be changed once it has been used to create a connection,
-such as by calling nng_http_client_connect, but a new one can be installed in the client.
+such as by calling nng_http_client_connect, but a new one can be installed in the client.
 Existing connections will use the TLS configuration that there were created with.

 

 
Creating Connections

@@ -619,9 +619,9 @@ Existing connections will use the TLS configuration that there were created with
 void nng_http_client_connect(nng_http_client *client, nng_aio *aio);
 

 
The nng_http_client_connect function makes an outgoing connection to the
-server configured for client, and creates an nng_http object for the connection.

+server configured for client, and creates an nng_http object for the connection.

 
This is done asynchronously, and when the operation succeseds the connection may be
-retried from the aio using nng_aio_get_output with index 0.

+retried from the aio using nng_aio_get_output with index 0.

 
Example 1: Connecting to Google

 
nng_aio *aio;
 nng_url *url;
@@ -660,16 +660,16 @@ the HTTP request associated with conn.
 The entire request is sent,
 including headers, and if present, the request body data.
 (The request body can be set with
-nng_http_set_body or nng_http_copy_body.)

+nng_http_set_body or nng_http_copy_body.)

 
This function returns immediately, with no return value.
 Completion of the operation is signaled via the aio, and the final result
-may be obtained via nng_aio_result.

+may be obtained via nng_aio_result.

 

 

   
   tip
 

-
Consider using the [nng_http_transact] function,
+
Consider using the nng_http_transact function,
 which provides a simpler interface for performing a complete HTTP client transaction.

 

 
Obtaining the Response

@@ -678,7 +678,7 @@ which provides a simpler interface for performing a complete HTTP client transac
 
The nng_http_read_response function starts an asynchronous read from the
 HTTP connection conn, reading an HTTP response into the response associated with conn, including all
 of the related headers.

-
It does not transfer any response body. To do that, use nng_http_read_all or nng_http_read.

+
It does not transfer any response body. To do that, use nng_http_read_all or nng_http_read.

 

 

   
@@ -692,7 +692,7 @@ need to do so may use the direct read functions.

   
   tip
 

-
An easier one-shot method for many use cases might be [nng_http_transact].

+
An easier one-shot method for many use cases might be nng_http_transact.

 

 
Submitting the Transaction

 
void nng_http_transact(nng_http *conn, nng_aio *aio);
@@ -703,11 +703,11 @@ When the function is complete, the aio will be notified.

 HTTP exchange over the connection conn, sending the request
 and attached body data to the remote server, and reading the response.

 
The entire response is read, including any associated body, which can
-subsequently be obtained using [nng_http_get_data].

+subsequently be obtained using nng_http_get_body.

 
This function is intended to make creation of client applications easier,
 by performing multiple asynchronous operations required to complete an
 entire HTTP transaction.

-
If an error occurs, the caller should close conn with nng_http_close, as it may not
+
If an error occurs, the caller should close conn with nng_http_close, as it may not
 necessarily be usable with other transactions.

 

 

@@ -731,7 +731,7 @@ request interleaving.

 

 
This function returns immediately, with no return value.
 Completion of the operation is signaled via the aio, and the final result
-may be obtained via [nng_aio_result()].

+may be obtained via nng_aio_result.

 
Response Body

 
Server API

 
Handlers

@@ -745,7 +745,7 @@ Only the path component of the Request URI is considered when determining whethe
 
This implementation limits the path length to 1024 bytes, including the
 zero termination byte. This does not prevent requests with much longer
 URIs from being supported, but doing so will require setting the handler to match a parent path in the tree using
-[nng_http_handler_set_tree].

+nng_http_handler_set_tree.

 

 

   
@@ -754,11 +754,11 @@ URIs from being supported, but doing so will require setting the handler to matc
 
The NNG HTTP framework is optimized for URLs shorter than 200 characters.

 

 
Additionally each handler has a method it is registered to handle
-(the default is “GET” andc can be changed with nng_http_handler_set_method), and
-optionally a “Host” header it can be matched against (see nng_http_handler_set_host).

+(the default is “GET” andc can be changed with nng_http_handler_set_method), and
+optionally a “Host” header it can be matched against (see nng_http_handler_set_host).

 
In some cases, a handler may reference a logical tree rather (directory)
 rather than just a single element.
-(See [nng_http_handler_set_tree]).

+(See nng_http_handler_set_tree).

 
Implementing a Handler

 
typedef void (*nng_http_handler_func)(nng_http_conn *conn, void *arg, nng_aio *aio);
 
@@ -770,30 +770,30 @@ On success, a pointer to the handler is stored at the located pointed to by 
 
The handler function is specified by cb.
 This function uses the asynchronous I/O framework.

 
The function receives the connection on conn, and an optional data pointer that was set
-previously with nng_http_handler_set_data as the second argument. The
-final argument is the nng_aio aio, which must be “finished” to complete the operation.

-
The handler may call nng_http_write_response to send the response, or
+previously with nng_http_handler_set_data as the second argument. The
+final argument is the nng_aio aio, which must be “finished” to complete the operation.

+
The handler may call nng_http_write_response to send the response, or
 it may simply let the framework do so on its behalf. The server will perform
 this step if the callback has not already done so.

-
Response headers may be set using nng_http_set_header, and request headers
-may be accessed by using nng_http_get_header. They can also be iterated
-over using nng_http_next_header

-
Likewise the request body may be accessed, using nng_http_get_body, and
-the response body may be set using either nng_http_set_body or nng_http_copy_body.

+
Response headers may be set using nng_http_set_header, and request headers
+may be accessed by using nng_http_get_header. They can also be iterated
+over using nng_http_next_header

+
Likewise the request body may be accessed, using nng_http_get_body, and
+the response body may be set using either nng_http_set_body or nng_http_copy_body.

 

 

   
   note
 

 
The request body is only collected for the handler if the
-nng_http_handler_collect_body function has been called for the handler.

+nng_http_handler_collect_body function has been called for the handler.

 

-
The HTTP status should be set for the transaction using nng_http_set_status.

-
Finally, the handler should finish the operation by calling the nng_aio_finish function
-after having set the status to NNG_OK.
+
The HTTP status should be set for the transaction using nng_http_set_status.

+
Finally, the handler should finish the operation by calling the nng_aio_finish function
+after having set the status to NNG_OK.
 If any other status is set on the aio, then a generic 500 response will be created and
 sent, if possible, and the connection will be closed.

-
The aio may be scheduled for deferred completion using the nng_aio_start.

+
The aio may be scheduled for deferred completion using the nng_aio_start.

 
Serving Directories and Files

 
nng_err nng_http_handler_alloc_directory(nng_http_handler **hp, const char *path, const char *dirname);
 nng_err nng_http_handler_alloc_file(nng_http_handler **hp, const char *path, const char *filename);
@@ -819,7 +819,7 @@ then a value of application/octet-stream is assumed.

 

 
The nng_http_handler_alloc_redirect function creates a handler with
 a function that simply directions from the URI at path to the given location.

-
The HTTP reply it creates will be with status code status,
+
The HTTP reply it creates will be with status code status,
 which should be a 3XX code such as 301, and a Location: header will contain the URL
 referenced by location, with any residual suffix from the request
 URI appended.

@@ -828,7 +828,7 @@ URI appended.

   
   tip
 

-
Use [nng_http_handler_set_tree] to redirect an entire tree.
+
Use nng_http_handler_set_tree to redirect an entire tree.
 For example, it is possible to redirect an entire HTTP site to another
 HTTPS site by specifying / as the path and then using the base
 of the new site, such as https://newsite.example.com as the new location.

@@ -839,10 +839,10 @@ of the new site, such as https://newsite.example.com as the new loc
   tip
 

 
Be sure to use the appropriate value for status.
-Permanent redirection should use [NNG_HTTP_STATUS_STATUS_MOVED_PERMANENTLY] (301)
-and temporary redirections should use NNG_HTTP_STATUS_TEMPORARY_REDIRECT (307).
+Permanent redirection should use NNG_HTTP_STATUS_MOVED_PERMANENTLY (301)
+and temporary redirections should use NNG_HTTP_STATUS_TEMPORARY_REDIRECT (307).
 In REST APIs, using a redirection to supply the new location of an object
-created with POST should use NNG_HTTP_STATUS_SEE_OTHER (303).

+created with POST should use NNG_HTTP_STATUS_SEE_OTHER (303).

 
 
Collecting Request Body

 
void nng_http_handler_collect_body(nng_http_handler *handler, bool want, size_t maxsz);
@@ -851,12 +851,12 @@ created with POST should use nng_http_get_body function.

+nng_http_get_body function.

 
The collection is enabled if want is true.
 Furthermore, the data that the client may sent is limited by the
 value of maxsz.
 If the client attempts to send more data than maxsz, then the
-request will be terminated with NNG_HTTP_STATUS_CONTENT_TOO_LARGE (413).

+request will be terminated with NNG_HTTP_STATUS_CONTENT_TOO_LARGE (413).

 

 

   
@@ -903,7 +903,7 @@ The intended use of this function is deallocate any resources associated with handler will be called for, such as “GET” or “POST”.
 (By default the “GET” method is handled.)

 
If method is NULL the handler will be executed for all methods.
-The handler may determine the actual method used with the nng_http_get_method function.

+The handler may determine the actual method used with the nng_http_get_method function.

 
The server will automatically call “GET” handlers if the client
 sends a “HEAD” request, and will suppress HTTP body data in the responses
 sent for such requests.

@@ -954,16 +954,21 @@ It can also provide a logical fallback instead of relying on a 404 error code.void nng_http_write_response(nng_http *conn, nng_aio *aio);
 

 
Normally the server will send any attached response, but there are circumstances where
-a response must be sent manually, such as when hijacking a connection.

+a response must be sent manually, such as when hijacking a connection.

 
In such a case, nng_http_write_response can be called, which will send the response and any attached data, asynchronously
-using the nng_aio aio.

+using the nng_aio aio.

 
By default, for HTTP/1.1 connections, the connection is kept open, and
 will be reused to receive new requests. For HTTP/1.0, or if the client has requested
 explicitly by setting the “Connection: close” header, the connection will be closed after the
 response is fully sent.

+
 
 
 
+
 
 
 
diff --git a/ref/api/id_map.html b/ref/api/id_map.html
index d18b3d5b..efa7d2ae 100644
--- a/ref/api/id_map.html
+++ b/ref/api/id_map.html
@@ -267,7 +267,7 @@ will use space efficiently even if identifiers are very far apart.
   important
 

 
The function available for nng_id_map are not thread-safe.
-Callers should use a mutex or similar approach when thread-safety is needed.

+Callers should use a mutex or similar approach when thread-safety is needed.

 
 
Create ID Map

 
#define NNG_MAP_RANDOM 1
@@ -285,7 +285,7 @@ This is useful to reduce the odds of different instances of an application using
 the same identifiers at the same time.

 
If both lo and hi are zero, then the values 0 and 0xffffffff are substituted
 in their place, giving a full range of 32-bit identifiers.

-
This function can return NNG_ENOMEM if it is unable to allocate resources, otherwise
+
This function can return NNG_ENOMEM if it is unable to allocate resources, otherwise
 it returns zero on success.

 
Destroy Map

 
void nng_id_map_free(nng_id_map *map);
@@ -315,7 +315,7 @@ index id.

 
The value must not be NULL.

 
 
If the table has to grow to accommodate this value, it may fail if insufficient
-memory is available, returning NNG_ENOMEM. Otherwise it returns zero.

+memory is available, returning NNG_ENOMEM. Otherwise it returns zero.

 
Lookup a Value

 
void *nng_id_get(nng_id_map *map, uint64_t id);
 

@@ -331,16 +331,16 @@ largest possible identifier is allocated. After wrapping, only identifiers that
 in use will be considered.
 No effort is made to order the availability of identifiers based on
 when they were freed.2

-
As with nng_id_set, this may need to allocate memory and can thus
-fail with NNG_ENOMEM.

+
As with nng_id_set, this may need to allocate memory and can thus
+fail with NNG_ENOMEM.

 
Additionally, if there are no more free identifiers within the range specified
-when map was created, then it will return NNG_ENOSPC.

+when map was created, then it will return NNG_ENOSPC.

 
Otherwise it returns zero, indicating success.

 
Remove an ID

 
int nng_id_remove(nng_id_map *map, uint64_t id);
 

 
The nng_id_remove removes the entry at index id from map.

-
If no such entry exist, it will return NNG_ENOENT. Otherwise it returns zero.

+
If no such entry exist, it will return NNG_ENOENT. Otherwise it returns zero.

 
Iterating IDs

 
bool nng_id_visit(nng_id_map *map, uint64_t *id_p, void **value_p, uint32_t *cursor);
 

@@ -356,9 +356,14 @@ The caller must not attempt to derive any value of the cursor as it ref
 iteration is undefined; entries may be repeated or omitted during such an iteration.

 
The caller must not attempt to derive any value of the cursor as it refers to internal
 table indices.

+
 
 
 
+
 
 
 
diff --git a/ref/api/init.html b/ref/api/init.html
index 8365961c..777d95fb 100644
--- a/ref/api/init.html
+++ b/ref/api/init.html
@@ -263,12 +263,12 @@ extern nng_err nng_init(nng_init_params *params);
 
Before using other interfaces in this library, it is necessary to initialize
 the library. The nng_init function performs this initialization.

 
The function is idempotent, although on tear down, every call to nng_init must
-be paired with a call to nng_fini or no resources will be released.
+be paired with a call to nng_fini or no resources will be released.
 This allows for libraries consuming these interfaces to safely initialize and finalize
 the library without disrupting other consumers in the same process.

 
Further, only the first call to this function may have a value of params other than NULL.
 If params is not NULL, and the library has already been intiazed, then nng_init will
-return NNG_EBUSY.

+return NNG_EBUSY.

 
In some cases it is desirable to tune certain runtime parameters for the library, which
 can be done by supplying a non-NULL params argument.

 
Parameters

@@ -312,12 +312,17 @@ Changes the number of threads used for asynchronous DNS look ups.

 

 
When the consumer is ready to deallocate any resources allocated by the library, it should call
 the nng_fini function. Each call to nng_fini should be paired with an earlier call to
-nng_init.

+nng_init.

 
After calling nng_fini, the consuming application must not make any other calls to NNG functions,
 except that it may use nng_init to initialize the application for further use.

+
 
 
 
+
 
 
 
diff --git a/ref/api/memory.html b/ref/api/memory.html
index 986bc369..949c81ce 100644
--- a/ref/api/memory.html
+++ b/ref/api/memory.html
@@ -256,8 +256,8 @@ at least size bytes, and returns a pointer to it.
 The memory will be 64-bit aligned.
 Note that the memory may have random data in it, just like with malloc.

 
If memory cannot be allocated for any reason, then NULL will be returned.
-Applications that experience this should treat this like NNG_ENOMEM.

-
Memory returned by nng_alloc should be freed when no longer needed using nng_free.

+Applications that experience this should treat this like NNG_ENOMEM.

+
Memory returned by nng_alloc should be freed when no longer needed using nng_free.

 

 

   
@@ -270,30 +270,35 @@ other unpredictable behavior.

 
Deallocate Memory

 
void nng_free(void *ptr, size_t size);
 

-
The nng_free function deallocates memory previously allocated by nng_alloc.

+
The nng_free function deallocates memory previously allocated by nng_alloc.

 
The size argument must exactly match the size argument that was supplied to
-nng_alloc when the memory was allocated.

+nng_alloc when the memory was allocated.

 
Duplicate String

 
char *nng_strdup(const char *src);
 

 
The nng_strdup duplicates the string src and returns it.

-
This is logically equivalent to using nng_alloc
+
This is logically equivalent to using nng_alloc
 to allocate a region of memory of strlen(s) + 1 bytes, and then
 using strcpy to copy the string into the destination before
 returning it.

 
The returned string should be deallocated with
-nng_strfree, or may be deallocated using the
-nng_free using the length of the returned string plus
+nng_strfree, or may be deallocated using the
+nng_free using the length of the returned string plus
 one (for the NUL terminating byte).

 
Free String

 
void nng_strfree(char *str);
 

 
The nng_strfree function is a convenience function that
-can be used to deallocate strings allocated with nng_strdup.

+can be used to deallocate strings allocated with nng_strdup.

 
It is effectively the same as nng_free(strlen(str) + 1).

+
 
 
 
+
 
 
 
diff --git a/ref/api/misc.html b/ref/api/misc.html
index 748304c9..21e678e7 100644
--- a/ref/api/misc.html
+++ b/ref/api/misc.html
@@ -258,7 +258,7 @@ number facilities when available.

 

 
The nng_socket_pair function creates a pair of connected file descriptors.
 These file descriptors, which are returned in the fds array, are suitable for
-use with the Socket transport.

+use with the Socket transport.

 
On POSIX platforms, this is a thin wrapper around the standard socketpair function,
 using the AF_UNIX family and the SOCK_STREAM socket type.
 1

@@ -290,9 +290,14 @@ the version numbers reported refer to both the API and the library itself.
 (The ABI – application binary interface – between the
 library and the application is controlled in a similar, but different
 manner depending upon the link options and how the library is built.)

+
 
 
 
+
 
 
 
diff --git a/ref/api/msg.html b/ref/api/msg.html
index c1153a2a..28e23337 100644
--- a/ref/api/msg.html
+++ b/ref/api/msg.html
@@ -246,15 +246,15 @@
 
Messages

 
Messages  in Scalability Protocols are the fundamental unit of
 transmission and reception, as these protocols are fundamentally message-oriented.

-
Messages have a body, containing the application-supplied
-payload, and a header, containing protocol specific routing and similar
+
Messages have a body, containing the application-supplied
+payload, and a header, containing protocol specific routing and similar
 related information.

 

 

   
   tip
 

-
Only applications using raw mode need to access the message header.
+
Only applications using raw mode need to access the message header.
 Very few NNG applications do this.

 

 
Message Structure

@@ -268,7 +268,7 @@ and a header.

 
The nng_msg_alloc function allocates a new message.
 It takes a size argument, and returns a message
 with a preallocated body of that size in the msgp parameter.

-
If it succeeds, it returns zero, otherwise this function may return NNG_ENOMEM,
+
If it succeeds, it returns zero, otherwise this function may return NNG_ENOMEM,
 indicating that insufficient memory is available to allocate a new message.

 
Destroy a Message

 
void nng_msg_free(nng_msg *msg);
@@ -278,7 +278,7 @@ indicating that insufficient memory is available to allocate a new message.

 
int nng_msg_dup(nng_msg **dup, nng_msg *msg);
 

 
The nng_msg_dup function duplicates the message msg, storing a pointer
-to the new duplicate in dup. This function also returns zero on success, or NNG_ENOMEM
+to the new duplicate in dup. This function also returns zero on success, or NNG_ENOMEM
 if memory is exhausted.

 
Message Size and Capacity

 
size_t nng_msg_capacity(nng_msg *msg);
@@ -311,7 +311,7 @@ If reallocation fails due to insufficient memory, then the original is left inta
 is at least capacity bytes. Use of this function to ensure the total anticipated
 capacity is present in the message may help prevent many small allocations.

 
Both nng_msg_realloc and nng_msg_reserve return zero on success, or may return
-NNG_ENOMEM if insufficient memory exists to preform allocation.

+NNG_ENOMEM if insufficient memory exists to preform allocation.

 

 

   
@@ -418,7 +418,7 @@ int nng_msg_header_insert_u64(nng_msg *msg, uint64_t val64);
 

 
Appending data to a message header is done by using the nng_msg_header_append functions,
 and inserting data in the header is done using the nng_msg_header_insert functions.

-
These functions act just like the nng_msg_append and nng_msg_insert functions,
+
These functions act just like the nng_msg_append and nng_msg_insert functions,
 except that they operate on the message header rather than the message body.

 
Consume from Header

 
int nng_msg_header_chop(nng_msg *msg, size_t size);
@@ -433,16 +433,16 @@ int nng_msg_header_trim_u64(nng_msg *msg, uint64_t *val64);
 

 
The nng_msg_header_trim functions remove data from the beginning of the message header,
 and the nng_msg_header_chop functions remove data from the end of the message header.

-
These functions act just like the nng_msg_trim and nng_msg_chop functions,
+
These functions act just like the nng_msg_trim and nng_msg_chop functions,
 except that they operate the message header rather than the message body.

 
Message Pipe

 
nng_pipe nng_msg_get_pipe(nng_msg *msg);
 void nng_msg_get_pipe(nng_msg *msg, nng_pipe p);
 

-
The nng_msg_set_pipe function sets the pipe associated with msg to p.
+
The nng_msg_set_pipe function sets the pipe associated with msg to p.
 This is most often useful when used with protocols that support directing
 a message to a specific peer.
-For example the PAIR version 1 protocol can do
+For example the PAIR version 1 protocol can do
 this when NNG_OPT_PAIR1_POLY mode is set.

 
The nng_msg_get_pipe function returns the pipe that was previously set on the message m,
 either directly by the application, or when the message was received by the protocol.

@@ -473,9 +473,14 @@ while ((val64 = next_datum()) != 0) {
   }
 }
 

+
 
 
 
+
 
 
 
diff --git a/ref/api/pipe.html b/ref/api/pipe.html
index f4a3be6a..49d703ce 100644
--- a/ref/api/pipe.html
+++ b/ref/api/pipe.html
@@ -269,7 +269,7 @@ accurate type checks in functions passing values of this type.

 However it is possible to access a pipe when more information about the
 source of a message is needed, or when more control is required over message delivery.

 
-
Pipe objects are created by dialers and and listeners.

+
Pipe objects are created by dialers and and listeners.

 
Initialization

 
A pipe may be initialized using the macro NNG_PIPE_INITIALIZER
 before it is opened, to prevent confusion with valid open pipes.

@@ -288,7 +288,7 @@ Otherwise it returns -1.

 

 
A pipe is considered valid if it was ever created by the socket.
 Pipes that are allocated on the stack or statically should be initialized with the macro
-NNG_PIPE_INITIALIZER to ensure that they cannot be confused with a valid pipe.

+NNG_PIPE_INITIALIZER to ensure that they cannot be confused with a valid pipe.

 
 
Closing a Pipe

 
nng_err nng_pipe_close(nng_pipe p);
@@ -296,7 +296,7 @@ Pipes that are allocated on the stack or statically should be initialized with t
 
The nng_pipe_close function closes the supplied pipe, p.
 Messages that have been submitted for sending may be flushed or delivered,
 depending upon the transport.

-
Further attempts to use the pipe after this call returns will result in NNG_ECLOSED.

+
Further attempts to use the pipe after this call returns will result in NNG_ECLOSED.

 

 

   
@@ -313,7 +313,7 @@ nng_socket nng_pipe_socket(nng_pipe p);
 

 
 
-These functions return the socket, dialer, or listener that created or owns the pipe.

+These functions return the socket, dialer, or listener that created or owns the pipe.

 
If the pipe was does not have an associated dialer or listener, then the associated will
 return [NNG_DIALER_INITIALIZER] or [NNG_LISTENER_INITIALIZER], as appropriate, and
 either [nng_dialer_id] or [nng_listener_id] for the returned object will return -1.

@@ -323,7 +323,7 @@ either [nng_dialer_id] or [nng_listener_id] for the re
   note
 

 
The socket, or the endpoint, returned by these functions may be in the process of closing,
-and might not be further usable as a result. (Other functions will result in NNG_ECLOSED.)

+and might not be further usable as a result. (Other functions will result in NNG_ECLOSED.)

 

 
Pipe Options

 
nng_err nng_pipe_get_bool(nng_pipe p, const char *opt, bool *valp);
@@ -349,8 +349,8 @@ referenced by valp.

 
These functions access an option as a specific type. The transport layer will have details about which options
 are available, and which type they may be accessed using.

 
In the case of nng_pipe_get_string, the underlying string may only be valid for as long as the pipe is valid.
-Thus, this function can only be safely called in a pipe event callback set up with nng_pipe_notify.

-
The nng_pipe_get_strdup function is like nng_pipe_get_string, but makes a copy into a newly allocated buffer, so that the string must be freed by the caller using nng_strfree.

+Thus, this function can only be safely called in a pipe event callback set up with nng_pipe_notify.

+
The nng_pipe_get_strdup function is like nng_pipe_get_string, but makes a copy into a newly allocated buffer, so that the string must be freed by the caller using nng_strfree.

 
The nng_pipe_get_strcpy function is also like nng_pipe_get_string, but it makes a copy into a buffer
 supplied by the caller. The buffer is passed in val, and the size of the buffer is passed in len.
 The value of len must be large enough to hold the string and the terminating zero byte.

@@ -377,7 +377,7 @@ Each event may have at most one callback registered.
 Registering a callback implicitly unregisters any previously registered.

 
The following pipe events are supported:

 

-
+
EventDescription
NNG_PIPE_EV_ADD_PREThis event occurs after a connection and negotiation has completed, but before the pipe is added to the socket. If the pipe is closed (using nng_pipe_close) at this point, the socket will never see the pipe, and no further events will occur for the given pipe.
NNG_PIPE_EV_ADD_PREThis event occurs after a connection and negotiation has completed, but before the pipe is added to the socket. If the pipe is closed (using nng_pipe_close) at this point, the socket will never see the pipe, and no further events will occur for the given pipe.

 
NNG_PIPE_EV_ADD_POSTThis event occurs after the pipe is fully added to the socket. Prior to this time, it is not possible to communicate over the pipe with the socket.

 
NNG_PIPE_EV_REM_POSTThis event occurs after the pipe has been removed from the socket. The underlying transport may be closed at this point, and it is not possible communicate using this pipe.

 

@@ -395,7 +395,7 @@ Doing so would thus result in a deadlock.

   
   tip
 

-
The callback cb may close a pipe for any reason by simply closing it using nng_pipe_close.
+
The callback cb may close a pipe for any reason by simply closing it using nng_pipe_close.
 For example, this might be done to prevent an unauthorized peer from connecting to the socket,
 if an authorization check made during NNG_PIPE_EV_ADD_PRE fails.

 

@@ -406,9 +406,14 @@ if an authorization check made during NNG_PIPE_EV_ADD_PRE fails.

 
This function ignores invalid values for ev.

 
+
 
 
 
+
 
 
 
diff --git a/ref/api/sock.html b/ref/api/sock.html
index facf5300..81698cce 100644
--- a/ref/api/sock.html
+++ b/ref/api/sock.html
@@ -278,7 +278,7 @@ names of the socket’s protocol, and of the protocol peers of the socket use.
 The value stored in name is a fixed string located in program text, and must not be freed
 or altered. It is guaranteed to remain valid while this library is present.

 
The nng_socket_raw function determines whether the socket is in
-raw mode or not, storing true in raw if it is, or false if it is not.

+raw mode or not, storing true in raw if it is, or false if it is not.

 
Opening a Socket

 
int nng_bus0_open(nng_socket *s);
 int nng_pub0_open(nng_socket *s);
@@ -295,18 +295,18 @@ The constructors for sockets are protocol specific so please refer to protocol d
 for more specific information.

 
The following functions open a socket in normal mode:

 
    
-
  • nng_bus0_open - BUS version 0
    • 
-
  • nng_pair0_open - PAIR version 0
    • 
-
  • nng_pair1_open - PAIR version 1
    • 
-
  • nng_pair1_open_poly - PAIR version 1, polyamorous mode
    • 
-
  • nng_pub0_open - PUB version 0
    • 
-
  • nng_pull0_open - PULL version 0
    • 
-
  • nng_push0_open - PUSH version 0
    • 
-
  • nng_rep0_open - REP version 0
    • 
-
  • nng_req0_open - REQ version 0
    • 
-
  • nng_respondent0_open - RESPONDENT version 0
    • 
-
  • nng_sub0_open - SUB version 0
    • 
-
  • nng_surveyor0_open - SURVEYOR version 0
    • 
+
  • nng_bus0_open - BUS version 0
    • 
+
  • nng_pair0_open - PAIR version 0
    • 
+
  • nng_pair1_open - PAIR version 1
    • 
+
  • nng_pair1_open_poly - PAIR version 1, polyamorous mode
    • 
+
  • nng_pub0_open - PUB version 0
    • 
+
  • nng_pull0_open - PULL version 0
    • 
+
  • nng_push0_open - PUSH version 0
    • 
+
  • nng_rep0_open - REP version 0
    • 
+
  • nng_req0_open - REQ version 0
    • 
+
  • nng_respondent0_open - RESPONDENT version 0
    • 
+
  • nng_sub0_open - SUB version 0
    • 
+
  • nng_surveyor0_open - SURVEYOR version 0
    • 
 

 
Raw Mode Sockets

 
int nng_bus0_open_raw(nng_socket *s);
@@ -334,36 +334,36 @@ the protocol specific processing must be performed by the application.

   tip
 

 
Most applications do not need to use raw sockets.
-The notable exception is when using nng_device, which requires raw sockets.
-To obtain asynchronous behavior, consider using contexts instead.

+The notable exception is when using nng_device, which requires raw sockets.
+To obtain asynchronous behavior, consider using contexts instead.

 
-
The following functions open a socket in raw mode:

+
The following functions open a socket in raw mode:

 
    
-
  • nng_bus0_open_raw - BUS version 0, raw mode
    • 
-
  • nng_pair0_open_raw - PAIR version 0, raw mode
    • 
-
  • nng_pair1_open_raw - PAIR version 1, raw mode
    • 
-
  • nng_pub0_open_raw - PUB version 0, raw mode
    • 
-
  • nng_pull0_open_raw - PULL version 0, raw mode
    • 
-
  • nng_push0_open_raw - PUSH version 0, raw mode
    • 
-
  • nng_rep0_open_raw - REP version 0, raw mode
    • 
-
  • nng_req0_open_raw - REP version 0, raw mode
    • 
-
  • nng_respondent0_open_raw - RESPONDENT version 0, raw mode
    • 
-
  • nng_sub0_open_raw - SUB version 0, raw mode
    • 
-
  • nng_surveyor0_open_raw - SURVEYOR version 0, raw mode
    • 
+
  • nng_bus0_open_raw - BUS version 0, raw mode
    • 
+
  • nng_pair0_open_raw - PAIR version 0, raw mode
    • 
+
  • nng_pair1_open_raw - PAIR version 1, raw mode
    • 
+
  • nng_pub0_open_raw - PUB version 0, raw mode
    • 
+
  • nng_pull0_open_raw - PULL version 0, raw mode
    • 
+
  • nng_push0_open_raw - PUSH version 0, raw mode
    • 
+
  • nng_rep0_open_raw - REP version 0, raw mode
    • 
+
  • nng_req0_open_raw - REP version 0, raw mode
    • 
+
  • nng_respondent0_open_raw - RESPONDENT version 0, raw mode
    • 
+
  • nng_sub0_open_raw - SUB version 0, raw mode
    • 
+
  • nng_surveyor0_open_raw - SURVEYOR version 0, raw mode
    • 
 

 
Closing a Socket

 
int nng_socket_close(nng_socket s);
 

 
The nng_socket_close function closes a socket, releasing all resources
 associated with it. Any operations that are in progress will be terminated with
-a result of NNG_ECLOSED.

+a result of NNG_ECLOSED.

 

 

   
   note
 

-
Closing a socket also invalidates any dialers, listeners,
-pipes, or contexts associated with it.

+
Closing a socket also invalidates any dialers, listeners,
+pipes, or contexts associated with it.

 

 

 

@@ -396,8 +396,8 @@ messages over the socket s. The differences in their behaviors are as f
 
The semantics of what sending a message means varies from protocol to
 protocol, so examination of the protocol documentation is encouraged.
 Additionally, some protocols may not support sending at all or may require other pre-conditions first.
-(For example, REP sockets cannot normally send data until they have first received a request,
-while SUB sockets can only receive data and never send it.)

+(For example, REP sockets cannot normally send data until they have first received a request,
+while SUB sockets can only receive data and never send it.)

 

 
nng_send

 
The nng_send function is the simplest to use, but is the least efficient.
@@ -406,7 +406,7 @@ made up of zero or more of the following values:

 
    
 
  • NNG_FLAG_NONBLOCK: 
 If the socket cannot accept more data at this time, it does not block, but returns immediately
-with a status of NNG_EAGAIN. If this flag is absent, the function will wait until data can be sent.
    • 
+with a status of NNG_EAGAIN. If this flag is absent, the function will wait until data can be sent.
 

 

 

@@ -417,28 +417,28 @@ with a status of NNG_EAGAINNNG_FLAG_NONBLOCK,
-such as with PUB sockets, which are best-effort delivery only.

+such as with PUB sockets, which are best-effort delivery only.

 

 
nng_sendmsg

 
The nng_sendmsg function sends the msg over the socket s.

 
If this function returns zero, then the socket will dispose of msg when the transmission is complete.
 If the function returns a non-zero status, then the call retains the responsibility for disposing of msg.

-
The flags can contain the value NNG_FLAG_NONBLOCK, indicating that the function should not wait if the socket
-cannot accept more data for sending. In such a case, it will return NNG_EAGAIN.

+
The flags can contain the value NNG_FLAG_NONBLOCK, indicating that the function should not wait if the socket
+cannot accept more data for sending. In such a case, it will return NNG_EAGAIN.

 

 

   
   tip
 

-
This function is preferred over nng_send, as it gives access to the message structure and eliminates both
+
This function is preferred over nng_send, as it gives access to the message structure and eliminates both
 a data copy and allocation.

 

 
nng_socket_send

-
The nng_socket_send function sends a message asynchronously, using the nng_aio aio, over the socket s.
-The message to send must have been set on aio using the nng_aio_set_msg function.

+
The nng_socket_send function sends a message asynchronously, using the nng_aio aio, over the socket s.
+The message to send must have been set on aio using the nng_aio_set_msg function.

 
If the operation completes successfully, then the socket will have disposed of the message.
 However, if it fails, then callback of aio should arrange for a final disposition of the message.
-(The message can be retrieved from aio with nng_aio_get_msg.)

+(The message can be retrieved from aio with nng_aio_get_msg.)

 
Note that callback associated with aio may be called before the message is finally delivered to the recipient.
 For example, the message may be sitting in queue, or located in TCP buffers, or even in flight.

 

@@ -448,7 +448,7 @@ For example, the message may be sitting in queue, or located in TCP buffers, or
 

 
This is the preferred function to use for sending data on a socket. While it does require a few extra
 steps on the part of the application, the lowest latencies and highest performance will be achieved by using
-this function instead of nng_send or nng_sendmsg.

+this function instead of nng_send or nng_sendmsg.

 

 
Receiving Messages

 
int nng_recv(nng_socket s, void *data, size_t *sizep, int flags);
@@ -465,8 +465,8 @@ messages over the socket s. The differences in their behaviors are as f
 
The semantics of what receiving a message means varies from protocol to
 protocol, so examination of the protocol documentation is encouraged.
 Additionally, some protocols may not support receiving at all or may require other pre-conditions first.
-(For example, REQ sockets cannot normally receive data until they have first sent a request,
-while PUB sockets can only send data and never receive it.)

+(For example, REQ sockets cannot normally receive data until they have first sent a request,
+while PUB sockets can only send data and never receive it.)

 
 
nng_recv

 
The nng_recv function is the simplest to use, but is the least efficient.
@@ -476,23 +476,23 @@ It receives the content in data, as a message size (in bytes) of up to
 
    
 
  • NNG_FLAG_NONBLOCK:
 If the socket has no messages pending for reception at this time, it does not block, but returns immediately
-with a status of NNG_EAGAIN. If this flag is absent, the function will wait until data can be received.
    • 
+with a status of NNG_EAGAIN. If this flag is absent, the function will wait until data can be received.
 

 
nng_recvmsg

-
The nng_recvmsg function receives a message and stores a pointer to the nng_msg for that message in msgp.

-
The flags can contain the value NNG_FLAG_NONBLOCK, indicating that the function should not wait if the socket
-has no messages available to receive. In such a case, it will return NNG_EAGAIN.

+
The nng_recvmsg function receives a message and stores a pointer to the nng_msg for that message in msgp.

+
The flags can contain the value NNG_FLAG_NONBLOCK, indicating that the function should not wait if the socket
+has no messages available to receive. In such a case, it will return NNG_EAGAIN.

 

 

   
   tip
 

-
This function is preferred over nng_recv, as it gives access to the message structure and eliminates both
+
This function is preferred over nng_recv, as it gives access to the message structure and eliminates both
 a data copy and allocation.

 

 
nng_socket_recv

-
The nng_socket_send function receives a message asynchronously, using the nng_aio aio, over the socket s.
-On success, the received message can be retrieved from the aio using the nng_aio_get_msg function.

+
The nng_socket_send function receives a message asynchronously, using the nng_aio aio, over the socket s.
+On success, the received message can be retrieved from the aio using the nng_aio_get_msg function.

 

 

   
@@ -508,7 +508,7 @@ Failure to do so will leak the memory.

 

 
This is the preferred function to use for receiving data on a socket. While it does require a few extra
 steps on the part of the application, the lowest latencies and highest performance will be achieved by using
-this function instead of nng_recv or nng_recvmsg.

+this function instead of nng_recv or nng_recvmsg.

 

 
Socket Options

 
int nng_socket_get_bool(nng_socket s, const char *opt, bool *valp);
@@ -533,16 +533,16 @@ are available, whether they can be read or written, and the appropriate type to
   note
 

 
Socket options are are used to tune the behavior of the higher level protocol. To change the options
-for an underlying transport, the option should be set on the dialer or listener instead of the socket.

+for an underlying transport, the option should be set on the dialer or listener instead of the socket.

 
 
Common Options

 
The following options are available for many protocols, and always use the same types and semantics described below.

 

-
-
-
+
+
+
-
+
@@ -554,8 +554,8 @@ for an underlying transport, the option should be set on the 
   note
 

-
The NNG_OPT_RECONNMAXT, NNG_OPT_RECONNMINT, and NNG_OPT_RECVMAXSZ options are just the initial defaults that dialers
-(and for NNG_OPT_RECVMAXSZ also listeners)
+
The NNG_OPT_RECONNMAXT, NNG_OPT_RECONNMINT, and NNG_OPT_RECVMAXSZ options are just the initial defaults that dialers
+(and for NNG_OPT_RECVMAXSZ also listeners)
 will use. After the dialer or listener is created, changes to the socket’s value will have no affect on that dialer or listener.
Polling Socket Events

@@ -581,7 +581,7 @@ were available in previous versions of NNG.

   note
 

-
These functions are not compatible with contexts.

+
These functions are not compatible with contexts.

 

@@ -598,7 +598,7 @@ messages on the socket.

   tip
 

 
Using these functions will force the socket to perform extra system calls, and thus
-have a negative impact on performance and latency. It is preferable to use asynchronous I/O
+have a negative impact on performance and latency. It is preferable to use asynchronous I/O
 when possible.

 
Examples

@@ -606,7 +606,7 @@ when possible.
nng_socket s = NNG_SOCKET_INITIALIZER;
 
Example 2: Publishing a Timestamp

-
This example demonstrates the use of nng_aio, nng_socket_send, and nng_sleep_aio to
+
This example demonstrates the use of nng_aio, nng_socket_send, and nng_sleep_aio to
 build a service that publishes a timestamp at one second intervals. Error handling is elided for the
 sake of clarity.
#include <stdlib.h>
@@ -657,7 +657,7 @@ int main(int argc, char **argv) {
 }
 
Example 3: Watching a Periodic Timestamp

-
This example demonstrates the use of nng_aio, nng_socket_recv, to build a client to
+
This example demonstrates the use of nng_aio, nng_socket_recv, to build a client to
 watch for messages received from the service created in Example 2.
 Error handling is elided for the sake of clarity.
#include <stdlib.h>
@@ -702,9 +702,14 @@ int main(int argc, char **argv) {
     }
 }
 

+
+
diff --git a/ref/api/stats.html b/ref/api/stats.html
index 55c805bc..aa0eeec9 100644
--- a/ref/api/stats.html
+++ b/ref/api/stats.html
@@ -278,7 +278,7 @@ subject to change at any time and without notice.
The nng_stats_get function takes a snapshot of the statistics for
 the system and returns it through the pointer statsp.
-This function may return NNG_ENOMEM if memory is exhausted, or NNG_ENOTSUP if the statistics
+This function may return NNG_ENOMEM if memory is exhausted, or NNG_ENOTSUP if the statistics
 support is not enabled in the build, but is otherwise expected to return zero.
Freeing a Snapshot
void nng_stats_free(nng_stat *stat);
@@ -312,8 +312,8 @@ const nng_stat *nng_stat_find_listener(const nng_stat *stat, nng_dialer listener
 const nng_stat *nng_stat_find_socket(const nng_stat *stat, nng_dialer socket);
 
Sometimes it is easiest to search for a specific statistic, matching by name,
-or possibly to find the tree of statistics associated with a specific socket,
-dialer, or listener.

+or possibly to find the tree of statistics associated with a specific socket,
+dialer, or listener.
The nng_stat_find functions are provided for this purpose.
The nng_stat_find function returns the first statistic within the subtree of
 statistics stat, with the given name. If no such statistic can be found, NULL
@@ -347,8 +347,8 @@ statistics tree.

 The statistic is a counter that only increments.
 Usually the change in the value of the statistic is more interesting
 (as a rate) than the absolute value at any given time. The value should
-be obtained using nng_stat_value.
-The units will be given by the value returned from nng_stat_unit.

+be obtained using nng_stat_value.
+The units will be given by the value returned from nng_stat_unit.
  • 
 
    NNG_STAT_LEVEL: 
@@ -357,25 +357,25 @@ to a specific value at a specific time. For example, this may represent the
 number of messages currently queued for some operation, or the link speed
 of a network interface. Most often the absolute value is more interesting
 than the change in the value over time. Again the value can be obtained with
-nng_stat_value, and any appropriate unit of measurement
-with nng_stat_unit.
    
+nng_stat_value, and any appropriate unit of measurement
+with nng_stat_unit.
    
 
  • 
 
    NNG_STAT_STRING: 
 The statistic is a string, such as a name. The value
-of the string can be obtained with nng_stat_string.
+of the string can be obtained with nng_stat_string.
 The value of this string
-will remain valid until the snapshot is deallocated with nng_stats_free.
    
+will remain valid until the snapshot is deallocated with nng_stats_free.
    
 
  • 
 
    NNG_STAT_BOOLEAN: 
 The value of the statistic is a truth value (either true
-or false) and can be obtained with nng_stat_bool.
    
+or false) and can be obtained with nng_stat_bool.
    
 
  • 
 
    NNG_STAT_ID: 
 The value of the statistic is a numeric identifier, such as a socket
-identifier. The value can be obtained with nng_stat_value,
+identifier. The value can be obtained with nng_stat_value,
 and will be fixed for the life of the statistic.
    
 
    • 
@@ -386,18 +386,18 @@ bool nng_stat_bool(const nng_stat *stat);
 
    These functions return the value associated with the statistic.
    The nng_stat_value function returns the the numeric value for the statistic stat
-of type NNG_STAT_COUNTER, NNG_STAT_LEVEL, or NNG_STAT_ID.
+of type NNG_STAT_COUNTER, NNG_STAT_LEVEL, or NNG_STAT_ID.
 If stat is not one of these types, then it returns zero.
    The nng_stat_bool function returns the Boolean value (either true or false) for the statistic stat of
-type NNG_STAT_BOOLEAN. If the statistics is not of this type, then it returns false.
    
+type NNG_STAT_BOOLEAN. If the statistics is not of this type, then it returns false.
    The nng_stat_string function returns a pointer to a string value for the statistic stat,
-of type NNG_STAT_STRING. This string will remain valid until the snapshot that
-stat was collected with is deallocated with nng_stats_free. If the statistic
+of type NNG_STAT_STRING. This string will remain valid until the snapshot that
+stat was collected with is deallocated with nng_stats_free. If the statistic
 is not of type NNG_STAT_STRING, then NULL is returned.
    Statistic Units
    int nng_stat_unit(const nng_stat *stat);
 
    
-
    For statistics of type NNG_STAT_COUNTER or NNG_STAT_LEVEL,
+
    For statistics of type NNG_STAT_COUNTER or NNG_STAT_LEVEL,
 it is often useful to know what that quantity being reported measures.
 The following units may be returned from nng_stat_unit for such a statistic:
      
@@ -413,12 +413,17 @@ The following units may be returned from nng_stat_unit<
 
      Statistics have a timestamp indicating when the value was sampled,
 obtained via nng_stat_timestamp. The timestamp is given in
 in milliseconds since a reference time, and the reference time used
-here is the same reference time used for nng_clock.
      
+here is the same reference time used for nng_clock.
      
 
      See Also
      
-
      nng_clock
      
+
      nng_clock
      
+
 
 
 
+
 
 
 
diff --git a/ref/api/stream.html b/ref/api/stream.html
index d0403665..25ca66bc 100644
--- a/ref/api/stream.html
+++ b/ref/api/stream.html
@@ -267,26 +267,26 @@ using these Streams APIs.
      
   note
 
      
 
      The nng_stream object is used for raw byte stream connections, and
-should not be confused with a pipe object created on a socket using
-the nng_listen, nng_dial or related functions.
      
+should not be confused with a pipe object created on a socket using
+the nng_listen, nng_dial or related functions.
      
 
 
      Sending and Receiving Data
      
 
      void nng_stream_send(nng_stream *s, nng_aio *aio);
 void nng_stream_recv(nng_stream *s, nng_aio *aio);
 
      
 
      The nng_stream_send function starts sending data asynchronously over the stream s.
-The data is sent from the scatter/gather vector located in the nng_aio aio,
-which must have been previously set using nng_aio_set_iov.
      
+The data is sent from the scatter/gather vector located in the nng_aio aio,
+which must have been previously set using nng_aio_set_iov.
      
 
      The nng_stream_recv function starts receiving data [asynchronously over the stream s
-into the scatter/gather vector located in the nng_aio aio,
-which must have been previously set using nng_aio_set_iov.
      
+into the scatter/gather vector located in the nng_aio aio,
+which must have been previously set using nng_aio_set_iov.
      
 
      These functions return immediately, with no return value.
 Completion of the operation is signaled via the aio, and the final
-result may be obtained via nng_aio_result.
      
+result may be obtained via nng_aio_result.
      
 
      The I/O operation may complete as soon as at least one byte has been
 transferred, or an error has occurred.
 Therefore, the number of bytes transferred may be less than requested.
-The actual number of bytes transferred can be determined with nng_aio_count.
      
+The actual number of bytes transferred can be determined with nng_aio_count.
      
 
      Closing a Stream
      
 
      void nng_stream_close(nng_stream *s);
 void nng_stream_stop(nng_stream *s);
@@ -294,8 +294,8 @@ void nng_stream_free(nng_stream *s);
 
      
 
      The nng_stream_close function closes a stream, but does not destroy it.
 This function returns immediately. Operations that are pending against the stream, such
-as nng_stream_send or nng_stream_recv operations will be canceled asynchronously, if possible.
-Those operations will result in NNG_ECLOSED.
      
+as nng_stream_send or nng_stream_recv operations will be canceled asynchronously, if possible.
+Those operations will result in NNG_ECLOSED.
      
 
      The nng_stream_stop function not only closes the stream, but waits for any operations
 pending against it to complete, and for any underlying asynchronous registered I/O to be fully deregistered.
 As some systems use separate threads for asynchronous I/O, stopping the stream is necessary before those
@@ -310,7 +310,7 @@ stream itself.
      
 
      
 
      Because nng_stream_stop and nng_stream_free both may block waiting for outstanding I/O to complete
 or be aborted, these functions are unsafe to call from functions that may not block, such as the
-completion function registered with an nng_aio when it is created.
      
+completion function registered with an nng_aio when it is created.
      
 
 
      Getting Stream Options
      
 
      nng_err nng_stream_get_bool(nng_stream *s, const char *opt, bool *valp);
@@ -338,7 +338,7 @@ typedef struct nng_stream_listener nng_stream_listener;
 
      
 
      
 The nng_stream_listener object and nng_stream_listener objects can be thought of as factories that
-create nng_stream streams.
      
+create nng_stream streams.
      
 
      The nng_stream_listener object a handle to a listener, which creates streams by accepting incoming connection requests.
 In a BSD socket implementation, this is the entity responsible for doing bind, listen and accept.
 Normally a listener may be used to accept multiple, possibly many, concurrent connections.
      
@@ -352,10 +352,10 @@ nng_err nng_stream_listener_alloc(nng_stream_listener **lstenerp, const char *ur
 nng_err nng_stream_listener_alloc_url(nng_stream_listener **listenerp, const nng_url *url);
       
 
      The nng_stream_dialer_alloc and nng_stream_dialer_alloc_url functions create a stream dialer, associated the
-URL specified by url represented as a string, or as an nng_url object, respectively. The dialer is returned in the location
+URL specified by url represented as a string, or as an nng_url object, respectively. The dialer is returned in the location
 dialerp references.
      
 
      The nng_stream_listener_alloc and nng_stream_listener_alloc_url functions create a stream listener, associated the
-URL specified by url represented as a string, or as an nng_url object, respectively. The listener is returned in the location
+URL specified by url represented as a string, or as an nng_url object, respectively. The listener is returned in the location
 listenerp references.
      
 
      Example 1: Creating a TCP Listener
      
 
      This shows creating a TCP listener that listens on INADDR_ANY, port 444.
      
@@ -390,15 +390,15 @@ callbacks are running that could reference an object after it is deallocated.
      Making Outgoing Connections
 
      void nng_stream_dialer_dial(nng_stream_dialer *dialer, nng_aio *aio);
 
      
-
      The nng_stream_dialer_dial initiates an outgoing connection asynchronously, using the nng_aio aio.
-If it successfully establishes a connection, it creates an nng_stream, which can be obtained as the first
-output result on aio using the nng_aio_get_output function with index zero.
      
+
      The nng_stream_dialer_dial initiates an outgoing connection asynchronously, using the nng_aio aio.
+If it successfully establishes a connection, it creates an nng_stream, which can be obtained as the first
+output result on aio using the nng_aio_get_output function with index zero.
      
 
      
 
      
   
   tip
 
      
-
      An nng_stream_dialer can be used multiple times to make multiple concurrent connection requests, but
+
      An nng_stream_dialer can be used multiple times to make multiple concurrent connection requests, but
 they all must reference the same URL.
      
 
      
 
      Example 3: Connecting to Google
      
@@ -426,12 +426,12 @@ void nng_stream_listener_accept(nng_stream_listener *listener, nng_aio *aio);
 
 
      Accepting incoming connections is performed in two steps. The first step, nng_stream_listener_listen is to setup for
 listening. For a TCP implementation of this, for example, this would perform the bind and the listen steps. This will bind
-to the address represented by the URL that was specific when the listener was created with nng_stream_listener_alloc.
      
-
      In the second step, nng_stream_listener_accept accepts an incoming connection on listener asynchronously, using the nng_aio aio.
-If an incoming connection is accepted, it will be represented as an nng_stream, which can be obtained from the aio as the first
-output result using the nng_aio_get_output function with index zero.
      
+to the address represented by the URL that was specific when the listener was created with nng_stream_listener_alloc.
      
+
      In the second step, nng_stream_listener_accept accepts an incoming connection on listener asynchronously, using the nng_aio aio.
+If an incoming connection is accepted, it will be represented as an nng_stream, which can be obtained from the aio as the first
+output result using the nng_aio_get_output function with index zero.
      
 
      Example 3: Accepting an Inbound Stream
      
-
      For clarity this example uses a synchronous approach using nng_aio_wait, but a typical server application
+
      For clarity this example uses a synchronous approach using nng_aio_wait, but a typical server application
 would most likely use a callback to accept the incoming stream, and start another instance of nng_stream_listener_accept.
      
 
      nng_aio *aio;
 nng_listener *listener;
@@ -518,10 +518,10 @@ need not retain the value referenced once the function returns.
      
 
      In the case of nng_stream_dialer_set_addr and nng_stream_listener_set_addr, the contents of addr are copied if necessary, so that the caller
 need not retain the value referenced once the function returns.
      
 
      Example 4: Socket Activation
      
-
      Some nng_stream_listener objects, depending on the underlying transport and platform, can support a technique known as “socket activation”,
+
      Some nng_stream_listener objects, depending on the underlying transport and platform, can support a technique known as “socket activation”,
 where the file descriptor used for listening and accepting is supplied externally, such as by a system service manager.
 In this case, the application supplies the file descriptor or SOCKET object using the NNG_OPT_LISTEN_FD option,
-instead of calling nng_stream_listener_listen.
      
+instead of calling nng_stream_listener_listen.
      
 
      
 
      
   
@@ -548,25 +548,30 @@ nng_err nng_stream_dialer_set_tls(nng_stream_listener *dialer, nng_tls_config *t
 nng_err nng_stream_listener_get_tls(nng_stream_listener *listener, nng_tls_config **tlsp);
 nng_err nng_stream_listener_set_tls(nng_stream_listener *listener, nng_tls_config *tls);
 
      
-
      Both nng_stream_dialer and nng_stream_listener objects may support configuration of TLS parameters.
+
      Both nng_stream_dialer and nng_stream_listener objects may support configuration of TLS parameters.
 The nng_stream_dialer_set_tls and nng_stream_listener_set_tls functions support setting the
-configuration of a nng_tls_config object supplied by tls on dialer or listener.
-This must be performed before the listener starts listening with nng_stream_listener_listen, or the dialer starts an outgoing connection
-as a result of nng_stream_dialer_dial.
      
+configuration of a nng_tls_config object supplied by tls on dialer or listener.
+This must be performed before the listener starts listening with nng_stream_listener_listen, or the dialer starts an outgoing connection
+as a result of nng_stream_dialer_dial.
      
 
      The configuration object that was previously established (which may be a default if one was not explicitly
 configured) can be obtained with the nng_stream_dialer_get_tls and nng_stream_listener_get_tls.
-They will return a pointer to the nng_tls_config object in question at the location referenced by tlsp.
      
+They will return a pointer to the nng_tls_config object in question at the location referenced by tlsp.
      
 
      
 
      
   
   note
 
      
 
      TLS configuration cannot be changed once it has started being used by a listener or dialer. This applies to
-both configuring a different TLS configuration object, as well as mutating the existing nng_tls_config object.
      
+both configuring a different TLS configuration object, as well as mutating the existing nng_tls_config object.
      
 
      
+
 
 
 
+
 
 
 
diff --git a/ref/api/synch.html b/ref/api/synch.html
index 870bab9b..eb8672a2 100644
--- a/ref/api/synch.html
+++ b/ref/api/synch.html
@@ -245,32 +245,32 @@
 
 
      Synchronization Primitives
      
 
      In order to allow safely accessing shared state, or to allow coordination between
-different threads, NNG provides synchronization primitives in the
+different threads, NNG provides synchronization primitives in the
 form of mutual exclusion locks and condition variables.
      
 
      Correct use of these primitives will be needed when accessing shared state from
-threads, or from callback functions associated with asynchronous operations.
+threads, or from callback functions associated with asynchronous operations.
 (The need to do this in callbacks is because the callback may be executed under
 a task thread other than the submitting thread.)
      
 
      Mutual Exclusion Lock
      
 
      typedef struct nng_mtx nng_mtx;
 
      
 
      Mutual exclusion locks, or mutex locks, represented by the nng_mtx structure,
-allow only a single thread to lock “own” the lock, acquired by nng_mtx_lock.
+allow only a single thread to lock “own” the lock, acquired by nng_mtx_lock.
 Any other thread trying to acquire the same mutex will wait until the owner has released the mutex
-by calling nng_mtx_unlock.
      
+by calling nng_mtx_unlock.
      
 
      Creating a Mutex
      
 
      int nng_mutx_alloc(nng_mt **mtxp);
 
      
 
      A mutex can be created by allocating one with nng_mtx_lock.
 On success, a pointer to the mutex is returned through mtxp.
 This function can fail due to insufficient memory or resources, in which
-case it will return NNG_ENOMEM. Otherwise it will succeed and return zero.
      
+case it will return NNG_ENOMEM. Otherwise it will succeed and return zero.
      
 
      Destroying a Mutex
      
 
      void nng_mtx_free(nng_mtx *mtx);
 
      
 
      When no longer needed, a mutex can be deallocated and its resources returned
 to the caller, by calling nng_mtx_free. The mutex must not be locked
-by any thread when calling this function.
      
+by any thread when calling this function.
      
 
      Acquiring a Mutex
      
 
      void nng_mtx_lock(nng_mtx *mtx);
 
      
@@ -288,7 +288,7 @@ If it does attempt to do so, the result will be a single party deadlock.
      
 
      void nng_mtx_unlock(nng_mtx *mtx);
 
      
 
      The nng_mtx_unlock function releases a mutex that the calling thread has previously
-acquired with nng_mtx_lock.
      
+acquired with nng_mtx_lock.
      
 
      
 
      
   
@@ -301,7 +301,7 @@ that acquired the mutex to begin with.
      
 
      typedef struct nng_cv nng_cv;
 
      
 
      The nng_cv structure implements a condition variable, associated with the
-the mutex mtx which was supplied when it was created.
      
+the mutex mtx which was supplied when it was created.
      
 
      Condition variables provide for a way to wait on an arbitrary condition, and to be woken
 when the condition is signaled.
 The mutex is dropped while the caller is asleep, and reacquired atomically when the caller
@@ -329,16 +329,16 @@ void nng_cv_wait(nng_cv *cv);
 
 
      The nng_cv_until and nng_cv_wait functions put the caller to sleep until the condition
 variable cv is signaled, or (in the case of nng_cv_until), the specified time when
-(as determined by nng_clock is reached.
      
+(as determined by nng_clock is reached.
      
 
      While nng_cv_wait never fails and so has no return value, the nng_cv_until function can
-return NNG_ETIMEDOUT if the time is reached before condition cv is signaled by
-either nng_cv_wake or nng_cv_wake1.
      
+return NNG_ETIMEDOUT if the time is reached before condition cv is signaled by
+either nng_cv_wake or nng_cv_wake1.
      
 
      Signaling the Condition
      
 
      void nng_cv_wake(nng_cv *cv);
 void nng_cv_wake1(nng_cv *cv);
 
      
 
      The nng_cv_wake and nng_cv_wake1 functions wake threads waiting in
-nng_cv_until or nng_cv_wait.
+nng_cv_until or nng_cv_wait.
 The difference between these functions is that
 nng_cv_wake will wake every thread, whereas nng_cv_wake1 will wake up exactly
 one thread (which may be chosen randomly).
      
@@ -377,12 +377,17 @@ nng_cv_wake(cv);
 nng_mtx_unlock(m);
 
 
      See Also
      
-
      Threads,
-Time,
-Asynchronous I/O
      
+
      Threads,
+Time,
+Asynchronous I/O
      
+
 
 
 
+
 
 
 
diff --git a/ref/api/thread.html b/ref/api/thread.html
index b191bb9a..9c5104e6 100644
--- a/ref/api/thread.html
+++ b/ref/api/thread.html
@@ -279,7 +279,7 @@ Blocking NNG library calls can however be made safely from NNG
 
      The system may impose limits on the number of threads that can be created.
 Typically applications should not create more than a dozen of these.
 If greater concurrency or scalability is needed, consider instead using
-an asynchronous model using nng_aio structures.
      
+an asynchronous model using nng_aio structures.
      
 
      
 
      Thread Structure
      
 
      typedef struct nng_thread nng_thread;
@@ -287,7 +287,7 @@ an asynchronous model using The nng_thread structure represents a thread, which is a single execution context.
 A given thread will have its own stack, and CPU registers. However global state, as well
 as values allocated on the heap, will be shared and accessible to all threads in the system
-(See the Synchronization chapter for functions to help with data sharing between different threads.)
      
+(See the Synchronization chapter for functions to help with data sharing between different threads.)
      
 
      Multiple threads can be thought of as running concurrently, even though
 they might not actually do so.
      
 
      I/O operations that block (i.e. wait for completion) will block the
@@ -314,11 +314,16 @@ It also has the effect of blocking execution in the caller until thr ha
 to provide a name for the thread. This may change how the thread is represented
 in debuggers. Not all platforms support setting the thread name.
      
 
      See Also
      
-
      Synchronization,
-Asynchronous Operations
      
+
      Synchronization,
+Asynchronous Operations
      
+
 
 
 
+
 
 
 
diff --git a/ref/api/time.html b/ref/api/time.html
index a64a3bb3..ee901c77 100644
--- a/ref/api/time.html
+++ b/ref/api/time.html
@@ -306,26 +306,31 @@ underlying system.
      
 
      Wait Asynchronously
      
 
      void nng_sleep_aio(nng_duration msec, nng_aio *aio);
 
      
-
      It is possible to wait as the action on an nng_aio, which in effect
+
      It is possible to wait as the action on an nng_aio, which in effect
 acts like scheduling a callback to run after a specified period of time.
      
 
      The nng_sleep_aio function provides this capability.
 After msec milliseconds have passed, then aio’s callback will be executed.
 If this sleep waits without interruption, and then completes, the result from
-nng_aio_result will be zero.
      
+nng_aio_result will be zero.
      
 
      
 
      
   
   note
 
      
-
      If a timeout shorter than msec is set on aio using nng_aio_set_timeout,
-then the sleep will wake up early, with a result code of NNG_ETIMEDOUT.
      
+
      If a timeout shorter than msec is set on aio using nng_aio_set_timeout,
+then the sleep will wake up early, with a result code of NNG_ETIMEDOUT.
      
 
      
 
      See Also
      
-
      Asynchronous Operations,
-Synchronization
      
+
      Asynchronous Operations,
+Synchronization
      
+
 
 
 
+
 
 
 
diff --git a/ref/api/url.html b/ref/api/url.html
index e2f042b9..a38c2a1c 100644
--- a/ref/api/url.html
+++ b/ref/api/url.html
@@ -293,7 +293,7 @@ the query-information (the part following a ‘?’) and fragment
 if they are not. The returned string will not include the leading ‘?’ or ‘#’
 characters.
      
 
      Note that any strings returned by these functions are only valid until
-url is freed with nng_url_free.
      
+url is freed with nng_url_free.
      
 
      Format a URL
      
 
      int nng_url_sprintf(char *buf, size_t bufsz, const nng_url *url);
 
      
@@ -322,7 +322,7 @@ and creates a dynamically allocated nng_url, returning it in ur
   
   important
 
      
-
      Only nng_url_free should be used to deallocate nng_url objects.
      
+
      Only nng_url_free should be used to deallocate nng_url objects.
      
 
 
      Clone a URL
      
 
      int nng_url_clone(nng_url **dup, const nng_url *url);
@@ -332,8 +332,8 @@ and creates a dynamically allocated nng_url, returning it in ur
 
      void nng_url_free(nng_url *url);
 
      
 
      The nng_url_free function destroy an nng_url object created with
-either nng_url_parse or nng_url_free.
      
-
      This is the only correct way to destroy an nng_url object.
      
+either nng_url_parse or nng_url_free.
      
+
      This is the only correct way to destroy an nng_url object.
      
 
      Update a URL Port
      
 
      void nng_url_resolve_port(nng_url *url, uint32_t port);
 
      
@@ -345,9 +345,14 @@ a URL with a new port. This will have no effect if the URL already has a non-zer
 
      See Also
      
 
      More information about Universal Resource Locators can be found in
 RFC 3986.
      
+
 
 
 
+
 
 
 
diff --git a/ref/migrate/nanomsg.html b/ref/migrate/nanomsg.html
index 1576987f..28c9eae7 100644
--- a/ref/migrate/nanomsg.html
+++ b/ref/migrate/nanomsg.html
@@ -254,7 +254,7 @@ update it for this version of NNG.
      
 
      Replace -lnanomsg with -lnng.
 It may be necessary to include additional system libraries, such as -lpthread, depending on your system.
      
 
      Initialization
      
-
      It is necessary to explicitly initialize the library, using the nng_init function.
+
      It is necessary to explicitly initialize the library, using the nng_init function.
 This must be called before any other function.
      
 
      Types
      
 
      Sockets, dialers, and listeners in libnanomsg are simple integers.
@@ -265,87 +265,87 @@ headers.
      
 NNG approach to messages. Likewise there is no struct nn_cmsghdr equivalent.
      
 
      API Conversions
      
 
    OptionTypeDescription
    NNG_OPT_MAXTTLintMaximum number of traversals across an nng_device device, to prevent forwarding loops. May be 1-255, inclusive. Normally defaults to 8.
    NNG_OPT_RECONNMAXTnng_durationMaximum time dialers will delay before trying after failing to connect.
    NNG_OPT_RECONNMINTnng_durationMinimum time dialers will delay before trying after failing to connect.
    NNG_OPT_MAXTTLintMaximum number of traversals across an nng_device device, to prevent forwarding loops. May be 1-255, inclusive. Normally defaults to 8.
    NNG_OPT_RECONNMAXTnng_durationMaximum time dialers will delay before trying after failing to connect.
    NNG_OPT_RECONNMINTnng_durationMinimum time dialers will delay before trying after failing to connect.
    
 
    NNG_OPT_RECVBUFintMaximum number of messages (0-8192) to buffer locally when receiving.
    NNG_OPT_RECVMAXSZsize_tMaximum message size acceptable for receiving. Zero means unlimited. Intended to prevent remote abuse. Can be tuned independently on dialers and listeners.
    NNG_OPT_RECVMAXSZsize_tMaximum message size acceptable for receiving. Zero means unlimited. Intended to prevent remote abuse. Can be tuned independently on dialers and listeners.
    
 
    NNG_OPT_RECVTIMEOnng_durationDefault timeout (ms) for receiving messages.
    
 
    NNG_OPT_SENDBUFintMaximum number of messages (0-8192) to buffer when sending messages.
    
 
    NNG_OPT_SENDTIMEOnng_durationDefault timeout (ms) for sending messages.
    
 
 
   
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
    
-
+
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-
+
+
-
+
-
-
-
+
+
+
    Nanomsg APINNG EquivalentNotes
    nn_strerrornng_strerror
    nn_strerrornng_strerror
    
 
    nn_errnoNoneErrors are returned directly rather than through errno.
    
 
    nn_socketVariousUse the appropriate protocol constructor, such as nng_req0_open.
    nn_closenng_socket_close 
    nn_bindnng_listen, nng_listener_createAllocating a listener with nng_lister_create and configuring it offers more capabilities.
    nn_connectnng_dial, nng_dialer_createAllocating a dialer with nng_dialer_create and configuring it offers more capabilities.
    nn_shutdownnng_listener_close, nng_dialer_close
    nn_allocmsgnng_msg_allocThere are significant semantic differences.
    nn_freemsgnng_msg_free
    nn_reallocmsgnng_msg_realloc
    nn_sendnng_send
    nn_recvnng_recv
    nn_sendmsgnng_sendmsg
    nn_getsockoptnng_socket_getNNG has typed accessors for options, and also separate functions for dialers and listeners.
    nn_setsockoptnng_socket_set
    nn_devicenng_device
    nn_closenng_socket_close 
    nn_bindnng_listen, nng_listener_createAllocating a listener with nng_lister_create and configuring it offers more capabilities.
    nn_connectnng_dial, nng_dialer_createAllocating a dialer with nng_dialer_create and configuring it offers more capabilities.
    nn_shutdownnng_listener_close, nng_dialer_close
    nn_allocmsgnng_msg_allocThere are significant semantic differences.
    nn_freemsgnng_msg_free
    nn_reallocmsgnng_msg_realloc
    nn_sendnng_send
    nn_recvnng_recv
    nn_sendmsgnng_sendmsg
    nn_getsockoptnng_socket_getNNG has typed accessors for options, and also separate functions for dialers and listeners.
    nn_setsockoptnng_socket_set
    nn_devicenng_device
    
 
    nn_pollNoneCan be constructed using nng_aio. Few if any applications ever used this API.
    nn_termnng_finiThe nng_fini API can do this, but is not recommended except when debugging memory leaks.
    nn_get_statisticnng_stats_getThe statistics in NNG are completely different, with different semantics and no stability guarantees.
    nn_termnng_finiThe nng_fini API can do this, but is not recommended except when debugging memory leaks.
    nn_get_statisticnng_stats_getThe statistics in NNG are completely different, with different semantics and no stability guarantees.
    
 
    NN_POLLINNoneUsed only with nn_poll.
    
 
    NN_POLLOUTNoneUsed only with nn_poll.
    NN_MSGnng_sendmsg, nng_recvmsgThere are differences as a separate nng_msg structure is involved.
    NN_MSGnng_sendmsg, nng_recvmsgThere are differences as a separate nng_msg structure is involved.
    
 
    NN_CMSG_ALIGNNone
    
 
    NN_CMSG_FIRSTHDRNone
    
 
    NN_CMSG_NXTHDRNone
    
 
    NN_CMSG_DATANone
    
 
    NN_CMSG_LENNone
    
 
    NN_CMSG_SPACENone
    struct nn_iovecnng_iov
    struct nn_msghdrnng_msg
    struct nn_cmsghdrnng_msg and nng_msg_header
    struct nn_iovecnng_iov
    struct nn_msghdrnng_msg
    struct nn_cmsghdrnng_msg and nng_msg_header
    
 
    
 
    
 
    Options
    
 
    The following options are changed.
    
 
    
-
-
-
-
-
-
+
+
+
+
+
+
-
-
+
+
-
+
-
-
-
+
+
+
    Nanomsg OptionNNG EqvaivalentNotes
    
 
    NN_LINGERNoneNNG does not support tuning this.
    NN_SNDBUFNNG_OPT_SENDBUFNNG value is given in messages, not bytes.
    NN_RCVBUFNNG_OPT_RECVBUFNNG value is given in messages, not bytes.
    NN_SNDTIMEONNG_OPT_SENDTIMEO
    NN_RCVTIMEONNG_OPT_RECVTIMEO
    NN_RECONNECT_IVLNNG_OPT_RECONNMINT
    NN_RECONNECT_IVL_MAXNNG_OPT_RECONNMAXT
    NN_SNDBUFNNG_OPT_SENDBUFNNG value is given in messages, not bytes.
    NN_RCVBUFNNG_OPT_RECVBUFNNG value is given in messages, not bytes.
    NN_SNDTIMEONNG_OPT_SENDTIMEO
    NN_RCVTIMEONNG_OPT_RECVTIMEO
    NN_RECONNECT_IVLNNG_OPT_RECONNMINT
    NN_RECONNECT_IVL_MAXNNG_OPT_RECONNMAXT
    
 
    NN_SNDPRIONoneNot supported in NNG yet.
    
 
    NN_RCVPRIONoneNot supported in NNG yet.
    NN_RCVFDnng_socket_get_recv_poll_fdNo longer an option, use a function call.
    NN_SNDFDnng_socket_get_send_poll_fdNo longer an option, use a function call.
    NN_RCVFDnng_socket_get_recv_poll_fdNo longer an option, use a function call.
    NN_SNDFDnng_socket_get_send_poll_fdNo longer an option, use a function call.
    
 
    NN_DOMAINNoneNNG options are not divided by domain or protocol.
    NN_PROTOCOLnng_socket_proto_idNo longer an option. See also nng_socket_proto_name.
    NN_PROTOCOLnng_socket_proto_idNo longer an option. See also nng_socket_proto_name.
    
 
    NN_IPV4ONLYNoneUse URL such as tcp4:// to obtain this functionality.
    
 
    NN_SOCKET_NAMENoneRemoved from NNG.
    NN_MAXTTLNNG_OPT_MAXTTL
    NN_SUB_SUBSCRIBEnng_sub0_socket_subscribeNo longer an option, use a function call.
    NN_SUB_UNSUBSCRIBEnng_sub0_socket_unsubscribeNo longer an option, use a function call.
    NN_MAXTTLNNG_OPT_MAXTTL
    NN_SUB_SUBSCRIBEnng_sub0_socket_subscribeNo longer an option, use a function call.
    NN_SUB_UNSUBSCRIBEnng_sub0_socket_unsubscribeNo longer an option, use a function call.
    
 
    
 
    
 
    Error Codes
    
 
    Most of the error codes have similar names in NNG, just prefixed with NNG_.
 There are some exceptions. Be aware that the numeric values are not the same.
    
 
    
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
    Nanomsg ErrorNNG ErrorNotes
    EINTRNNG_EINTR
    ENOMEMNNG_ENOMEM
    EINVALNNG_EINVAL, NNG_EADDRINVAL, NNG_EBADTYPENNG discrimates between different types of errors.
    EBUSYNNG_EBUSY
    ETIMEDOUTNNG_ETIMEDOUT
    ECONNREFUSEDNNG_ECONNREFUSED
    EBADFNNG_ECLOSED, NNG_ECANCELEDCanceling an operation returns differently than using an invalid or closed object.
    EAGAINNNG_EAGAIN
    ENOTSUPNNG_ENOTSUP
    EADDRINUSENNG_EADDRINUSE
    EFSMNNG_ESTATENot a legal POSIX errno value.
    ENOENTNNG_ENOENT
    EPROTONNG_EPROTO
    EHOSTUNREACHNNG_EUNREACHABLE
    EACCCESNNG_EPERM, NNG_EWRITEONLY, NNG_EREADONLY, NNG_ECRYPTO, NNG_EPEERAUTHNNG has more fine grained reasons for access failures.
    EMSGSIZENNG_EMSGSIZE
    ECONNABORTEDNNG_ECONNABORTED
    ECONNRESETNNG_ECONNRESET
    EEXISTNNG_EEXIST
    EMFILENNG_ENOFILES
    ENOSPCNNG_ENOSPC
    EINTRNNG_EINTR
    ENOMEMNNG_ENOMEM
    EINVALNNG_EINVAL, NNG_EADDRINVAL, NNG_EBADTYPENNG discrimates between different types of errors.
    EBUSYNNG_EBUSY
    ETIMEDOUTNNG_ETIMEDOUT
    ECONNREFUSEDNNG_ECONNREFUSED
    EBADFNNG_ECLOSED, NNG_ECANCELEDCanceling an operation returns differently than using an invalid or closed object.
    EAGAINNNG_EAGAIN
    ENOTSUPNNG_ENOTSUP
    EADDRINUSENNG_EADDRINUSE
    EFSMNNG_ESTATENot a legal POSIX errno value.
    ENOENTNNG_ENOENT
    EPROTONNG_EPROTO
    EHOSTUNREACHNNG_EUNREACHABLE
    EACCCESNNG_EPERM, NNG_EWRITEONLY, NNG_EREADONLY, NNG_ECRYPTO, NNG_EPEERAUTHNNG has more fine grained reasons for access failures.
    EMSGSIZENNG_EMSGSIZE
    ECONNABORTEDNNG_ECONNABORTED
    ECONNRESETNNG_ECONNRESET
    EEXISTNNG_EEXIST
    EMFILENNG_ENOFILES
    ENOSPCNNG_ENOSPC
    
 
    
 
    
 
    Local Addresses for Dialing
    
@@ -353,9 +353,14 @@ There are some exceptions. Be aware that the numeric values are not the
 using nn_dial inside the URL is not present in NNG. The correct
 way to specify the local address is using the NNG_OPT_LOCADDR option on the
 dialer before starting to dial.
    
+
 
 
 
+
 
 
 
diff --git a/ref/migrate/nng1.html b/ref/migrate/nng1.html
index 59e30494..cf8f81ca 100644
--- a/ref/migrate/nng1.html
+++ b/ref/migrate/nng1.html
@@ -264,7 +264,7 @@ between releases or builds of NNG 2.
    
 See the Migrating From libnanomsg chapter for details.
    
 
    Library Initialization
    
 
    It is now required for applications to initialize the library explicitly before using it.
-This is done using the nng_init function.
    
+This is done using the nng_init function.
    
 
    Removed Headers
    
 
    The following header files are removed, and the declarations they provided are now provided by including <nng/nng.h>.
 Simply remove any references to them.
    
@@ -294,9 +294,9 @@ Simply remove any references to them.
    
 
    The following functions have been renamed as described by the following table.
 The old names are available by defining the macro NNG1_TRANSITION in your compilation environment.
    
 
    
-
-
-
+
+
+
    Old NameNew Name
    nng_closenng_socket_close
    nng_recv_aionng_socket_recv
    nng_send_aionng_socket_send
    nng_closenng_socket_close
    nng_recv_aionng_socket_recv
    nng_send_aionng_socket_send
    
 
    
 
    
 
    Removed Protocol Aliases
    
@@ -316,13 +316,13 @@ The old names are available by defining the macro NNG1_TRANSITION i
 
    Just add either 0 or 1 (in the case of PAIRv1) to get the protocol desired. (Forcing the version number to
 be supplied should avoid surprises later as new versions of protocols are added.)
    
 
    NNG_FLAG_ALLOC Removed
    
-
    The NNG_FLAG_ALLOC flag that allowed a zero copy semantic with nng_send and nng_recv is removed.
+
    The NNG_FLAG_ALLOC flag that allowed a zero copy semantic with nng_send and nng_recv is removed.
 This was implemented mostly to aid legacy nanomsg applications, and it was both error prone and still a bit
 suboptimal in terms of performance.
    
-
    Modern code should use one of nng_sendmsg, nng_recvmsg, nng_socket_send, or nng_socket_recv to get the maximum performance benefit.
-Working directly with nng_msg structures gives more control, reduces copies, and reduces allocation activity.
    
+
    Modern code should use one of nng_sendmsg, nng_recvmsg, nng_socket_send, or nng_socket_recv to get the maximum performance benefit.
+Working directly with nng_msg structures gives more control, reduces copies, and reduces allocation activity.
    
 
    Error Code Changes
    
-
    When an operation fails with NNG_ESTOPPED, it means that the associated [nni_aio] object has
+
    When an operation fails with NNG_ESTOPPED, it means that the associated [nni_aio] object has
 been permanently stopped and must not be reused. Applications must watch for this error code, and
 not resubmit an operation that returns it. This is particularly important for callbacks that automatically
 resubmit operations. Failure to observe this rule will lead to an infinite loop
@@ -331,9 +331,9 @@ as any further operations on the object will fail immediately with NNG_EST
 
    AIO Provider API changes
    
 
    The API used for providers for asynchronous I/O operations has changed slightly.
    
 
 
    The following API calls have changed so that they are void returns, and cannot fail.
 They may silently truncate data.
    
 
 
    The HTTP handler objects may not be modified once in use. Previously this would fail with NNG_EBUSY.
 These checks are removed now, but debug builds will assert if an application tries to do so.
    
@@ -566,14 +566,19 @@ support for security descriptors altogether in NNG.
    
 
    Command Line Argument Parser Changes
    
 
    The supplemental function nng_opts_parse and supporting definitions have moved.
 This functionality is now supplied by a header only library, available in nng/args.h.
-See nng_args_parse for more information.
    
+See nng_args_parse for more information.
    
 
    ZeroTier Support Removed
    
 
    The Layer 2 special ZeroTier transport has been removed.
 It is possible to use NNG with ZeroTier using TCP/IP, and a future update
 is planned to provided coexistence between ZeroTier & the native stack’s TCP/IP using lwIP.
    
+
 
 
 
+
 
 
 
diff --git a/ref/print.html b/ref/print.html
index c8a63675..517fc830 100644
--- a/ref/print.html
+++ b/ref/print.html
@@ -728,12 +728,12 @@ extern nng_err nng_init(nng_init_params *params);
 
    Before using other interfaces in this library, it is necessary to initialize
 the library. The nng_init function performs this initialization.
    
 
    The function is idempotent, although on tear down, every call to nng_init must
-be paired with a call to nng_fini or no resources will be released.
+be paired with a call to nng_fini or no resources will be released.
 This allows for libraries consuming these interfaces to safely initialize and finalize
 the library without disrupting other consumers in the same process.
    
 
    Further, only the first call to this function may have a value of params other than NULL.
 If params is not NULL, and the library has already been intiazed, then nng_init will
-return NNG_EBUSY.
    
+return NNG_EBUSY.
    
 
    In some cases it is desirable to tune certain runtime parameters for the library, which
 can be done by supplying a non-NULL params argument.
    
 
    Parameters
    
@@ -777,12 +777,17 @@ Changes the number of threads used for asynchronous DNS look ups.
    
 
    
 
    When the consumer is ready to deallocate any resources allocated by the library, it should call
 the nng_fini function. Each call to nng_fini should be paired with an earlier call to
-nng_init.
    
+nng_init.
    
 
    After calling nng_fini, the consuming application must not make any other calls to NNG functions,
 except that it may use nng_init to initialize the application for further use.
    
+
 
 
 
+
 
 
 
@@ -857,15 +862,15 @@ except that it may use nng_init to initialize the application for f
 
    Messages
    
 
    Messages  in Scalability Protocols are the fundamental unit of
 transmission and reception, as these protocols are fundamentally message-oriented.
    
-
    Messages have a body, containing the application-supplied
-payload, and a header, containing protocol specific routing and similar
+
    Messages have a body, containing the application-supplied
+payload, and a header, containing protocol specific routing and similar
 related information.
    
 
    
 
    
   
   tip
 
    
-
    Only applications using raw mode need to access the message header.
+
    Only applications using raw mode need to access the message header.
 Very few NNG applications do this.
    
 
    
 
    Message Structure
    
@@ -879,7 +884,7 @@ and a header.
    
 
    The nng_msg_alloc function allocates a new message.
 It takes a size argument, and returns a message
 with a preallocated body of that size in the msgp parameter.
    
-
    If it succeeds, it returns zero, otherwise this function may return NNG_ENOMEM,
+
    If it succeeds, it returns zero, otherwise this function may return NNG_ENOMEM,
 indicating that insufficient memory is available to allocate a new message.
    
 
    Destroy a Message
    
 
    void nng_msg_free(nng_msg *msg);
@@ -889,7 +894,7 @@ indicating that insufficient memory is available to allocate a new message.
    
 
    int nng_msg_dup(nng_msg **dup, nng_msg *msg);
 
    
 
    The nng_msg_dup function duplicates the message msg, storing a pointer
-to the new duplicate in dup. This function also returns zero on success, or NNG_ENOMEM
+to the new duplicate in dup. This function also returns zero on success, or NNG_ENOMEM
 if memory is exhausted.
    
 
    Message Size and Capacity
    
 
    size_t nng_msg_capacity(nng_msg *msg);
@@ -922,7 +927,7 @@ If reallocation fails due to insufficient memory, then the original is left inta
 is at least capacity bytes. Use of this function to ensure the total anticipated
 capacity is present in the message may help prevent many small allocations.
    
 
    Both nng_msg_realloc and nng_msg_reserve return zero on success, or may return
-NNG_ENOMEM if insufficient memory exists to preform allocation.
    
+NNG_ENOMEM if insufficient memory exists to preform allocation.
    
 
    
 
    
   
@@ -1029,7 +1034,7 @@ int nng_msg_header_insert_u64(nng_msg *msg, uint64_t val64);
 
    
 
    Appending data to a message header is done by using the nng_msg_header_append functions,
 and inserting data in the header is done using the nng_msg_header_insert functions.
    
-
    These functions act just like the nng_msg_append and nng_msg_insert functions,
+
    These functions act just like the nng_msg_append and nng_msg_insert functions,
 except that they operate on the message header rather than the message body.
    
 
    Consume from Header
    
 
    int nng_msg_header_chop(nng_msg *msg, size_t size);
@@ -1044,16 +1049,16 @@ int nng_msg_header_trim_u64(nng_msg *msg, uint64_t *val64);
 
    
 
    The nng_msg_header_trim functions remove data from the beginning of the message header,
 and the nng_msg_header_chop functions remove data from the end of the message header.
    
-
    These functions act just like the nng_msg_trim and nng_msg_chop functions,
+
    These functions act just like the nng_msg_trim and nng_msg_chop functions,
 except that they operate the message header rather than the message body.
    
 
    Message Pipe
    
 
    nng_pipe nng_msg_get_pipe(nng_msg *msg);
 void nng_msg_get_pipe(nng_msg *msg, nng_pipe p);
 
    
-
    The nng_msg_set_pipe function sets the pipe associated with msg to p.
+
    The nng_msg_set_pipe function sets the pipe associated with msg to p.
 This is most often useful when used with protocols that support directing
 a message to a specific peer.
-For example the PAIR version 1 protocol can do
+For example the PAIR version 1 protocol can do
 this when NNG_OPT_PAIR1_POLY mode is set.
    
 
    The nng_msg_get_pipe function returns the pipe that was previously set on the message m,
 either directly by the application, or when the message was received by the protocol.
    
@@ -1084,9 +1089,14 @@ while ((val64 = next_datum()) != 0) {
   }
 }
 
    
+
 
 
 
+
 
 
 
@@ -1193,7 +1203,7 @@ names of the socket’s protocol, and of the protocol peers of the socket use.
 The value stored in name is a fixed string located in program text, and must not be freed
 or altered. It is guaranteed to remain valid while this library is present.
    
 
    The nng_socket_raw function determines whether the socket is in
-raw mode or not, storing true in raw if it is, or false if it is not.
    
+raw mode or not, storing true in raw if it is, or false if it is not.
    
 
    Opening a Socket
    
 
    int nng_bus0_open(nng_socket *s);
 int nng_pub0_open(nng_socket *s);
@@ -1210,18 +1220,18 @@ The constructors for sockets are protocol specific so please refer to protocol d
 for more specific information.
    
 
    The following functions open a socket in normal mode:
    
 
      
-
    • nng_bus0_open - BUS version 0
      • 
-
    • nng_pair0_open - PAIR version 0
      • 
-
    • nng_pair1_open - PAIR version 1
      • 
-
    • nng_pair1_open_poly - PAIR version 1, polyamorous mode
      • 
-
    • nng_pub0_open - PUB version 0
      • 
-
    • nng_pull0_open - PULL version 0
      • 
-
    • nng_push0_open - PUSH version 0
      • 
-
    • nng_rep0_open - REP version 0
      • 
-
    • nng_req0_open - REQ version 0
      • 
-
    • nng_respondent0_open - RESPONDENT version 0
      • 
-
    • nng_sub0_open - SUB version 0
      • 
-
    • nng_surveyor0_open - SURVEYOR version 0
      • 
+
    • nng_bus0_open - BUS version 0
      • 
+
    • nng_pair0_open - PAIR version 0
      • 
+
    • nng_pair1_open - PAIR version 1
      • 
+
    • nng_pair1_open_poly - PAIR version 1, polyamorous mode
      • 
+
    • nng_pub0_open - PUB version 0
      • 
+
    • nng_pull0_open - PULL version 0
      • 
+
    • nng_push0_open - PUSH version 0
      • 
+
    • nng_rep0_open - REP version 0
      • 
+
    • nng_req0_open - REQ version 0
      • 
+
    • nng_respondent0_open - RESPONDENT version 0
      • 
+
    • nng_sub0_open - SUB version 0
      • 
+
    • nng_surveyor0_open - SURVEYOR version 0
      • 
 
    
 
    Raw Mode Sockets
    
 
    int nng_bus0_open_raw(nng_socket *s);
@@ -1249,36 +1259,36 @@ the protocol specific processing must be performed by the application.
    
   tip
 
    
 
    Most applications do not need to use raw sockets.
-The notable exception is when using nng_device, which requires raw sockets.
-To obtain asynchronous behavior, consider using contexts instead.
    
+The notable exception is when using nng_device, which requires raw sockets.
+To obtain asynchronous behavior, consider using contexts instead.
    
 
-
    The following functions open a socket in raw mode:
    
+
    The following functions open a socket in raw mode:
    
 
      
-
    • nng_bus0_open_raw - BUS version 0, raw mode
      • 
-
    • nng_pair0_open_raw - PAIR version 0, raw mode
      • 
-
    • nng_pair1_open_raw - PAIR version 1, raw mode
      • 
-
    • nng_pub0_open_raw - PUB version 0, raw mode
      • 
-
    • nng_pull0_open_raw - PULL version 0, raw mode
      • 
-
    • nng_push0_open_raw - PUSH version 0, raw mode
      • 
-
    • nng_rep0_open_raw - REP version 0, raw mode
      • 
-
    • nng_req0_open_raw - REP version 0, raw mode
      • 
-
    • nng_respondent0_open_raw - RESPONDENT version 0, raw mode
      • 
-
    • nng_sub0_open_raw - SUB version 0, raw mode
      • 
-
    • nng_surveyor0_open_raw - SURVEYOR version 0, raw mode
      • 
+
    • nng_bus0_open_raw - BUS version 0, raw mode
      • 
+
    • nng_pair0_open_raw - PAIR version 0, raw mode
      • 
+
    • nng_pair1_open_raw - PAIR version 1, raw mode
      • 
+
    • nng_pub0_open_raw - PUB version 0, raw mode
      • 
+
    • nng_pull0_open_raw - PULL version 0, raw mode
      • 
+
    • nng_push0_open_raw - PUSH version 0, raw mode
      • 
+
    • nng_rep0_open_raw - REP version 0, raw mode
      • 
+
    • nng_req0_open_raw - REP version 0, raw mode
      • 
+
    • nng_respondent0_open_raw - RESPONDENT version 0, raw mode
      • 
+
    • nng_sub0_open_raw - SUB version 0, raw mode
      • 
+
    • nng_surveyor0_open_raw - SURVEYOR version 0, raw mode
      • 
 
    
 
    Closing a Socket
    
 
    int nng_socket_close(nng_socket s);
 
    
 
    The nng_socket_close function closes a socket, releasing all resources
 associated with it. Any operations that are in progress will be terminated with
-a result of NNG_ECLOSED.
    
+a result of NNG_ECLOSED.
    
 
    
 
    
   
   note
 
    
-
    Closing a socket also invalidates any dialers, listeners,
-pipes, or contexts associated with it.
    
+
    Closing a socket also invalidates any dialers, listeners,
+pipes, or contexts associated with it.
    
 
    
 
    
 
    
@@ -1311,8 +1321,8 @@ messages over the socket s. The differences in their behaviors are as f
 
    The semantics of what sending a message means varies from protocol to
 protocol, so examination of the protocol documentation is encouraged.
 Additionally, some protocols may not support sending at all or may require other pre-conditions first.
-(For example, REP sockets cannot normally send data until they have first received a request,
-while SUB sockets can only receive data and never send it.)
    
+(For example, REP sockets cannot normally send data until they have first received a request,
+while SUB sockets can only receive data and never send it.)
    
 
    
 
    nng_send
    
 
    The nng_send function is the simplest to use, but is the least efficient.
@@ -1321,7 +1331,7 @@ made up of zero or more of the following values:
    
 
      
 
    • NNG_FLAG_NONBLOCK: 
 If the socket cannot accept more data at this time, it does not block, but returns immediately
-with a status of NNG_EAGAIN. If this flag is absent, the function will wait until data can be sent.
      • 
+with a status of NNG_EAGAIN. If this flag is absent, the function will wait until data can be sent.
 
    
 
    
 
    
@@ -1332,28 +1342,28 @@ with a status of NNG_EAGAINNNG_FLAG_NONBLOCK,
-such as with PUB sockets, which are best-effort delivery only.
    
+such as with PUB sockets, which are best-effort delivery only.
    
 
    
 
    nng_sendmsg
    
 
    The nng_sendmsg function sends the msg over the socket s.
    
 
    If this function returns zero, then the socket will dispose of msg when the transmission is complete.
 If the function returns a non-zero status, then the call retains the responsibility for disposing of msg.
    
-
    The flags can contain the value NNG_FLAG_NONBLOCK, indicating that the function should not wait if the socket
-cannot accept more data for sending. In such a case, it will return NNG_EAGAIN.
    
+
    The flags can contain the value NNG_FLAG_NONBLOCK, indicating that the function should not wait if the socket
+cannot accept more data for sending. In such a case, it will return NNG_EAGAIN.
    
 
    
 
    
   
   tip
 
    
-
    This function is preferred over nng_send, as it gives access to the message structure and eliminates both
+
    This function is preferred over nng_send, as it gives access to the message structure and eliminates both
 a data copy and allocation.
    
 
    
 
    nng_socket_send
    
-
    The nng_socket_send function sends a message asynchronously, using the nng_aio aio, over the socket s.
-The message to send must have been set on aio using the nng_aio_set_msg function.
    
+
    The nng_socket_send function sends a message asynchronously, using the nng_aio aio, over the socket s.
+The message to send must have been set on aio using the nng_aio_set_msg function.
    
 
    If the operation completes successfully, then the socket will have disposed of the message.
 However, if it fails, then callback of aio should arrange for a final disposition of the message.
-(The message can be retrieved from aio with nng_aio_get_msg.)
    
+(The message can be retrieved from aio with nng_aio_get_msg.)
    
 
    Note that callback associated with aio may be called before the message is finally delivered to the recipient.
 For example, the message may be sitting in queue, or located in TCP buffers, or even in flight.
    
 
    
@@ -1363,7 +1373,7 @@ For example, the message may be sitting in queue, or located in TCP buffers, or
 
    
 
    This is the preferred function to use for sending data on a socket. While it does require a few extra
 steps on the part of the application, the lowest latencies and highest performance will be achieved by using
-this function instead of nng_send or nng_sendmsg.
    
+this function instead of nng_send or nng_sendmsg.
    
 
    
 
    Receiving Messages
    
 
    int nng_recv(nng_socket s, void *data, size_t *sizep, int flags);
@@ -1380,8 +1390,8 @@ messages over the socket s. The differences in their behaviors are as f
 
    The semantics of what receiving a message means varies from protocol to
 protocol, so examination of the protocol documentation is encouraged.
 Additionally, some protocols may not support receiving at all or may require other pre-conditions first.
-(For example, REQ sockets cannot normally receive data until they have first sent a request,
-while PUB sockets can only send data and never receive it.)
    
+(For example, REQ sockets cannot normally receive data until they have first sent a request,
+while PUB sockets can only send data and never receive it.)
    
 
 
    nng_recv
    
 
    The nng_recv function is the simplest to use, but is the least efficient.
@@ -1391,23 +1401,23 @@ It receives the content in data, as a message size (in bytes) of up to
 
      
 
    • NNG_FLAG_NONBLOCK:
 If the socket has no messages pending for reception at this time, it does not block, but returns immediately
-with a status of NNG_EAGAIN. If this flag is absent, the function will wait until data can be received.
      • 
+with a status of NNG_EAGAIN. If this flag is absent, the function will wait until data can be received.
 
    
 
    nng_recvmsg
    
-
    The nng_recvmsg function receives a message and stores a pointer to the nng_msg for that message in msgp.
    
-
    The flags can contain the value NNG_FLAG_NONBLOCK, indicating that the function should not wait if the socket
-has no messages available to receive. In such a case, it will return NNG_EAGAIN.
    
+
    The nng_recvmsg function receives a message and stores a pointer to the nng_msg for that message in msgp.
    
+
    The flags can contain the value NNG_FLAG_NONBLOCK, indicating that the function should not wait if the socket
+has no messages available to receive. In such a case, it will return NNG_EAGAIN.
    
 
    
 
    
   
   tip
 
    
-
    This function is preferred over nng_recv, as it gives access to the message structure and eliminates both
+
    This function is preferred over nng_recv, as it gives access to the message structure and eliminates both
 a data copy and allocation.
    
 
    
 
    nng_socket_recv
    
-
    The nng_socket_send function receives a message asynchronously, using the nng_aio aio, over the socket s.
-On success, the received message can be retrieved from the aio using the nng_aio_get_msg function.
    
+
    The nng_socket_send function receives a message asynchronously, using the nng_aio aio, over the socket s.
+On success, the received message can be retrieved from the aio using the nng_aio_get_msg function.
    
 
    
 
    
   
@@ -1423,7 +1433,7 @@ Failure to do so will leak the memory.
    
 
    
 
    This is the preferred function to use for receiving data on a socket. While it does require a few extra
 steps on the part of the application, the lowest latencies and highest performance will be achieved by using
-this function instead of nng_recv or nng_recvmsg.
    
+this function instead of nng_recv or nng_recvmsg.
    
 
    
 
    Socket Options
    
 
    int nng_socket_get_bool(nng_socket s, const char *opt, bool *valp);
@@ -1448,16 +1458,16 @@ are available, whether they can be read or written, and the appropriate type to
   note
 
    
 
    Socket options are are used to tune the behavior of the higher level protocol. To change the options
-for an underlying transport, the option should be set on the dialer or listener instead of the socket.
    
+for an underlying transport, the option should be set on the dialer or listener instead of the socket.
    
 
 
    Common Options
    
 
    The following options are available for many protocols, and always use the same types and semantics described below.
    
 
    
-
-
-
+
+
+
-
+
@@ -1469,8 +1479,8 @@ for an underlying transport, the option should be set on the 
   note
 
    
-
    The NNG_OPT_RECONNMAXT, NNG_OPT_RECONNMINT, and NNG_OPT_RECVMAXSZ options are just the initial defaults that dialers
-(and for NNG_OPT_RECVMAXSZ also listeners)
+
    The NNG_OPT_RECONNMAXT, NNG_OPT_RECONNMINT, and NNG_OPT_RECVMAXSZ options are just the initial defaults that dialers
+(and for NNG_OPT_RECVMAXSZ also listeners)
 will use. After the dialer or listener is created, changes to the socket’s value will have no affect on that dialer or listener.
    Polling Socket Events
    
@@ -1496,7 +1506,7 @@ were available in previous versions of NNG.
    
   note
 
    
-
    These functions are not compatible with contexts.
    
+
    These functions are not compatible with contexts.
    
 
    
@@ -1513,7 +1523,7 @@ messages on the socket.
    
   tip
 
    
 
    Using these functions will force the socket to perform extra system calls, and thus
-have a negative impact on performance and latency. It is preferable to use asynchronous I/O
+have a negative impact on performance and latency. It is preferable to use asynchronous I/O
 when possible.
    
 
    Examples
    
@@ -1521,7 +1531,7 @@ when possible.
    nng_socket s = NNG_SOCKET_INITIALIZER;
 
    Example 2: Publishing a Timestamp
    
-
    This example demonstrates the use of nng_aio, nng_socket_send, and nng_sleep_aio to
+
    This example demonstrates the use of nng_aio, nng_socket_send, and nng_sleep_aio to
 build a service that publishes a timestamp at one second intervals. Error handling is elided for the
 sake of clarity.
    #include <stdlib.h>
@@ -1572,7 +1582,7 @@ int main(int argc, char **argv) {
 }
 
    Example 3: Watching a Periodic Timestamp
    
-
    This example demonstrates the use of nng_aio, nng_socket_recv, to build a client to
+
    This example demonstrates the use of nng_aio, nng_socket_recv, to build a client to
 watch for messages received from the service created in Example 2.
 Error handling is elided for the sake of clarity.
    #include <stdlib.h>
@@ -1617,9 +1627,14 @@ int main(int argc, char **argv) {
     }
 }
 
    
+
+
@@ -1694,33 +1709,33 @@ int main(int argc, char **argv) {
 
    Contexts
    Contexts  in Scalability Protocols provide for isolation of protocol-specific
 state machines and associated data, allowing multiple concurrent state machines (or transactions)
-to coexist on a single socket.
    
-
    For example, a REP server may wish to allow many requests to be serviced concurrently,
+to coexist on a single socket.
    
+
    For example, a REP server may wish to allow many requests to be serviced concurrently,
 even though some jobs may take significant time to process. Contexts provide for this ability.
    Not all protocols have contexts, because many protocols simply have no state to manage.
 The following protocols support contexts:
    For these protocols, the socket will also have a single, default, context that is used when
 performing send or receive operations on the socket directly.
    Other protocols are stateless, at least with respect to message processing, and have no use for
-contexts. For the same reason, raw mode sockets do not support contexts.
    
+contexts. For the same reason, raw mode sockets do not support contexts.
    
 
    
   
   tip
 
    
-
    Developers with experience with [libnanomsg] may be used to using raw sockets for concurrency.
+
    Developers with experience with [libnanomsg] may be used to using raw sockets for concurrency.
 Contexts provide a superior solution, as they are much easier to use, less error prone, and allow
 for easy control of the amount of concurrency used on any given socket.
    
 
    One drawback of contexts is that they cannot be used with file descriptor polling using
-nng_socket_get_recv_poll_fd or nng_socket_get_send_poll_fd.
    
+nng_socket_get_recv_poll_fd or nng_socket_get_send_poll_fd.
    Context Structure
    #define NNG_CTX_INITIALIZER // opaque value
 
@@ -1733,15 +1748,15 @@ to ensure that it cannot be confused with a valid open context.
    
 
    Creating a Context
    
 
    int nng_ctx_open(nng_ctx *ctxp, nng_socket s);
 
    
-
    The nng_ctx_open function creates a separate context to be used with the socket s,
+
    The nng_ctx_open function creates a separate context to be used with the socket s,
 and returns it at the location pointed by ctxp.
    
 
    Context Identity
    
 
    int nng_ctx_id(nng_ctx c);
 
    
 
    The nng_ctx_id function returns a positive identifier for the context c if it is valid.
 Otherwise it returns -1.
    
-
    A context is considered valid if it was ever opened with nng_ctx_open function.
-Contexts that are allocated on the stack or statically should be initialized with the macro NNG_CTX_INITIALIZER
+
    A context is considered valid if it was ever opened with nng_ctx_open function.
+Contexts that are allocated on the stack or statically should be initialized with the macro NNG_CTX_INITIALIZER
 to ensure that they cannot be confused with a valid context before they are opened.
    
 
    Closing a Context
    
 
    int nng_ctx_close(nng_ctx ctx);
@@ -1757,7 +1772,7 @@ call is executed may also return with an NNG_ECLOSED result.
    
   
   note
 
    
-
    Closing the socket associated with ctx using nng_socket_close also closes this context.
    
+
    Closing the socket associated with ctx using nng_socket_close also closes this context.
    
 
 
    Sending Messages
    
 
    int nng_ctx_sendmsg(nng_ctx ctx, nng_msg *msg, int flags);
@@ -1773,21 +1788,21 @@ messages over the socket s. The differences in their behaviors are as f
 
    The semantics of what sending a message means varies from protocol to
 protocol, so examination of the protocol documentation is encouraged.
 Additionally, some protocols may not support sending at all or may require other pre-conditions first.
-(For example, REP sockets cannot normally send data until they have first received a request,
-while SUB sockets can only receive data and never send it.)
    
+(For example, REP sockets cannot normally send data until they have first received a request,
+while SUB sockets can only receive data and never send it.)
    
 
 
    nng_ctx_sendmsg
    
 
    The nng_ctx_sendmsg function sends the msg over the context ctx.
    
 
    If this function returns zero, then the socket will dispose of msg when the transmission is complete.
 If the function returns a non-zero status, then the call retains the responsibility for disposing of msg.
    
-
    The flags can contain the value NNG_FLAG_NONBLOCK, indicating that the function should not wait if the socket
-cannot accept more data for sending. In such a case, it will return NNG_EAGAIN.
    
+
    The flags can contain the value NNG_FLAG_NONBLOCK, indicating that the function should not wait if the socket
+cannot accept more data for sending. In such a case, it will return NNG_EAGAIN.
    
 
    nng_ctx_send
    
-
    The nng_ctx_send function sends a message asynchronously, using the nng_aio aio, over the context ctx.
-The message to send must have been set on aio using the nng_aio_set_msg function.
    
+
    The nng_ctx_send function sends a message asynchronously, using the nng_aio aio, over the context ctx.
+The message to send must have been set on aio using the nng_aio_set_msg function.
    
 
    If the operation completes successfully, then the context will have disposed of the message.
 However, if it fails, then callback of aio should arrange for a final disposition of the message.
-(The message can be retrieved from aio with nng_aio_get_msg.)
    
+(The message can be retrieved from aio with nng_aio_get_msg.)
    
 
    Note that callback associated with aio may be called before the message is finally delivered to the recipient.
 For example, the message may be sitting in queue, or located in TCP buffers, or even in flight.
    
 
    
@@ -1797,7 +1812,7 @@ For example, the message may be sitting in queue, or located in TCP buffers, or
 
    
 
    This is the preferred function to use for sending data on a context. While it does require a few extra
 steps on the part of the application, the lowest latencies and highest performance will be achieved by using
-this function instead of nng_ctx_sendmsg.
    
+this function instead of nng_ctx_sendmsg.
    
 
    
 
    Receiving Messages
    
 
    int nng_ctx_recvmsg(nng_ctx ctx, nng_msg **msgp, int flags);
@@ -1813,15 +1828,15 @@ messages over the context ctx. The differences in their behaviors are a
 
    The semantics of what receiving a message means varies from protocol to
 protocol, so examination of the protocol documentation is encouraged.
 Additionally, some protocols may not support receiving at all or may require other pre-conditions first.
-(For example, REQ sockets cannot normally receive data until they have first sent a request.)
    
+(For example, REQ sockets cannot normally receive data until they have first sent a request.)
    
 
 
    nng_recvmsg
    
-
    The nng_ctx_recvmsg function receives a message and stores a pointer to the nng_msg for that message in msgp.
    
-
    The flags can contain the value NNG_FLAG_NONBLOCK, indicating that the function should not wait if the socket
-has no messages available to receive. In such a case, it will return NNG_EAGAIN.
    
+
    The nng_ctx_recvmsg function receives a message and stores a pointer to the nng_msg for that message in msgp.
    
+
    The flags can contain the value NNG_FLAG_NONBLOCK, indicating that the function should not wait if the socket
+has no messages available to receive. In such a case, it will return NNG_EAGAIN.
    
 
    nng_socket_recv
    
-
    The nng_ctx_send function receives a message asynchronously, using the nng_aio aio, over the context ctx.
-On success, the received message can be retrieved from the aio using the nng_aio_get_msg function.
    
+
    The nng_ctx_send function receives a message asynchronously, using the nng_aio aio, over the context ctx.
+On success, the received message can be retrieved from the aio using the nng_aio_get_msg function.
    
 
    
 
    
   
@@ -1837,7 +1852,7 @@ Failure to do so will leak the memory.
    
 
    
 
    This is the preferred function to use for receiving data on a context. While it does require a few extra
 steps on the part of the application, the lowest latencies and highest performance will be achieved by using
-this function instead of nng_ctx_recvmsg.
    
+this function instead of nng_ctx_recvmsg.
    
 
    
 
    Context Options
    
 
    int nng_ctx_get_bool(nng_ctx ctx, const char *opt, bool *valp);
@@ -1862,7 +1877,7 @@ are available for contexts, whether they can be read or written, and the appropr
 
    These examples show building blocks for a concurrent service based on contexts.
    
 
    Example 1: Context Echo Server
    
 
    The following program fragment demonstrates the use of contexts to implement
-a concurrent REP service that simply echos messages back
+a concurrent REP service that simply echos messages back
 to the sender.
    
 
    struct echo_context {
     nng_ctx ctx;
@@ -1900,8 +1915,8 @@ echo(void *arg)
 
    
 
    Example 2: Starting the Echo Service
    
 
    Given the above fragment, the following example shows setting up the service.
-It assumes that the socket has already been
-created and any transports set up as well with functions such as nng_dial or nng_listen.
    
+It assumes that the socket has already been
+created and any transports set up as well with functions such as nng_dial or nng_listen.
    
 
    
 #define CONCURRENCY 1024
 
@@ -1919,9 +1934,14 @@ start_echo_service(nng_socket rep_socket)
     }
 }
 
    
+
 
 
 
+
 
 
 
@@ -2019,7 +2039,7 @@ accurate type checks in functions passing values of this type.
    
 However it is possible to access a pipe when more information about the
 source of a message is needed, or when more control is required over message delivery.
    
 
-
    Pipe objects are created by dialers and and listeners.
    
+
    Pipe objects are created by dialers and and listeners.
    
 
    Initialization
    
 
    A pipe may be initialized using the macro NNG_PIPE_INITIALIZER
 before it is opened, to prevent confusion with valid open pipes.
    
@@ -2038,7 +2058,7 @@ Otherwise it returns -1.
    
 
    
 
    A pipe is considered valid if it was ever created by the socket.
 Pipes that are allocated on the stack or statically should be initialized with the macro
-NNG_PIPE_INITIALIZER to ensure that they cannot be confused with a valid pipe.
    
+NNG_PIPE_INITIALIZER to ensure that they cannot be confused with a valid pipe.
    
 
 
    Closing a Pipe
    
 
    nng_err nng_pipe_close(nng_pipe p);
@@ -2046,7 +2066,7 @@ Pipes that are allocated on the stack or statically should be initialized with t
 
    The nng_pipe_close function closes the supplied pipe, p.
 Messages that have been submitted for sending may be flushed or delivered,
 depending upon the transport.
    
-
    Further attempts to use the pipe after this call returns will result in NNG_ECLOSED.
    
+
    Further attempts to use the pipe after this call returns will result in NNG_ECLOSED.
    
 
    
 
    
   
@@ -2063,7 +2083,7 @@ nng_socket nng_pipe_socket(nng_pipe p);
 
    
 
 
-These functions return the socket, dialer, or listener that created or owns the pipe.
    
+These functions return the socket, dialer, or listener that created or owns the pipe.
    
 
    If the pipe was does not have an associated dialer or listener, then the associated will
 return [NNG_DIALER_INITIALIZER] or [NNG_LISTENER_INITIALIZER], as appropriate, and
 either [nng_dialer_id] or [nng_listener_id] for the returned object will return -1.
    
@@ -2073,7 +2093,7 @@ either [nng_dialer_id] or [nng_listener_id] for the re
   note
 
    
 
    The socket, or the endpoint, returned by these functions may be in the process of closing,
-and might not be further usable as a result. (Other functions will result in NNG_ECLOSED.)
    
+and might not be further usable as a result. (Other functions will result in NNG_ECLOSED.)
    
 
    
 
    Pipe Options
    
 
    nng_err nng_pipe_get_bool(nng_pipe p, const char *opt, bool *valp);
@@ -2099,8 +2119,8 @@ referenced by valp.
    
 
    These functions access an option as a specific type. The transport layer will have details about which options
 are available, and which type they may be accessed using.
    
 
    In the case of nng_pipe_get_string, the underlying string may only be valid for as long as the pipe is valid.
-Thus, this function can only be safely called in a pipe event callback set up with nng_pipe_notify.
    
-
    The nng_pipe_get_strdup function is like nng_pipe_get_string, but makes a copy into a newly allocated buffer, so that the string must be freed by the caller using nng_strfree.
    
+Thus, this function can only be safely called in a pipe event callback set up with nng_pipe_notify.
    
+
    The nng_pipe_get_strdup function is like nng_pipe_get_string, but makes a copy into a newly allocated buffer, so that the string must be freed by the caller using nng_strfree.
    
 
    The nng_pipe_get_strcpy function is also like nng_pipe_get_string, but it makes a copy into a buffer
 supplied by the caller. The buffer is passed in val, and the size of the buffer is passed in len.
 The value of len must be large enough to hold the string and the terminating zero byte.
    
@@ -2127,7 +2147,7 @@ Each event may have at most one callback registered.
 Registering a callback implicitly unregisters any previously registered.
    
 
    The following pipe events are supported:
    
 
    OptionTypeDescription
    NNG_OPT_MAXTTLintMaximum number of traversals across an nng_device device, to prevent forwarding loops. May be 1-255, inclusive. Normally defaults to 8.
    NNG_OPT_RECONNMAXTnng_durationMaximum time dialers will delay before trying after failing to connect.
    NNG_OPT_RECONNMINTnng_durationMinimum time dialers will delay before trying after failing to connect.
    NNG_OPT_MAXTTLintMaximum number of traversals across an nng_device device, to prevent forwarding loops. May be 1-255, inclusive. Normally defaults to 8.
    NNG_OPT_RECONNMAXTnng_durationMaximum time dialers will delay before trying after failing to connect.
    NNG_OPT_RECONNMINTnng_durationMinimum time dialers will delay before trying after failing to connect.
    
 
    NNG_OPT_RECVBUFintMaximum number of messages (0-8192) to buffer locally when receiving.
    NNG_OPT_RECVMAXSZsize_tMaximum message size acceptable for receiving. Zero means unlimited. Intended to prevent remote abuse. Can be tuned independently on dialers and listeners.
    NNG_OPT_RECVMAXSZsize_tMaximum message size acceptable for receiving. Zero means unlimited. Intended to prevent remote abuse. Can be tuned independently on dialers and listeners.
    
 
    NNG_OPT_RECVTIMEOnng_durationDefault timeout (ms) for receiving messages.
    
 
    NNG_OPT_SENDBUFintMaximum number of messages (0-8192) to buffer when sending messages.
    
 
    NNG_OPT_SENDTIMEOnng_durationDefault timeout (ms) for sending messages.
    
 
 
   
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
    
-
+
    EventDescription
    NNG_PIPE_EV_ADD_PREThis event occurs after a connection and negotiation has completed, but before the pipe is added to the socket. If the pipe is closed (using nng_pipe_close) at this point, the socket will never see the pipe, and no further events will occur for the given pipe.
    NNG_PIPE_EV_ADD_PREThis event occurs after a connection and negotiation has completed, but before the pipe is added to the socket. If the pipe is closed (using nng_pipe_close) at this point, the socket will never see the pipe, and no further events will occur for the given pipe.
    
 
    NNG_PIPE_EV_ADD_POSTThis event occurs after the pipe is fully added to the socket. Prior to this time, it is not possible to communicate over the pipe with the socket.
    
 
    NNG_PIPE_EV_REM_POSTThis event occurs after the pipe has been removed from the socket. The underlying transport may be closed at this point, and it is not possible communicate using this pipe.
    
 
    
@@ -2145,7 +2165,7 @@ Doing so would thus result in a deadlock.
    
   
   tip
 
    
-
    The callback cb may close a pipe for any reason by simply closing it using nng_pipe_close.
+
    The callback cb may close a pipe for any reason by simply closing it using nng_pipe_close.
 For example, this might be done to prevent an unauthorized peer from connecting to the socket,
 if an authorization check made during NNG_PIPE_EV_ADD_PRE fails.
    
 
    
@@ -2156,9 +2176,14 @@ if an authorization check made during NNG_PIPE_EV_ADD_PRE fails.
    
 
    This function ignores invalid values for ev.
    
 
+
 
 
 
+
 
 
 
@@ -2243,8 +2268,8 @@ at least size bytes, and returns a pointer to it.
 The memory will be 64-bit aligned.
 Note that the memory may have random data in it, just like with malloc.
    
 
    If memory cannot be allocated for any reason, then NULL will be returned.
-Applications that experience this should treat this like NNG_ENOMEM.
    
-
    Memory returned by nng_alloc should be freed when no longer needed using nng_free.
    
+Applications that experience this should treat this like NNG_ENOMEM.
    
+
    Memory returned by nng_alloc should be freed when no longer needed using nng_free.
    
 
    
 
    
   
@@ -2257,30 +2282,35 @@ other unpredictable behavior.
    
 
    Deallocate Memory
    
 
    void nng_free(void *ptr, size_t size);
 
    
-
    The nng_free function deallocates memory previously allocated by nng_alloc.
    
+
    The nng_free function deallocates memory previously allocated by nng_alloc.
    
 
    The size argument must exactly match the size argument that was supplied to
-nng_alloc when the memory was allocated.
    
+nng_alloc when the memory was allocated.
    
 
    Duplicate String
    
 
    char *nng_strdup(const char *src);
 
    
 
    The nng_strdup duplicates the string src and returns it.
    
-
    This is logically equivalent to using nng_alloc
+
    This is logically equivalent to using nng_alloc
 to allocate a region of memory of strlen(s) + 1 bytes, and then
 using strcpy to copy the string into the destination before
 returning it.
    
 
    The returned string should be deallocated with
-nng_strfree, or may be deallocated using the
-nng_free using the length of the returned string plus
+nng_strfree, or may be deallocated using the
+nng_free using the length of the returned string plus
 one (for the NUL terminating byte).
    
 
    Free String
    
 
    void nng_strfree(char *str);
 
    
 
    The nng_strfree function is a convenience function that
-can be used to deallocate strings allocated with nng_strdup.
    
+can be used to deallocate strings allocated with nng_strdup.
    
 
    It is effectively the same as nng_free(strlen(str) + 1).
    
+
 
 
 
+
 
 
 
@@ -2415,26 +2445,31 @@ underlying system.
    
 
    Wait Asynchronously
    
 
    void nng_sleep_aio(nng_duration msec, nng_aio *aio);
 
    
-
    It is possible to wait as the action on an nng_aio, which in effect
+
    It is possible to wait as the action on an nng_aio, which in effect
 acts like scheduling a callback to run after a specified period of time.
    
 
    The nng_sleep_aio function provides this capability.
 After msec milliseconds have passed, then aio’s callback will be executed.
 If this sleep waits without interruption, and then completes, the result from
-nng_aio_result will be zero.
    
+nng_aio_result will be zero.
    
 
    
 
    
   
   note
 
    
-
    If a timeout shorter than msec is set on aio using nng_aio_set_timeout,
-then the sleep will wake up early, with a result code of NNG_ETIMEDOUT.
    
+
    If a timeout shorter than msec is set on aio using nng_aio_set_timeout,
+then the sleep will wake up early, with a result code of NNG_ETIMEDOUT.
    
 
    
 
    See Also
    
-
    Asynchronous Operations,
-Synchronization
    
+
    Asynchronous Operations,
+Synchronization
    
+
 
 
 
+
 
 
 
@@ -2556,7 +2591,7 @@ the query-information (the part following a ‘?’) and fragment
 if they are not. The returned string will not include the leading ‘?’ or ‘#’
 characters.
    
 
    Note that any strings returned by these functions are only valid until
-url is freed with nng_url_free.
    
+url is freed with nng_url_free.
    
 
    Format a URL
    
 
    int nng_url_sprintf(char *buf, size_t bufsz, const nng_url *url);
 
    
@@ -2585,7 +2620,7 @@ and creates a dynamically allocated nng_url, returning it in ur
   
   important
 
    
-
    Only nng_url_free should be used to deallocate nng_url objects.
    
+
    Only nng_url_free should be used to deallocate nng_url objects.
    
 
    
 
    Clone a URL
    
 
    int nng_url_clone(nng_url **dup, const nng_url *url);
@@ -2595,8 +2630,8 @@ and creates a dynamically allocated nng_url, returning it in ur
 
    void nng_url_free(nng_url *url);
 
    
 
    The nng_url_free function destroy an nng_url object created with
-either nng_url_parse or nng_url_free.
    
-
    This is the only correct way to destroy an nng_url object.
    
+either nng_url_parse or nng_url_free.
    
+
    This is the only correct way to destroy an nng_url object.
    
 
    Update a URL Port
    
 
    void nng_url_resolve_port(nng_url *url, uint32_t port);
 
    
@@ -2608,9 +2643,14 @@ a URL with a new port. This will have no effect if the URL already has a non-zer
 
    See Also
    
 
    More information about Universal Resource Locators can be found in
 RFC 3986.
    
+
 
 
 
+
 
 
 
@@ -2686,7 +2726,7 @@ a URL with a new port. This will have no effect if the URL already has a non-zer
 
    In order to obtain significant scalability, with low-latency, and minimal
 overheads, NNG supports performing operations asynchronously.
    
 
    One way that applications can perform work asynchronously and concurrently
-is by using threads, but threads carry significant resource overheads
+is by using threads, but threads carry significant resource overheads
 and frequently there are limits on the number that can easily be created.
    
 
    Additionally, with most network applications, the flow of execution will spend
 the bulk of its time waiting for traffic from a peer.
    
@@ -2711,17 +2751,17 @@ can only be used with a single operation at a time.
    
 Instead the application registers a callback function to be executed
 when the operation is complete (whether successfully or not).
 This callback will be executed exactly once.
    
-
    The asynchronous I/O framework also supports cancellation of
+
    The asynchronous I/O framework also supports cancellation of
 operations that are already in progress as well setting a maximum
-timeout for them to complete.
    
-
    It is also possible to initiate an asynchronous operation, and wait for it to
+timeout for them to complete.
    
+
    It is also possible to initiate an asynchronous operation, and wait for it to
 complete, creating a synchronous flow from an asynchronous one.
    
 
    Create Handle
    
 
    nng_err nng_aio_alloc(nng_aio **aiop, void (*callb)(void *), void *arg);
 
    
-
    The nng_aio_alloc function creates an nng_aio object, with the
+
    The nng_aio_alloc function creates an nng_aio object, with the
 callback callb taking the argument arg, and returns it in aiop.
    
-
    If this succeeds, the function returns zero. Otherwise it may return NNG_ENOMEM.
    
+
    If this succeeds, the function returns zero. Otherwise it may return NNG_ENOMEM.
    
 
    
 
    
   
@@ -2729,15 +2769,15 @@ complete, creating a synchronous flow from an asynchronous one.
    
 
    
 
    The arg should normally be a structure that contains a pointer to the aiop,
 or from which it can be located. This allows callb to check the handle for
-success using nng_aio_result, as well access other properties of aiop.
    
+success using nng_aio_result, as well access other properties of aiop.
    
 
    
 
    
 
    
   
   tip
 
    
-
    The callb may be executed on another thread, so it may be necessary to use
-synchronization methods in callb to avoid data races.
    
+
    The callb may be executed on another thread, so it may be necessary to use
+synchronization methods in callb to avoid data races.
    
 
    
 
    Destroy Handle
    
 
    void nng_aio_free(nng_aio *aio);
@@ -2746,7 +2786,7 @@ void nng_aio_reap(nng_aio *aio);
 
    The nng_aio_free handle destroys the handle aio, waiting for any operations
 and associated callbacks to complete before doing so.
    
 
    The nng_aio_reap handle destroys the handle aio asynchronously, using a reaper
-thread to do so. It does not wait for the object to be destroyed. Thus this function
+thread to do so. It does not wait for the object to be destroyed. Thus this function
 is safe to call from aio’s own callback.
    
 
    
 
    
@@ -2769,13 +2809,13 @@ If the operation is successfully canceled or aborted, then the callback
 will still be called.
    
 
    The nng_aio_abort function aborts the operation associated with aio
 and returns immediately without waiting. If cancellation was successful,
-then nng_aio_result will return err.
    
+then nng_aio_result will return err.
    
 
    The nng_aio_cancel function acts like nng_aio_abort, but uses the error code
-NNG_ECANCELED.
    
-
    The nng_aio_stop function aborts the aio operation with NNG_ESTOPPED,
+NNG_ECANCELED.
    
+
    The nng_aio_stop function aborts the aio operation with NNG_ESTOPPED,
 and then waits the operation and any associated callback to complete.
 This function also marks aio itself permanently stopped, so that any
-new operations scheduled by I/O providers using nng_aio_start
+new operations scheduled by I/O providers using nng_aio_start
 return false. Thus this function should be used to teardown operations.
    
 
    
 
    
@@ -2784,7 +2824,7 @@ return false. Thus this function should be used to teardown operations.
    
 
    
 
    When multiple asynchronous I/O handles are in use and need to be
 deallocated, it is safest to stop all of them using nng_aio_stop,
-before deallocating any of them with nng_aio_free,
+before deallocating any of them with nng_aio_free,
 particularly if the callbacks might attempt to reschedule further operations.
    
 
    
 
    Set Timeout
    
@@ -2795,15 +2835,15 @@ void nng_aio_set_expire(nng_aio *aio, nng_time expiration);
 for the asynchronous operation associated with aio.
 This causes a timer to be started when the operation is actually started.
 If the timer expires before the operation is completed, then it is
-aborted with an error of NNG_ETIMEDOUT.
-The timeout duration is specified as a relative number of milliseconds.
    
-
    If the timeout is NNG_DURATION_INFINITE, then no timeout is used.
-If the timeout is NNG_DURATION_DEFAULT, then a “default” or socket-specific
+aborted with an error of NNG_ETIMEDOUT.
+The timeout duration is specified as a relative number of milliseconds.
    
+
    If the timeout is NNG_DURATION_INFINITE, then no timeout is used.
+If the timeout is NNG_DURATION_DEFAULT, then a “default” or socket-specific
 timeout is used.
-(This is frequently the same as NNG_DURATION_INFINITE.)
    
+(This is frequently the same as NNG_DURATION_INFINITE.)
    
 
    The nng_aio_set_expire function is similar to nng_aio_set_timeout, but sets
 an expiration time based on the system clock. The expiration
-time is a clock timestamp, such as would be returned by nng_clock.
    
+time is a clock timestamp, such as would be returned by nng_clock.
    
 
    Wait for Completion
    
 
    void nng_aio_wait(nng_aio *aio);
 
    
@@ -2817,7 +2857,7 @@ function will not be called until the callback has completed.
    
   important
 
    
 
    The nng_aio_wait function should never be called from a function that itself
-is a callback of an nng_aio, either this one or any other.
+is a callback of an nng_aio, either this one or any other.
 Doing so may result in a deadlock.
    
 
    
 
    Test for Completion
    
@@ -2825,7 +2865,7 @@ Doing so may result in a deadlock.
    
 
    
 
    The nng_aio_busy function returns true if the aio is currently busy performing an
 operation or is executing a completion callback. Otherwise it return false.
-This is the same test used internally by nng_aio_wait.
    
+This is the same test used internally by nng_aio_wait.
    
 
    
 
    
   
@@ -2841,7 +2881,7 @@ size_t nng_aio_count(nng_aio *aio);
 
    The nng_aio_result function returns the result of the operation associated
 with the handle aio.
 If the operation was successful, then 0 is returned.
-Otherwise a non-zero error code, such as NNG_ECANCELED or NNG_ETIMEDOUT, is returned.
    
+Otherwise a non-zero error code, such as NNG_ECANCELED or NNG_ETIMEDOUT, is returned.
    
 
    For operations that transfer data, nng_aio_count returns the
 number of bytes transferred by the operation associated with the handle aio.
 Operations that do not transfer data, or do not keep a count, may return zero for this function.
    
@@ -2852,13 +2892,13 @@ Operations that do not transfer data, or do not keep a count, may return zero fo
 
    
 
    The return value from these functions is undefined if the operation has not completed yet.
 Either call these from the handle’s completion callback, or after waiting for the
-operation to complete with nng_aio_wait.
    
+operation to complete with nng_aio_wait.
    
 
    
 
    Messages
    
 
    nng_msg *nng_aio_get_msg(nng_aio *aio);
 void nng_aio_set_msg(nng_aio *aio, nng_msg *msg);
 
    
-
    The nng_aio_get_msg and nng_aio_set_msg functions retrieve and store a message
+
    The nng_aio_get_msg and nng_aio_set_msg functions retrieve and store a message
 in aio.
 For example, if a function to receive data is called, that function can generally be expected
 to store a message on the associated aio, for the application to retrieve with
@@ -2884,7 +2924,7 @@ then no message is stored on the aio.
    
 
 int nng_aio_set_iov(nng_aio *aio, unsigned int niov, nng_iov *iov);
 
    
-
    For some operations, the unit of data transferred is not a message, but
+
    For some operations, the unit of data transferred is not a message, but
 rather a stream of bytes.
    
 
    For these operations, an array of niov nng_iov structures can be passed to
 the nng_aio_set_iov function to provide a scatter/gather array of
@@ -2901,14 +2941,14 @@ The values pointed to by the iov_buf members are not copie
 
    Most functions using nng_iov do not guarantee to transfer all of the data that they
 are requested to. To be sure that correct amount of data is transferred, as well as to
 start an attempt to complete any partial transfer, check the amount of data transferred by
-calling nng_aio_count.
    
+calling nng_aio_count.
    
 
 
    Inputs and Outputs
    
 
    void nng_aio_set_input(nng_aio *aio, unsigned int index, void *param);
 void *nng_aio_get_output(nng_aio *aio, unsigned int index);
 
    
 
    Asynchronous operations can take additional input parameters, and
-provide additional result outputs besides the result code.
    
+provide additional result outputs besides the result code.
    
 
    The nng_aio_set_input function sets the input parameter at index
 to param for the operation associated with aio.
    
 
    The nng_aio_get_output function returns the output result at index
@@ -2944,7 +2984,7 @@ in use by an active asynchronous operation.
    
 void nng_aio_set_iov(nng_aio *aio, unsigned nio, const nng_iov *iov);
 
    
 
    
-Some asynchronous operations, such as those dealing with streams, use scatter or gather
+Some asynchronous operations, such as those dealing with streams, use scatter or gather
 vectors, where data to be transferred is either gathered from multiple separate regions of memory, or
 scattered into separate regions of memory. For example a message may have a header located at one location
 in memory, and a payload located in another.
    
@@ -2954,16 +2994,21 @@ the elements in iov. For each of these, the segment of size iov_len
 on the stack or another temporary location. The locations referenced by it, must remain valid for
 the duration of the operation, of course.
    
 
    Note that many of these operations are not guaranteed to perform a full transfer of data, so even a
-successful operation should check the amount of data actually transferred using nng_aio_count,
+successful operation should check the amount of data actually transferred using nng_aio_count,
 and if necessary resubmit the operation with a suitably updated vector of nng_iov using this function.
    
 
    See Also
    
-
    Synchronization,
-Threads,
-Streams,
-Time
    
+
    Synchronization,
+Threads,
+Streams,
+Time
    
+
 
 
 
+
 
 
 
@@ -3037,32 +3082,32 @@ and if necessary resubmit the operation with a suitably updated vector of 
 
 
    Synchronization Primitives
    
 
    In order to allow safely accessing shared state, or to allow coordination between
-different threads, NNG provides synchronization primitives in the
+different threads, NNG provides synchronization primitives in the
 form of mutual exclusion locks and condition variables.
    
 
    Correct use of these primitives will be needed when accessing shared state from
-threads, or from callback functions associated with asynchronous operations.
+threads, or from callback functions associated with asynchronous operations.
 (The need to do this in callbacks is because the callback may be executed under
 a task thread other than the submitting thread.)
    
 
    Mutual Exclusion Lock
    
 
    typedef struct nng_mtx nng_mtx;
 
    
 
    Mutual exclusion locks, or mutex locks, represented by the nng_mtx structure,
-allow only a single thread to lock “own” the lock, acquired by nng_mtx_lock.
+allow only a single thread to lock “own” the lock, acquired by nng_mtx_lock.
 Any other thread trying to acquire the same mutex will wait until the owner has released the mutex
-by calling nng_mtx_unlock.
    
+by calling nng_mtx_unlock.
    
 
    Creating a Mutex
    
 
    int nng_mutx_alloc(nng_mt **mtxp);
 
    
 
    A mutex can be created by allocating one with nng_mtx_lock.
 On success, a pointer to the mutex is returned through mtxp.
 This function can fail due to insufficient memory or resources, in which
-case it will return NNG_ENOMEM. Otherwise it will succeed and return zero.
    
+case it will return NNG_ENOMEM. Otherwise it will succeed and return zero.
    
 
    Destroying a Mutex
    
 
    void nng_mtx_free(nng_mtx *mtx);
 
    
 
    When no longer needed, a mutex can be deallocated and its resources returned
 to the caller, by calling nng_mtx_free. The mutex must not be locked
-by any thread when calling this function.
    
+by any thread when calling this function.
    
 
    Acquiring a Mutex
    
 
    void nng_mtx_lock(nng_mtx *mtx);
 
    
@@ -3080,7 +3125,7 @@ If it does attempt to do so, the result will be a single party deadlock.
    
 
    void nng_mtx_unlock(nng_mtx *mtx);
 
    
 
    The nng_mtx_unlock function releases a mutex that the calling thread has previously
-acquired with nng_mtx_lock.
    
+acquired with nng_mtx_lock.
    
 
    
 
    
   
@@ -3093,7 +3138,7 @@ that acquired the mutex to begin with.
    
 
    typedef struct nng_cv nng_cv;
 
    
 
    The nng_cv structure implements a condition variable, associated with the
-the mutex mtx which was supplied when it was created.
    
+the mutex mtx which was supplied when it was created.
    
 
    Condition variables provide for a way to wait on an arbitrary condition, and to be woken
 when the condition is signaled.
 The mutex is dropped while the caller is asleep, and reacquired atomically when the caller
@@ -3121,16 +3166,16 @@ void nng_cv_wait(nng_cv *cv);
 
    
 
    The nng_cv_until and nng_cv_wait functions put the caller to sleep until the condition
 variable cv is signaled, or (in the case of nng_cv_until), the specified time when
-(as determined by nng_clock is reached.
    
+(as determined by nng_clock is reached.
    
 
    While nng_cv_wait never fails and so has no return value, the nng_cv_until function can
-return NNG_ETIMEDOUT if the time is reached before condition cv is signaled by
-either nng_cv_wake or nng_cv_wake1.
    
+return NNG_ETIMEDOUT if the time is reached before condition cv is signaled by
+either nng_cv_wake or nng_cv_wake1.
    
 
    Signaling the Condition
    
 
    void nng_cv_wake(nng_cv *cv);
 void nng_cv_wake1(nng_cv *cv);
 
    
 
    The nng_cv_wake and nng_cv_wake1 functions wake threads waiting in
-nng_cv_until or nng_cv_wait.
+nng_cv_until or nng_cv_wait.
 The difference between these functions is that
 nng_cv_wake will wake every thread, whereas nng_cv_wake1 will wake up exactly
 one thread (which may be chosen randomly).
    
@@ -3169,12 +3214,17 @@ nng_cv_wake(cv);
 nng_mtx_unlock(m);
 
    
 
    See Also
    
-
    Threads,
-Time,
-Asynchronous I/O
    
+
    Threads,
+Time,
+Asynchronous I/O
    
+
 
 
 
+
 
 
 
@@ -3282,7 +3332,7 @@ Blocking NNG library calls can however be made safely from NNG
 
    The system may impose limits on the number of threads that can be created.
 Typically applications should not create more than a dozen of these.
 If greater concurrency or scalability is needed, consider instead using
-an asynchronous model using nng_aio structures.
    
+an asynchronous model using nng_aio structures.
    
 
 
    Thread Structure
    
 
    typedef struct nng_thread nng_thread;
@@ -3290,7 +3340,7 @@ an asynchronous model using <
 
    The nng_thread structure represents a thread, which is a single execution context.
 A given thread will have its own stack, and CPU registers. However global state, as well
 as values allocated on the heap, will be shared and accessible to all threads in the system
-(See the Synchronization chapter for functions to help with data sharing between different threads.)
    
+(See the Synchronization chapter for functions to help with data sharing between different threads.)
    
 
    Multiple threads can be thought of as running concurrently, even though
 they might not actually do so.
    
 
    I/O operations that block (i.e. wait for completion) will block the
@@ -3317,11 +3367,16 @@ It also has the effect of blocking execution in the caller until thr ha
 to provide a name for the thread. This may change how the thread is represented
 in debuggers. Not all platforms support setting the thread name.
    
 
    See Also
    
-
    Synchronization,
-Asynchronous Operations
    
+
    Synchronization,
+Asynchronous Operations
    
+
 
 
 
+
 
 
 
@@ -3636,7 +3691,7 @@ subject to change at any time and without notice.
    
 
    
 
    The nng_stats_get function takes a snapshot of the statistics for
 the system and returns it through the pointer statsp.
-This function may return NNG_ENOMEM if memory is exhausted, or NNG_ENOTSUP if the statistics
+This function may return NNG_ENOMEM if memory is exhausted, or NNG_ENOTSUP if the statistics
 support is not enabled in the build, but is otherwise expected to return zero.
    
 
    Freeing a Snapshot
    
 
    void nng_stats_free(nng_stat *stat);
@@ -3670,8 +3725,8 @@ const nng_stat *nng_stat_find_listener(const nng_stat *stat, nng_dialer listener
 const nng_stat *nng_stat_find_socket(const nng_stat *stat, nng_dialer socket);
 
    
 
    Sometimes it is easiest to search for a specific statistic, matching by name,
-or possibly to find the tree of statistics associated with a specific socket,
-dialer, or listener.
    
+or possibly to find the tree of statistics associated with a specific socket,
+dialer, or listener.
    
 
    The nng_stat_find functions are provided for this purpose.
    
 
    The nng_stat_find function returns the first statistic within the subtree of
 statistics stat, with the given name. If no such statistic can be found, NULL
@@ -3705,8 +3760,8 @@ statistics tree.
    
 The statistic is a counter that only increments.
 Usually the change in the value of the statistic is more interesting
 (as a rate) than the absolute value at any given time. The value should
-be obtained using nng_stat_value.
-The units will be given by the value returned from nng_stat_unit.
    
+be obtained using nng_stat_value.
+The units will be given by the value returned from nng_stat_unit.
    
 
 
  • 
 
    NNG_STAT_LEVEL: 
@@ -3715,25 +3770,25 @@ to a specific value at a specific time. For example, this may represent the
 number of messages currently queued for some operation, or the link speed
 of a network interface. Most often the absolute value is more interesting
 than the change in the value over time. Again the value can be obtained with
-nng_stat_value, and any appropriate unit of measurement
-with nng_stat_unit.
    
+nng_stat_value, and any appropriate unit of measurement
+with nng_stat_unit.
    
 
    • 
 
  • 
 
    NNG_STAT_STRING: 
 The statistic is a string, such as a name. The value
-of the string can be obtained with nng_stat_string.
+of the string can be obtained with nng_stat_string.
 The value of this string
-will remain valid until the snapshot is deallocated with nng_stats_free.
    
+will remain valid until the snapshot is deallocated with nng_stats_free.
    
 
    • 
 
  • 
 
    NNG_STAT_BOOLEAN: 
 The value of the statistic is a truth value (either true
-or false) and can be obtained with nng_stat_bool.
    
+or false) and can be obtained with nng_stat_bool.
    
 
    • 
 
  • 
 
    NNG_STAT_ID: 
 The value of the statistic is a numeric identifier, such as a socket
-identifier. The value can be obtained with nng_stat_value,
+identifier. The value can be obtained with nng_stat_value,
 and will be fixed for the life of the statistic.
    
 
    • 
 
@@ -3744,18 +3799,18 @@ bool nng_stat_bool(const nng_stat *stat);
 
    
 
    These functions return the value associated with the statistic.
    
 
    The nng_stat_value function returns the the numeric value for the statistic stat
-of type NNG_STAT_COUNTER, NNG_STAT_LEVEL, or NNG_STAT_ID.
+of type NNG_STAT_COUNTER, NNG_STAT_LEVEL, or NNG_STAT_ID.
 If stat is not one of these types, then it returns zero.
    
 
    The nng_stat_bool function returns the Boolean value (either true or false) for the statistic stat of
-type NNG_STAT_BOOLEAN. If the statistics is not of this type, then it returns false.
    
+type NNG_STAT_BOOLEAN. If the statistics is not of this type, then it returns false.
    
 
    The nng_stat_string function returns a pointer to a string value for the statistic stat,
-of type NNG_STAT_STRING. This string will remain valid until the snapshot that
-stat was collected with is deallocated with nng_stats_free. If the statistic
+of type NNG_STAT_STRING. This string will remain valid until the snapshot that
+stat was collected with is deallocated with nng_stats_free. If the statistic
 is not of type NNG_STAT_STRING, then NULL is returned.
    
 
    Statistic Units
    
 
    int nng_stat_unit(const nng_stat *stat);
 
    
-
    For statistics of type NNG_STAT_COUNTER or NNG_STAT_LEVEL,
+
    For statistics of type NNG_STAT_COUNTER or NNG_STAT_LEVEL,
 it is often useful to know what that quantity being reported measures.
 The following units may be returned from nng_stat_unit for such a statistic:
    
 
      
@@ -3771,12 +3826,17 @@ The following units may be returned from nng_stat_unit<
 
      Statistics have a timestamp indicating when the value was sampled,
 obtained via nng_stat_timestamp. The timestamp is given in
 in milliseconds since a reference time, and the reference time used
-here is the same reference time used for nng_clock.
      
+here is the same reference time used for nng_clock.
      
 
      See Also
      
-
      nng_clock
      
+
      nng_clock
      
+
 
 
 
+
 
 
 
@@ -3894,20 +3954,20 @@ as in diagnostic messages or log entries.
      
 NNG_EBUSY4Resource busy.
 NNG_ETIMEDOUT5Timed out. The operation took longer than the allotted time.
 NNG_ECONNREFUSED6Connection refused. Usually indicates the wrong address or a server is running.
-NNG_ECLOSED7Object closed. Typically the socket is closed.
+NNG_ECLOSED7Object closed. Typically the socket is closed.
 NNG_EAGAIN8Try again. Typcally for a non-blocking operation that might succeed later.
 NNG_ENOTSUP9Not supported. Perhaps the protocol or transport is not supported, or the operation is not not supported with the transport or protocol.
-NNG_EADDRINUSE10Address in use. The network address is already used by another process. Most often this is seen for listeners.
+NNG_EADDRINUSE10Address in use. The network address is already used by another process. Most often this is seen for listeners.
 NNG_ESTATE11Incorrect state. The operation cannot be performed in the current state, such as trying to send a response when no request has yet been received.
 NNG_ENOENT12Entry not found (no such object.) Can also indicate that a file does not exist.
 NNG_EPROTO13Protocol error. Typically this indicates incorrect messages over a network.
 NNG_EUNREACHABLE14Destination unreachable.
-NNG_EADDRINVAL15Address invalid. Like NNG_EINVAL, but only for network addresses.
+NNG_EADDRINVAL15Address invalid. Like NNG_EINVAL, but only for network addresses.
 NNG_EPERM16Permission denied.
 NNG_EMSGSIZE17Message too large.
 NNG_ECONNABORTED18Connection aborted. A connection attempt was aborted locally.
 NNG_ECONNRESET19Connection reset. The remote peer reset the connection unexpectedly.
-NNG_ECANCELED20Operation canceled. Typically as a result of nng_aio_cancel or similar.
+NNG_ECANCELED20Operation canceled. Typically as a result of nng_aio_cancel or similar.
 NNG_ENOFILES21Out of files. Either the destination file system cannot store files, or all available file handles are used.
 NNG_ENOSPC22Out of space. Destination table or filesystem is full.
 NNG_EEXIST23Resource already exists.
@@ -3917,14 +3977,19 @@ as in diagnostic messages or log entries.
      
 NNG_EPEERAUTH27Peer could not be authenticated.
 NNG_EBADTYPE30Incorrect type. A type-specific function was used for an object of the wrong type.
 NNG_ECONNSHUT31Connection shutdown. The connection was shut down and cannot be used.
-NNG_ESTOPPED1000Operation stopped. The operation was stopped with nng_aio_stop or [nng_aio_close].
+NNG_ESTOPPED1000Operation stopped. The operation was stopped with nng_aio_stop or [nng_aio_close].
 NNG_EINTERNAL1000An unidentifier internal error occurred.
 NNG_ESYSERR0x10000000 - 0x1FFFFFFFAn unidentified system error occurred. These are errors reported by the operating system.
 NNG_ETRANERR0x20000000 - 0x2FFFFFFFAn unidentified transport error occurred.
 
-
+
+
 
 
+
 
 
 
@@ -4024,26 +4089,26 @@ using these Streams APIs.
      
   note
 
      
 
      The nng_stream object is used for raw byte stream connections, and
-should not be confused with a pipe object created on a socket using
-the nng_listen, nng_dial or related functions.
      
+should not be confused with a pipe object created on a socket using
+the nng_listen, nng_dial or related functions.
      
 
 
      Sending and Receiving Data
      
 
      void nng_stream_send(nng_stream *s, nng_aio *aio);
 void nng_stream_recv(nng_stream *s, nng_aio *aio);
 
      
 
      The nng_stream_send function starts sending data asynchronously over the stream s.
-The data is sent from the scatter/gather vector located in the nng_aio aio,
-which must have been previously set using nng_aio_set_iov.
      
+The data is sent from the scatter/gather vector located in the nng_aio aio,
+which must have been previously set using nng_aio_set_iov.
      
 
      The nng_stream_recv function starts receiving data [asynchronously over the stream s
-into the scatter/gather vector located in the nng_aio aio,
-which must have been previously set using nng_aio_set_iov.
      
+into the scatter/gather vector located in the nng_aio aio,
+which must have been previously set using nng_aio_set_iov.
      
 
      These functions return immediately, with no return value.
 Completion of the operation is signaled via the aio, and the final
-result may be obtained via nng_aio_result.
      
+result may be obtained via nng_aio_result.
      
 
      The I/O operation may complete as soon as at least one byte has been
 transferred, or an error has occurred.
 Therefore, the number of bytes transferred may be less than requested.
-The actual number of bytes transferred can be determined with nng_aio_count.
      
+The actual number of bytes transferred can be determined with nng_aio_count.
      
 
      Closing a Stream
      
 
      void nng_stream_close(nng_stream *s);
 void nng_stream_stop(nng_stream *s);
@@ -4051,8 +4116,8 @@ void nng_stream_free(nng_stream *s);
 
      
 
      The nng_stream_close function closes a stream, but does not destroy it.
 This function returns immediately. Operations that are pending against the stream, such
-as nng_stream_send or nng_stream_recv operations will be canceled asynchronously, if possible.
-Those operations will result in NNG_ECLOSED.
      
+as nng_stream_send or nng_stream_recv operations will be canceled asynchronously, if possible.
+Those operations will result in NNG_ECLOSED.
      
 
      The nng_stream_stop function not only closes the stream, but waits for any operations
 pending against it to complete, and for any underlying asynchronous registered I/O to be fully deregistered.
 As some systems use separate threads for asynchronous I/O, stopping the stream is necessary before those
@@ -4067,7 +4132,7 @@ stream itself.
      
 
      
 
      Because nng_stream_stop and nng_stream_free both may block waiting for outstanding I/O to complete
 or be aborted, these functions are unsafe to call from functions that may not block, such as the
-completion function registered with an nng_aio when it is created.
      
+completion function registered with an nng_aio when it is created.
      
 
 
      Getting Stream Options
      
 
      nng_err nng_stream_get_bool(nng_stream *s, const char *opt, bool *valp);
@@ -4095,7 +4160,7 @@ typedef struct nng_stream_listener nng_stream_listener;
 
      
 
      
 The nng_stream_listener object and nng_stream_listener objects can be thought of as factories that
-create nng_stream streams.
      
+create nng_stream streams.
      
 
      The nng_stream_listener object a handle to a listener, which creates streams by accepting incoming connection requests.
 In a BSD socket implementation, this is the entity responsible for doing bind, listen and accept.
 Normally a listener may be used to accept multiple, possibly many, concurrent connections.
      
@@ -4109,10 +4174,10 @@ nng_err nng_stream_listener_alloc(nng_stream_listener **lstenerp, const char *ur
 nng_err nng_stream_listener_alloc_url(nng_stream_listener **listenerp, const nng_url *url);
 
    
 
    The nng_stream_dialer_alloc and nng_stream_dialer_alloc_url functions create a stream dialer, associated the
-URL specified by url represented as a string, or as an nng_url object, respectively. The dialer is returned in the location
+URL specified by url represented as a string, or as an nng_url object, respectively. The dialer is returned in the location
 dialerp references.
    
 
    The nng_stream_listener_alloc and nng_stream_listener_alloc_url functions create a stream listener, associated the
-URL specified by url represented as a string, or as an nng_url object, respectively. The listener is returned in the location
+URL specified by url represented as a string, or as an nng_url object, respectively. The listener is returned in the location
 listenerp references.
    
 
    Example 1: Creating a TCP Listener
    
 
    This shows creating a TCP listener that listens on INADDR_ANY, port 444.
    
@@ -4147,15 +4212,15 @@ callbacks are running that could reference an object after it is deallocated.
    Making Outgoing Connections
 
    void nng_stream_dialer_dial(nng_stream_dialer *dialer, nng_aio *aio);
 
    
-
    The nng_stream_dialer_dial initiates an outgoing connection asynchronously, using the nng_aio aio.
-If it successfully establishes a connection, it creates an nng_stream, which can be obtained as the first
-output result on aio using the nng_aio_get_output function with index zero.
    
+
    The nng_stream_dialer_dial initiates an outgoing connection asynchronously, using the nng_aio aio.
+If it successfully establishes a connection, it creates an nng_stream, which can be obtained as the first
+output result on aio using the nng_aio_get_output function with index zero.
    
 
    
 
    
   
   tip
 
    
-
    An nng_stream_dialer can be used multiple times to make multiple concurrent connection requests, but
+
    An nng_stream_dialer can be used multiple times to make multiple concurrent connection requests, but
 they all must reference the same URL.
    
 
    
 
    Example 3: Connecting to Google
    
@@ -4183,12 +4248,12 @@ void nng_stream_listener_accept(nng_stream_listener *listener, nng_aio *aio);
 
    
 
    Accepting incoming connections is performed in two steps. The first step, nng_stream_listener_listen is to setup for
 listening. For a TCP implementation of this, for example, this would perform the bind and the listen steps. This will bind
-to the address represented by the URL that was specific when the listener was created with nng_stream_listener_alloc.
    
-
    In the second step, nng_stream_listener_accept accepts an incoming connection on listener asynchronously, using the nng_aio aio.
-If an incoming connection is accepted, it will be represented as an nng_stream, which can be obtained from the aio as the first
-output result using the nng_aio_get_output function with index zero.
    
+to the address represented by the URL that was specific when the listener was created with nng_stream_listener_alloc.
    
+
    In the second step, nng_stream_listener_accept accepts an incoming connection on listener asynchronously, using the nng_aio aio.
+If an incoming connection is accepted, it will be represented as an nng_stream, which can be obtained from the aio as the first
+output result using the nng_aio_get_output function with index zero.
    
 
    Example 3: Accepting an Inbound Stream
    
-
    For clarity this example uses a synchronous approach using nng_aio_wait, but a typical server application
+
    For clarity this example uses a synchronous approach using nng_aio_wait, but a typical server application
 would most likely use a callback to accept the incoming stream, and start another instance of nng_stream_listener_accept.
    
 
    nng_aio *aio;
 nng_listener *listener;
@@ -4275,10 +4340,10 @@ need not retain the value referenced once the function returns.
    
 
    In the case of nng_stream_dialer_set_addr and nng_stream_listener_set_addr, the contents of addr are copied if necessary, so that the caller
 need not retain the value referenced once the function returns.
    
 
    Example 4: Socket Activation
    
-
    Some nng_stream_listener objects, depending on the underlying transport and platform, can support a technique known as “socket activation”,
+
    Some nng_stream_listener objects, depending on the underlying transport and platform, can support a technique known as “socket activation”,
 where the file descriptor used for listening and accepting is supplied externally, such as by a system service manager.
 In this case, the application supplies the file descriptor or SOCKET object using the NNG_OPT_LISTEN_FD option,
-instead of calling nng_stream_listener_listen.
    
+instead of calling nng_stream_listener_listen.
    
 
    
 
    
   
@@ -4305,25 +4370,30 @@ nng_err nng_stream_dialer_set_tls(nng_stream_listener *dialer, nng_tls_config *t
 nng_err nng_stream_listener_get_tls(nng_stream_listener *listener, nng_tls_config **tlsp);
 nng_err nng_stream_listener_set_tls(nng_stream_listener *listener, nng_tls_config *tls);
 
    
-
    Both nng_stream_dialer and nng_stream_listener objects may support configuration of TLS parameters.
+
    Both nng_stream_dialer and nng_stream_listener objects may support configuration of TLS parameters.
 The nng_stream_dialer_set_tls and nng_stream_listener_set_tls functions support setting the
-configuration of a nng_tls_config object supplied by tls on dialer or listener.
-This must be performed before the listener starts listening with nng_stream_listener_listen, or the dialer starts an outgoing connection
-as a result of nng_stream_dialer_dial.
    
+configuration of a nng_tls_config object supplied by tls on dialer or listener.
+This must be performed before the listener starts listening with nng_stream_listener_listen, or the dialer starts an outgoing connection
+as a result of nng_stream_dialer_dial.
    
 
    The configuration object that was previously established (which may be a default if one was not explicitly
 configured) can be obtained with the nng_stream_dialer_get_tls and nng_stream_listener_get_tls.
-They will return a pointer to the nng_tls_config object in question at the location referenced by tlsp.
    
+They will return a pointer to the nng_tls_config object in question at the location referenced by tlsp.
    
 
    
 
    
   
   note
 
    
 
    TLS configuration cannot be changed once it has started being used by a listener or dialer. This applies to
-both configuring a different TLS configuration object, as well as mutating the existing nng_tls_config object.
    
+both configuring a different TLS configuration object, as well as mutating the existing nng_tls_config object.
    
 
    
+
 
 
 
+
 
 
 
@@ -4417,8 +4487,8 @@ request headers, response status, response headers, and so forth.
    
 performed after the first transaction is complete.
    
 
    At any given point in time, an nng_http object can only refer to a single HTTP transaction.
 In NNG, these nng_http objects are used in both the client and server APIs.
    
-
    The nng_http object is created by either nng_http_client_connect or by an HTTP server
-object which then passes it to an nng_http_handler callback function.
    
+
    The nng_http object is created by either nng_http_client_connect or by an HTTP server
+object which then passes it to an nng_http_handler callback function.
    
 
    HTTP Method
    
 
    void nng_http_set_method(nng_http *conn, const char *method);
 const char *nng_http_get_method(nng_http *conn);
@@ -4437,8 +4507,8 @@ const char *nng_http_get_uri(nng_http *conn);
 
    The nng_http_set_uri function sets the URI, which normally appears like a path such as “/docs/index.html”,
 for the next transaction on conn. It sets the URI to uri, and, if query is not NULL, also appends the
 contents of query, separated by either the ‘?’ or ‘&’ character, depending on whether uri already
-contains a query string. It may return NNG_ENOMEM, or NNG_EMSGSIZE if the the result is too long,
-or NNG_EINVAL if there is some other problem with the URI.
    
+contains a query string. It may return NNG_ENOMEM, or NNG_EMSGSIZE if the the result is too long,
+or NNG_EINVAL if there is some other problem with the URI.
    
 
    
 
    
   
@@ -4456,7 +4526,7 @@ const char *nng_http_get_version(nng_http *conn);
 
    The nng_http_set_version function is used to select the HTTP protocol version to use for the
 exchange. At present, only the values NNG_HTTP_VERSION_1_0 and NNG_HTTP_VERSION_1_1 (corresponding to
 “HTTP/1.0” and “HTTP/1.1”) are supported. NNG will default to using “HTTP/1.1” if this function is not called.
-If an unsupported version is supplied, NNG_ENOTSUP will be returned, otherwise zero.
    
+If an unsupported version is supplied, NNG_ENOTSUP will be returned, otherwise zero.
    
 
    The nng_http_get_version function is used to determine the version the client selected. Normally
 there is little need to use this, but there are some subtle semantic differences between HTTP/1.0 and HTTP/1.1.
    
 
    
@@ -4492,72 +4562,72 @@ then a built in reason based on the status will be used instead.
    
   
   tip
 
    
-
    Callbacks used on the server may wish to use nng_http_server_set_error or nng_http_server_set_redirect instead of
+
    Callbacks used on the server may wish to use nng_http_server_set_error or nng_http_server_set_redirect instead of
 nng_http_set_status, because those functions will also set the response body to a suitable HTML document
 for display to users.
    
 
    
 
    Status codes are defined by the IETF. Here are definitions that NNG provides for convenience:
    
 
    
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
    NameCodeReason TextNotes
    NNG_HTTP_STATUS_CONTINUE100ContinuePartial transfer, client may send body.
    NNG_HTTP_STATUS_SWITCHING101Switching ProtocolsUsed when upgrading or hijacking a connection.
    NNG_HTTP_STATUS_PROCESSING102Processing
    NNG_HTTP_STATUS_OK200OKSuccessful result.
    NNG_HTTP_STATUS_CREATED201CreatedResource created successfully.
    NNG_HTTP_STATUS_ACCEPTED202CreatedRequest accepted for future processing.
    NNG_HTTP_STATUS_NOT_AUTHORITATIVE203Not AuthoritativeRequest successful, but modified by proxy.
    NNG_HTTP_STATUS_NO_CONTENT204No ContentRequest successful, no content returned.
    NNG_HTTP_STATUS_RESET_CONTENT205Reset ContentRequest successful, client should reload content.
    NNG_HTTP_STATUS_PARTIAL_CONTENT206Partial ContentResponse to a range request.
    NNG_HTTP_STATUS_MULTI_STATUS207Multi-StatusUsed with WebDAV.
    NNG_HTTP_STATUS_ALREADY_REPORTED208Already ReportedUsed with WebDAV.
    NNG_HTTP_STATUS_IM_USED226IM UsedUsed with delta encodings, rarely supported.
    NNG_HTTP_STATUS_MULTIPLE_CHOICES300Multiple ChoicesMultiple responses possible, client should choose.
    NNG_HTTP_STATUS_MOVED_PERMANENTLY301Moved PermanentlyPermanent redirection, may be saved by client.
    NNG_HTTP_STATUS_FOUND302FoundTemporary redirection, client may switch to GET.
    NNG_HTTP_STATUS_SEE_OTHER303See OtherRedirect, perhaps after a success POST or PUT.
    NNG_HTTP_STATUS_NOT_MODIFIED304Not ModifiedResource not modified, client may use cached version.
    NNG_HTTP_STATUS_USE_PROXY305Use Proxy
    NNG_HTTP_STATUS_TEMPORARY_REDIRECT307Temporary RedirectTemporary redirect, preserves method.
    NNG_HTTP_STATUS_PERMANENT_REDIRECT308Permanent RedirectPermanent redirect.
    NNG_HTTP_STATUS_BAD_REQUEST400Bad RequestGeneric problem with the request.
    NNG_HTTP_STATUS_UNAUTHORIZED401UnauthorizedIndicates a problem with authentication.
    NNG_HTTP_STATUS_PAYMENT_REQUIRED402Payment Required
    NNG_HTTP_STATUS_FORBIDDEN403ForbiddenNo permission to access resource.
    NNG_HTTP_STATUS_NOT_FOUND404Not FoundResource does not exist.
    NNG_HTTP_STATUS_METHOD_NOT_ALLOWED405Method Not AllowedResource does not support the method.
    NNG_HTTP_STATUS_METHOD_NOT_ACCEPTABLE406Not AcceptableCould not satisfy accept requirements.
    NNG_HTTP_STATUS_PROXY_AUTH_REQUIRED407Proxy Authentication RequiredProxy requires authentication.
    NNG_HTTP_STATUS_REQUEST_TIMEOUT408Request TimeoutTimed out waiting for request.
    NNG_HTTP_STATUS_CONFLICT409ConflictConflicting request.
    NNG_HTTP_STATUS_GONE410GoneResource no longer exists.
    NNG_HTTP_STATUS_LENGTH_REQUIRED411Length RequiredMissing Content-Length.
    NNG_HTTP_STATUS_PRECONDITION_FAILED412Precondition Failed
    NNG_HTTP_STATUS_CONTENT_TOO_LARGE413Content Too Large
    NNG_HTTP_STATUS_URI_TOO_LONG414URI Too Long
    NNG_HTTP_STATUS_UNSUPPORTED_MEDIA_TYPE415Unsupported Media Type
    NNG_HTTP_STATUS_RANGE_NOT_SATISFIABLE416Range Not Satisfiable
    NNG_HTTP_STATUS_EXPECTATION_FAILED417Expectation Failed
    NNG_HTTP_STATUS_TEAPOT418I Am A TeapotRFC 2324.
    NNG_HTTP_STATUS_UNPROCESSABLE_ENTITY422Unprocessable Entity
    NNG_HTTP_STATUS_LOCKED423Locked
    NNG_HTTP_STATUS_FAILED_DEPENDENCY424Failed Dependency
    NNG_HTTP_STATUS_TOO_EARLY425Too Early
    NNG_HTTP_STATUS_UPGRADE_REQUIRED426Upgrade Required
    NNG_HTTP_STATUS_PRECONDITION_REQUIRED428Precondition Required
    NNG_HTTP_STATUS_TOO_MANY_REQUESTS429Too Many Requests
    NNG_HTTP_STATUS_HEADERS_TOO_LARGE431Headers Too Large
    NNG_HTTP_STATUS_UNAVAIL_LEGAL_REASONS451Unavailable For Legal Reasons
    NNG_HTTP_STATUS_INTERNAL_SERVER_ERROR500Internal Server Error
    NNG_HTTP_STATUS_NOT_IMPLEMENTED501Not ImplementedServer does not implement method.
    NNG_HTTP_STATUS_BAD_GATEWAY502Bad Gateway
    NNG_HTTP_STATUS_SERVICE_UNAVAILALE503Service Unavailable
    NNG_HTTP_STATUS_GATEWAY_TIMEOUT504Gateway TImeout
    NNG_HTTP_STATUS_HTTP_VERSION_NOT_SUPP505HTTP Version Not Supported
    NNG_HTTP_STATUS_VARIANT_ALSO_NEGOTIATES506Variant Also Negotiates
    NNG_HTTP_STATUS_INSUFFICIENT_STORAGE507Variant Also Negotiates
    NNG_HTTP_STATUS_LOOP_DETECTED508Loop Detected
    NNG_HTTP_STATUS_NOT_EXTENDED510Not Extended
    NNG_HTTP_STATUS_NETWORK_AUTH_REQUIRED511Network Authentication Required
    NNG_HTTP_STATUS_CONTINUE100ContinuePartial transfer, client may send body.
    NNG_HTTP_STATUS_SWITCHING101Switching ProtocolsUsed when upgrading or hijacking a connection.
    NNG_HTTP_STATUS_PROCESSING102Processing
    NNG_HTTP_STATUS_OK200OKSuccessful result.
    NNG_HTTP_STATUS_CREATED201CreatedResource created successfully.
    NNG_HTTP_STATUS_ACCEPTED202CreatedRequest accepted for future processing.
    NNG_HTTP_STATUS_NOT_AUTHORITATIVE203Not AuthoritativeRequest successful, but modified by proxy.
    NNG_HTTP_STATUS_NO_CONTENT204No ContentRequest successful, no content returned.
    NNG_HTTP_STATUS_RESET_CONTENT205Reset ContentRequest successful, client should reload content.
    NNG_HTTP_STATUS_PARTIAL_CONTENT206Partial ContentResponse to a range request.
    NNG_HTTP_STATUS_MULTI_STATUS207Multi-StatusUsed with WebDAV.
    NNG_HTTP_STATUS_ALREADY_REPORTED208Already ReportedUsed with WebDAV.
    NNG_HTTP_STATUS_IM_USED226IM UsedUsed with delta encodings, rarely supported.
    NNG_HTTP_STATUS_MULTIPLE_CHOICES300Multiple ChoicesMultiple responses possible, client should choose.
    NNG_HTTP_STATUS_MOVED_PERMANENTLY301Moved PermanentlyPermanent redirection, may be saved by client.
    NNG_HTTP_STATUS_FOUND302FoundTemporary redirection, client may switch to GET.
    NNG_HTTP_STATUS_SEE_OTHER303See OtherRedirect, perhaps after a success POST or PUT.
    NNG_HTTP_STATUS_NOT_MODIFIED304Not ModifiedResource not modified, client may use cached version.
    NNG_HTTP_STATUS_USE_PROXY305Use Proxy
    NNG_HTTP_STATUS_TEMPORARY_REDIRECT307Temporary RedirectTemporary redirect, preserves method.
    NNG_HTTP_STATUS_PERMANENT_REDIRECT308Permanent RedirectPermanent redirect.
    NNG_HTTP_STATUS_BAD_REQUEST400Bad RequestGeneric problem with the request.
    NNG_HTTP_STATUS_UNAUTHORIZED401UnauthorizedIndicates a problem with authentication.
    NNG_HTTP_STATUS_PAYMENT_REQUIRED402Payment Required
    NNG_HTTP_STATUS_FORBIDDEN403ForbiddenNo permission to access resource.
    NNG_HTTP_STATUS_NOT_FOUND404Not FoundResource does not exist.
    NNG_HTTP_STATUS_METHOD_NOT_ALLOWED405Method Not AllowedResource does not support the method.
    NNG_HTTP_STATUS_METHOD_NOT_ACCEPTABLE406Not AcceptableCould not satisfy accept requirements.
    NNG_HTTP_STATUS_PROXY_AUTH_REQUIRED407Proxy Authentication RequiredProxy requires authentication.
    NNG_HTTP_STATUS_REQUEST_TIMEOUT408Request TimeoutTimed out waiting for request.
    NNG_HTTP_STATUS_CONFLICT409ConflictConflicting request.
    NNG_HTTP_STATUS_GONE410GoneResource no longer exists.
    NNG_HTTP_STATUS_LENGTH_REQUIRED411Length RequiredMissing Content-Length.
    NNG_HTTP_STATUS_PRECONDITION_FAILED412Precondition Failed
    NNG_HTTP_STATUS_CONTENT_TOO_LARGE413Content Too Large
    NNG_HTTP_STATUS_URI_TOO_LONG414URI Too Long
    NNG_HTTP_STATUS_UNSUPPORTED_MEDIA_TYPE415Unsupported Media Type
    NNG_HTTP_STATUS_RANGE_NOT_SATISFIABLE416Range Not Satisfiable
    NNG_HTTP_STATUS_EXPECTATION_FAILED417Expectation Failed
    NNG_HTTP_STATUS_TEAPOT418I Am A TeapotRFC 2324.
    NNG_HTTP_STATUS_UNPROCESSABLE_ENTITY422Unprocessable Entity
    NNG_HTTP_STATUS_LOCKED423Locked
    NNG_HTTP_STATUS_FAILED_DEPENDENCY424Failed Dependency
    NNG_HTTP_STATUS_TOO_EARLY425Too Early
    NNG_HTTP_STATUS_UPGRADE_REQUIRED426Upgrade Required
    NNG_HTTP_STATUS_PRECONDITION_REQUIRED428Precondition Required
    NNG_HTTP_STATUS_TOO_MANY_REQUESTS429Too Many Requests
    NNG_HTTP_STATUS_HEADERS_TOO_LARGE431Headers Too Large
    NNG_HTTP_STATUS_UNAVAIL_LEGAL_REASONS451Unavailable For Legal Reasons
    NNG_HTTP_STATUS_INTERNAL_SERVER_ERROR500Internal Server Error
    NNG_HTTP_STATUS_NOT_IMPLEMENTED501Not ImplementedServer does not implement method.
    NNG_HTTP_STATUS_BAD_GATEWAY502Bad Gateway
    NNG_HTTP_STATUS_SERVICE_UNAVAILALE503Service Unavailable
    NNG_HTTP_STATUS_GATEWAY_TIMEOUT504Gateway TImeout
    NNG_HTTP_STATUS_HTTP_VERSION_NOT_SUPP505HTTP Version Not Supported
    NNG_HTTP_STATUS_VARIANT_ALSO_NEGOTIATES506Variant Also Negotiates
    NNG_HTTP_STATUS_INSUFFICIENT_STORAGE507Variant Also Negotiates
    NNG_HTTP_STATUS_LOOP_DETECTED508Loop Detected
    NNG_HTTP_STATUS_NOT_EXTENDED510Not Extended
    NNG_HTTP_STATUS_NETWORK_AUTH_REQUIRED511Network Authentication Required
    
 
    
 
    
 
    Retrieving Headers
    
@@ -4584,11 +4654,11 @@ void nng_http_del_header(nng_http *conn, const char *key);
 
    
 
    The nng_http_add_header, nng_http_set_header, and nng_http_del_header functions are
 used to add a modify either the request or response headers for conn prior to sending to the connected peer on conn.
    
-
    Thus, if the conn is a client connection created by nng_http_client_connect, then the request headers are modified.
+
    Thus, if the conn is a client connection created by nng_http_client_connect, then the request headers are modified.
 Conversely, if it is a connection created by an HTTP server and used in a callback function, then the response headers are modified.
    
 
    The nng_http_add_header function adds a header with the name key, and the value val, to the list of headers.
 In so doing, it may bring collapse multiple headers with the same name into a comma separated list, following
-the syntax specified in RFC 9110. The function may return NNG_ENOMEM, NNG_EMSGSIZE, or NNG_EINVAL.
    
+the syntax specified in RFC 9110. The function may return NNG_ENOMEM, NNG_EMSGSIZE, or NNG_EINVAL.
    
 
    The nng_http_set_header function adds the header if it does not already exist, but replaces any and all previously existing
 headers with the same name key, if they exist. In all other respects it behaves similarly to nng_http_add_header.
    
 
    The nng_http_del_header removes all headers with name key.
    
@@ -4647,7 +4717,7 @@ including any disposing of any underlying file descriptors or related resources.
 
    
 
    The nng_http_reset function resets the request and response state of the
 the connection conn, so that it is just as if it had been freshly created with
-nng_http_client_connect or passed into a handler function for a server callback.
    
+nng_http_client_connect or passed into a handler function for a server callback.
    
 
    The intended purpose of this function is to clear the object state before reusing the conn for
 subsequent transactions.
    
 
    Direct Read and Write
    
@@ -4657,11 +4727,11 @@ void nng_http_read_all(nng_http *conn, nng_aio *aio);
 void nng_http_write_all(nng_http *conn, nng_aio *aio);
 
    
 
    The nng_http_read and nng_http_write functions read or write data asynchronously from or to the
-connection conn, using the nng_iov that is set in aio with nng_aio_set_iov.
+connection conn, using the nng_iov that is set in aio with nng_aio_set_iov.
 These functions will complete as soon as any data is transferred.
-Use nng_aio_count to determine how much data was actually transferred.
    
+Use nng_aio_count to determine how much data was actually transferred.
    
 
    The nng_http_read_all and nng_http_write_all functions perform the same task, but will keep resubmitting
-operations until the the entire amount of data requested by the nng_iov is transferred.
    
+operations until the the entire amount of data requested by the nng_iov is transferred.
    
 
    
 
    
   
@@ -4669,7 +4739,7 @@ operations until the the entire amount of data requested by the nng_http_hijack.
+
    These functions are most likely to be useful after hijacking the connection with nng_http_hijack.
 They can be used to transfer request or response body data as well.
    
 
    Hijacking Connections
    
 
    nng_err nng_http_hijack(nng_http *conn);
@@ -4681,7 +4751,7 @@ to be disassociated from the HTTP server where it was created.
    
 WebSocket), where the underlying HTTP connection will be taken over for
 some other purpose, and should not be used any further by the server.
    
 
    This function is most useful when called from a handler function.
-(See nng_http_handler_alloc.)
    
+(See nng_http_handler_alloc.)
    
 
    
 
    
   
@@ -4689,7 +4759,7 @@ some other purpose, and should not be used any further by the server.
    
 
    
 
    It is the responsibility of the caller to dispose of the underlying connection when it is no longer needed.
 Furthermore, the HTTP server will no longer send any responses to the hijacked connection, so the caller should do that as well if appropriate.
-(See nng_http_write_response.)
    
+(See nng_http_write_response.)
    
 
    
 
    
 
    
@@ -4706,7 +4776,7 @@ Most applications will never need to use this function.
    
 
    The nng_http_peer_cert function will obtain the TLS certificate object for the peer, if one is available.
 This can then be used for additional authentication or identity specific logic.
    
 
    The certificate must be released with [nng_tls_cert_free] when no longer in use.
-See [nng_tls_cert] for more information about working with TLS certificates.
    
+See nng_tls_cert for more information about working with TLS certificates.
    
 
    
 
    
   
@@ -4723,8 +4793,8 @@ transactions on those connections.
    
 
    Client Object
    
 
    typedef struct nng_http_client nng_http_client;
 
    
-
    The nng_http_client object is the client side creator for nng_http objects.
-It is analogous to a dialer object used elsewhere in NNG, but it specifically is only for HTTP.
    
+
    The nng_http_client object is the client side creator for nng_http objects.
+It is analogous to a dialer object used elsewhere in NNG, but it specifically is only for HTTP.
    
 
    Create a Client
    
 
    void nng_http_client_alloc(nng_http_client *clientp, const nng_url *url);
 
    
@@ -4741,7 +4811,7 @@ of its resources.
    
   
   note
 
    
-
    Any connections created by nng_http_client_connect are not affected by this function,
+
    Any connections created by nng_http_client_connect are not affected by this function,
 and must be closed explicitly as needed.
    
 
    
 
    Client TLS
    
@@ -4749,10 +4819,10 @@ and must be closed explicitly as needed.
    
 nng_err nng_http_client_set_tls(nng_http_client *client, nng_tls_config *tls);
 
    
 
    The nng_http_client_get_tls and nng_http_client_set_tls functions are used to
-retrieve or change the TLS configuration used when making outbound connections, enabling
+retrieve or change the TLS configuration used when making outbound connections, enabling
 TLS as a result.
    
-
    If TLS has not been previously configured on client, then nng_http_client_get_tls will return NNG_EINVAL.
-Both functions will return NNG_ENOTSUP if either HTTP or TLS is not supported.
    
+
    If TLS has not been previously configured on client, then nng_http_client_get_tls will return NNG_EINVAL.
+Both functions will return NNG_ENOTSUP if either HTTP or TLS is not supported.
    
 
    Calling nng_http_client_set_tls invalidates any client previously obtained with
 nng_http_client_get_tls, unless a separate hold on the object was obtained.
    
 
    Once TLS is enabled for an nng_http_client, it is not possible to disable TLS.
    
@@ -4762,7 +4832,7 @@ Both functions will return NNG_
   note
 
    
 
    The TLS configuration itself cannot be changed once it has been used to create a connection,
-such as by calling nng_http_client_connect, but a new one can be installed in the client.
+such as by calling nng_http_client_connect, but a new one can be installed in the client.
 Existing connections will use the TLS configuration that there were created with.
    
 
    
 
    Creating Connections
    
@@ -4771,9 +4841,9 @@ Existing connections will use the TLS configuration that there were created with
 void nng_http_client_connect(nng_http_client *client, nng_aio *aio);
 
    
 
    The nng_http_client_connect function makes an outgoing connection to the
-server configured for client, and creates an nng_http object for the connection.
    
+server configured for client, and creates an nng_http object for the connection.
    
 
    This is done asynchronously, and when the operation succeseds the connection may be
-retried from the aio using nng_aio_get_output with index 0.
    
+retried from the aio using nng_aio_get_output with index 0.
    
 
    Example 1: Connecting to Google
    
 
    nng_aio *aio;
 nng_url *url;
@@ -4812,16 +4882,16 @@ the HTTP request associated with conn.
 The entire request is sent,
 including headers, and if present, the request body data.
 (The request body can be set with
-nng_http_set_body or nng_http_copy_body.)
    
+nng_http_set_body or nng_http_copy_body.)
    
 
    This function returns immediately, with no return value.
 Completion of the operation is signaled via the aio, and the final result
-may be obtained via nng_aio_result.
    
+may be obtained via nng_aio_result.
    
 
    
 
    
   
   tip
 
    
-
    Consider using the [nng_http_transact] function,
+
    Consider using the nng_http_transact function,
 which provides a simpler interface for performing a complete HTTP client transaction.
    
 
    
 
    Obtaining the Response
    
@@ -4830,7 +4900,7 @@ which provides a simpler interface for performing a complete HTTP client transac
 
    The nng_http_read_response function starts an asynchronous read from the
 HTTP connection conn, reading an HTTP response into the response associated with conn, including all
 of the related headers.
    
-
    It does not transfer any response body. To do that, use nng_http_read_all or nng_http_read.
    
+
    It does not transfer any response body. To do that, use nng_http_read_all or nng_http_read.
    
 
    
 
    
   
@@ -4844,7 +4914,7 @@ need to do so may use the direct read functions.
    
   
   tip
 
    
-
    An easier one-shot method for many use cases might be [nng_http_transact].
    
+
    An easier one-shot method for many use cases might be nng_http_transact.
    
 
    
 
    Submitting the Transaction
    
 
    void nng_http_transact(nng_http *conn, nng_aio *aio);
@@ -4855,11 +4925,11 @@ When the function is complete, the aio will be notified.
    
 HTTP exchange over the connection conn, sending the request
 and attached body data to the remote server, and reading the response.
    
 
    The entire response is read, including any associated body, which can
-subsequently be obtained using [nng_http_get_data].
    
+subsequently be obtained using nng_http_get_body.
    
 
    This function is intended to make creation of client applications easier,
 by performing multiple asynchronous operations required to complete an
 entire HTTP transaction.
    
-
    If an error occurs, the caller should close conn with nng_http_close, as it may not
+
    If an error occurs, the caller should close conn with nng_http_close, as it may not
 necessarily be usable with other transactions.
    
 
    
 
    
@@ -4883,7 +4953,7 @@ request interleaving.
    
 
    
 
    This function returns immediately, with no return value.
 Completion of the operation is signaled via the aio, and the final result
-may be obtained via [nng_aio_result()].
    
+may be obtained via nng_aio_result.
    
 
    Response Body
    
 
    Server API
    
 
    Handlers
    
@@ -4897,7 +4967,7 @@ Only the path component of the Request URI is considered when determining whethe
 
    This implementation limits the path length to 1024 bytes, including the
 zero termination byte. This does not prevent requests with much longer
 URIs from being supported, but doing so will require setting the handler to match a parent path in the tree using
-[nng_http_handler_set_tree].
    
+nng_http_handler_set_tree.
    
 
    
 
    
   
@@ -4906,11 +4976,11 @@ URIs from being supported, but doing so will require setting the handler to matc
 
    The NNG HTTP framework is optimized for URLs shorter than 200 characters.
    
 
    
 
    Additionally each handler has a method it is registered to handle
-(the default is “GET” andc can be changed with nng_http_handler_set_method), and
-optionally a “Host” header it can be matched against (see nng_http_handler_set_host).
    
+(the default is “GET” andc can be changed with nng_http_handler_set_method), and
+optionally a “Host” header it can be matched against (see nng_http_handler_set_host).
    
 
    In some cases, a handler may reference a logical tree rather (directory)
 rather than just a single element.
-(See [nng_http_handler_set_tree]).
    
+(See nng_http_handler_set_tree).
    
 
    Implementing a Handler
    
 
    typedef void (*nng_http_handler_func)(nng_http_conn *conn, void *arg, nng_aio *aio);
 
@@ -4922,30 +4992,30 @@ On success, a pointer to the handler is stored at the located pointed to by 
 
    The handler function is specified by cb.
 This function uses the asynchronous I/O framework.
    
 
    The function receives the connection on conn, and an optional data pointer that was set
-previously with nng_http_handler_set_data as the second argument. The
-final argument is the nng_aio aio, which must be “finished” to complete the operation.
    
-
    The handler may call nng_http_write_response to send the response, or
+previously with nng_http_handler_set_data as the second argument. The
+final argument is the nng_aio aio, which must be “finished” to complete the operation.
    
+
    The handler may call nng_http_write_response to send the response, or
 it may simply let the framework do so on its behalf. The server will perform
 this step if the callback has not already done so.
    
-
    Response headers may be set using nng_http_set_header, and request headers
-may be accessed by using nng_http_get_header. They can also be iterated
-over using nng_http_next_header
    
-
    Likewise the request body may be accessed, using nng_http_get_body, and
-the response body may be set using either nng_http_set_body or nng_http_copy_body.
    
+
    Response headers may be set using nng_http_set_header, and request headers
+may be accessed by using nng_http_get_header. They can also be iterated
+over using nng_http_next_header
    
+
    Likewise the request body may be accessed, using nng_http_get_body, and
+the response body may be set using either nng_http_set_body or nng_http_copy_body.
    
 
    
 
    
   
   note
 
    
 
    The request body is only collected for the handler if the
-nng_http_handler_collect_body function has been called for the handler.
    
+nng_http_handler_collect_body function has been called for the handler.
    
 
    
-
    The HTTP status should be set for the transaction using nng_http_set_status.
    
-
    Finally, the handler should finish the operation by calling the nng_aio_finish function
-after having set the status to NNG_OK.
+
    The HTTP status should be set for the transaction using nng_http_set_status.
    
+
    Finally, the handler should finish the operation by calling the nng_aio_finish function
+after having set the status to NNG_OK.
 If any other status is set on the aio, then a generic 500 response will be created and
 sent, if possible, and the connection will be closed.
    
-
    The aio may be scheduled for deferred completion using the nng_aio_start.
    
+
    The aio may be scheduled for deferred completion using the nng_aio_start.
    
 
    Serving Directories and Files
    
 
    nng_err nng_http_handler_alloc_directory(nng_http_handler **hp, const char *path, const char *dirname);
 nng_err nng_http_handler_alloc_file(nng_http_handler **hp, const char *path, const char *filename);
@@ -4971,7 +5041,7 @@ then a value of application/octet-stream is assumed.
    
 
    
 
    The nng_http_handler_alloc_redirect function creates a handler with
 a function that simply directions from the URI at path to the given location.
    
-
    The HTTP reply it creates will be with status code status,
+
    The HTTP reply it creates will be with status code status,
 which should be a 3XX code such as 301, and a Location: header will contain the URL
 referenced by location, with any residual suffix from the request
 URI appended.
    
@@ -4980,7 +5050,7 @@ URI appended.
    
   
   tip
 
    
-
    Use [nng_http_handler_set_tree] to redirect an entire tree.
+
    Use nng_http_handler_set_tree to redirect an entire tree.
 For example, it is possible to redirect an entire HTTP site to another
 HTTPS site by specifying / as the path and then using the base
 of the new site, such as https://newsite.example.com as the new location.
    
@@ -4991,10 +5061,10 @@ of the new site, such as https://newsite.example.com as the new loc
   tip
 
    
 
    Be sure to use the appropriate value for status.
-Permanent redirection should use [NNG_HTTP_STATUS_STATUS_MOVED_PERMANENTLY] (301)
-and temporary redirections should use NNG_HTTP_STATUS_TEMPORARY_REDIRECT (307).
+Permanent redirection should use NNG_HTTP_STATUS_MOVED_PERMANENTLY (301)
+and temporary redirections should use NNG_HTTP_STATUS_TEMPORARY_REDIRECT (307).
 In REST APIs, using a redirection to supply the new location of an object
-created with POST should use NNG_HTTP_STATUS_SEE_OTHER (303).
    
+created with POST should use NNG_HTTP_STATUS_SEE_OTHER (303).
    
 
 
    Collecting Request Body
    
 
    void nng_http_handler_collect_body(nng_http_handler *handler, bool want, size_t maxsz);
@@ -5003,12 +5073,12 @@ created with POST should use nng_http_get_body function.
    
+nng_http_get_body function.
    
 
    The collection is enabled if want is true.
 Furthermore, the data that the client may sent is limited by the
 value of maxsz.
 If the client attempts to send more data than maxsz, then the
-request will be terminated with NNG_HTTP_STATUS_CONTENT_TOO_LARGE (413).
    
+request will be terminated with NNG_HTTP_STATUS_CONTENT_TOO_LARGE (413).
    
 
    
 
    
   
@@ -5055,7 +5125,7 @@ The intended use of this function is deallocate any resources associated with handler will be called for, such as “GET” or “POST”.
 (By default the “GET” method is handled.)
    
 
    If method is NULL the handler will be executed for all methods.
-The handler may determine the actual method used with the nng_http_get_method function.
    
+The handler may determine the actual method used with the nng_http_get_method function.
    
 
    The server will automatically call “GET” handlers if the client
 sends a “HEAD” request, and will suppress HTTP body data in the responses
 sent for such requests.
    
@@ -5106,16 +5176,21 @@ It can also provide a logical fallback instead of relying on a 404 error code.void nng_http_write_response(nng_http *conn, nng_aio *aio);
 
    
 
    Normally the server will send any attached response, but there are circumstances where
-a response must be sent manually, such as when hijacking a connection.
    
+a response must be sent manually, such as when hijacking a connection.
    
 
    In such a case, nng_http_write_response can be called, which will send the response and any attached data, asynchronously
-using the nng_aio aio.
    
+using the nng_aio aio.
    
 
    By default, for HTTP/1.1 connections, the connection is kept open, and
 will be reused to receive new requests. For HTTP/1.0, or if the client has requested
 explicitly by setting the “Connection: close” header, the connection will be closed after the
 response is fully sent.
    
+
 
 
 
+
 
 
 
@@ -5202,7 +5277,7 @@ number facilities when available.
    
 
    
 
    The nng_socket_pair function creates a pair of connected file descriptors.
 These file descriptors, which are returned in the fds array, are suitable for
-use with the Socket transport.
    
+use with the Socket transport.
    
 
    On POSIX platforms, this is a thin wrapper around the standard socketpair function,
 using the AF_UNIX family and the SOCK_STREAM socket type.
 1
    
@@ -5234,9 +5309,14 @@ the version numbers reported refer to both the API and the library itself.
 (The ABI – application binary interface – between the
 library and the application is controlled in a similar, but different
 manner depending upon the link options and how the library is built.)
    
+
 
 
 
+
 
 
 
@@ -5334,7 +5414,7 @@ will use space efficiently even if identifiers are very far apart.
   important
 
    
 
    The function available for nng_id_map are not thread-safe.
-Callers should use a mutex or similar approach when thread-safety is needed.
    
+Callers should use a mutex or similar approach when thread-safety is needed.
    
 
 
    Create ID Map
    
 
    #define NNG_MAP_RANDOM 1
@@ -5352,7 +5432,7 @@ This is useful to reduce the odds of different instances of an application using
 the same identifiers at the same time.
    
 
    If both lo and hi are zero, then the values 0 and 0xffffffff are substituted
 in their place, giving a full range of 32-bit identifiers.
    
-
    This function can return NNG_ENOMEM if it is unable to allocate resources, otherwise
+
    This function can return NNG_ENOMEM if it is unable to allocate resources, otherwise
 it returns zero on success.
    
 
    Destroy Map
    
 
    void nng_id_map_free(nng_id_map *map);
@@ -5382,7 +5462,7 @@ index id.
    
 
    The value must not be NULL.
    
 
 
    If the table has to grow to accommodate this value, it may fail if insufficient
-memory is available, returning NNG_ENOMEM. Otherwise it returns zero.
    
+memory is available, returning NNG_ENOMEM. Otherwise it returns zero.
    
 
    Lookup a Value
    
 
    void *nng_id_get(nng_id_map *map, uint64_t id);
 
    
@@ -5398,16 +5478,16 @@ largest possible identifier is allocated. After wrapping, only identifiers that
 in use will be considered.
 No effort is made to order the availability of identifiers based on
 when they were freed.2
    
-
    As with nng_id_set, this may need to allocate memory and can thus
-fail with NNG_ENOMEM.
    
+
    As with nng_id_set, this may need to allocate memory and can thus
+fail with NNG_ENOMEM.
    
 
    Additionally, if there are no more free identifiers within the range specified
-when map was created, then it will return NNG_ENOSPC.
    
+when map was created, then it will return NNG_ENOSPC.
    
 
    Otherwise it returns zero, indicating success.
    
 
    Remove an ID
    
 
    int nng_id_remove(nng_id_map *map, uint64_t id);
 
    
 
    The nng_id_remove removes the entry at index id from map.
    
-
    If no such entry exist, it will return NNG_ENOENT. Otherwise it returns zero.
    
+
    If no such entry exist, it will return NNG_ENOENT. Otherwise it returns zero.
    
 
    Iterating IDs
    
 
    bool nng_id_visit(nng_id_map *map, uint64_t *id_p, void **value_p, uint32_t *cursor);
 
    
@@ -5423,9 +5503,14 @@ The caller must not attempt to derive any value of the cursor as it ref
 iteration is undefined; entries may be repeated or omitted during such an iteration.
    
 
    The caller must not attempt to derive any value of the cursor as it refers to internal
 table indices.
    
+
 
 
 
+
 
 
 
@@ -5514,7 +5599,7 @@ and for this purpose a header library is supplied.
    
 
    
 
    The functionality described here is entirely contained in the
 nng/args.h header file, and may be used without previously
-initializing the library with nng_init, and may even be used
+initializing the library with nng_init, and may even be used
 in programs that are not linked against the NNG library.
    
 
 
    Parse Command Line Arguments
    
@@ -5675,9 +5760,14 @@ unambiguously (meaning it must not match any other option specification.)
    
         exit(1);
     }
 
    
+
 
 
 
+
 
 
 
@@ -7223,7 +7313,7 @@ same application, and they will not interfere with one another.
    
 
    Two applications may also use the same URL without interfering with each other.
 They will however be unable to communicate with each other using that URL.
    
 
    Socket Address
    
-
    When using an nng_sockaddr structure, the actual structure is of type nng_sockaddr_inproc.
    
+
    When using an nng_sockaddr structure, the actual structure is of type nng_sockaddr_inproc.
    
 
    Transport Options
    
 
    The inproc transport has no special options.
    
 
    
@@ -7243,9 +7333,14 @@ or libnanomsg implementations), it will not be possible to utilize
 the inproc transport to communicate across this boundary.
    
 
    This limitation also extends to using different instances of the NNG
 library within the same process.
    
+
 
 
 
+
 
 
 
@@ -7345,7 +7440,7 @@ relative to the root directory.
    
   note
 
    
 
    When using relative paths on POSIX systems, the address used and returned
-in properties like NNG_OPT_LOCADDR will also be relative.
+in properties like NNG_OPT_LOCADDR will also be relative.
 Consequently, they will only be interpreted the same by processes that have
 the same working directory.
 To ensure maximum portability and safety, absolute paths are recommended
@@ -7377,39 +7472,44 @@ For example, the name "a\0b" would be represented as abstract
 
    
 
    An empty name may be used with a listener to request “auto bind” be used to select a name.
 In this case the system will allocate a free name.
-The name assigned may be retrieved using NNG_OPT_LOCADDR.
    
+The name assigned may be retrieved using NNG_OPT_LOCADDR.
    
 
    
 
    Abstract names do not include the leading NUL byte used in the low-level socket address.
    
 
    Abstract sockets do not have any representation in the file system, and are automatically freed by
 the system when no longer in use.
    
 
    Abstract sockets ignore socket permissions, but it is still possible to determine the credentials
-of the peer with NNG_OPT_PEER_UID, and similar options.
+of the peer with NNG_OPT_PEER_UID, and similar options.
 2
    
 
    Socket Address
    
-
    When using an nng_sockaddr structure,
-the actual structure is of type nng_sockaddr_ipc,
-except for abstract sockets, which use nng_sockaddr_abstract.
    
+
    When using an nng_sockaddr structure,
+the actual structure is of type nng_sockaddr_ipc,
+except for abstract sockets, which use nng_sockaddr_abstract.
    
 
    Transport Options
    
 
    The following transport options are supported by this transport,
 where supported by the underlying platform.
    
 
    
-
-
+
+
-
+
    OptionTypeDescription
    
 
    NNG_OPT_IPC_PERMISSIONSintSettable on listeners before they start, this is the UNIX file mode used when creating the socket.
    NNG_OPT_LOCADDRnng_sockaddrLocal socket address, either nng_sockaddr_ipc or nng_sockaddr_abstract.
    NNG_OPT_REMADDRnng_sockaddrRemote socket address, either nng_sockaddr_ipc or nng_sockaddr_abstract.
    NNG_OPT_LOCADDRnng_sockaddrLocal socket address, either nng_sockaddr_ipc or nng_sockaddr_abstract.
    NNG_OPT_REMADDRnng_sockaddrRemote socket address, either nng_sockaddr_ipc or nng_sockaddr_abstract.
    
 
    NNG_OPT_PEER_GIDintRead only option, returns the group ID of the process at the other end of the socket, if platform supports it.
    
 
    NNG_OPT_PEER_PIDintRead only option, returns the processed ID of the process at the other end of the socket, if platform supports it.
    
 
    NNG_OPT_PEER_UIDintRead only option, returns the user ID of the process at the other end of the socket, if platform supports it.
    
 
    NNG_OPT_PEER_ZONEIDintRead only option, returns the zone ID of the process at the other end of the socket, if platform supports it.
    NNG_OPT_LISTEN_FDintWrite only for listeners before they start, use the named socket for accepting (for use with socket activation).
    NNG_OPT_LISTEN_FDintWrite only for listeners before they start, use the named socket for accepting (for use with socket activation).
    
 
    
 
    
 
    Other Configuration Parameters
    
 
    On Windows systems, the security descriptor for the listener,
 which can be used to control access, can be set using the function
-nng_listener_set_security_descriptor.
    
+nng_listener_set_security_descriptor.
    
+
 
 
 
+
 
 
 
@@ -7490,21 +7590,21 @@ prevent unauthorized access, or that checks against the peer credentials are mad
 
    Description
    
 
    The socket transport supports communication between
 peers across arbitrary BSD sockets, such as those that are
-created with nng_socket_pair.
    
-
    This transport only supports listeners, using nng_listener_create.
    
+created with nng_socket_pair.
    
+
    This transport only supports listeners, using nng_listener_create.
    
 
    
 
    
   
   note
 
    
-
    Attempts to create dialers using this transport will result in NNG_ENOTSUP.
    
+
    Attempts to create dialers using this transport will result in NNG_ENOTSUP.
    
 
    
 
    The socket file descriptor is passed to the listener using
 the NNG_OPT_SOCKET_FD option (as an integer).
-Setting this option will cause the listener to create a pipe
+Setting this option will cause the listener to create a pipe
 backed by the file descriptor.
    
 
    The protocol between peers using this transport is compatible with the protocol used
-for the tcp transport, but this is an implementation detail and subject to change without notice.
+for the tcp transport, but this is an implementation detail and subject to change without notice.
 1
    
 
    
 
    
@@ -7522,7 +7622,7 @@ There are no further socket details available.
    
 
    Transport Options
    
 
    The following transport options are supported by this transport.
    
 
    
-
+
@@ -7534,17 +7634,22 @@ There are no further socket details available.
    
   note
 
    The NNG_OPT_PEER_GID, NNG_OPT_PEER_PID, NNG_OPT_PEER_UID, and NNG_OPT_PEER_ZONEID options depend on platform support.
-These behave in exactly the same fashion as for the ipc transport.
    
+These behave in exactly the same fashion as for the ipc transport.
    
+
+
    
-
    1: Specifically it is not compatible with the ipc transport.
    
+
    1: Specifically it is not compatible with the ipc transport.
    2: Windows lacks a suitable socketpair equivalent function we could use.
    OptionTypeDescription
    NNG_OPT_SOCKET_FDintWrite-only option, that may be set multiple times on a listener. Each time this is set, the listener will create a pipe backed by the given file descriptor passed as an argument.
    NNG_OPT_SOCKET_FDintWrite-only option, that may be set multiple times on a listener. Each time this is set, the listener will create a pipe backed by the given file descriptor passed as an argument.
    
 
    NNG_OPT_PEER_GIDintRead only option, returns the group ID of the process at the other end of the socket, if platform supports it.
    
 
    NNG_OPT_PEER_PIDintRead only option, returns the processed ID of the process at the other end of the socket, if platform supports it.
    
 
    NNG_OPT_PEER_UIDintRead only option, returns the user ID of the process at the other end of the socket, if platform supports it.