diff options
Diffstat (limited to 'docs')
136 files changed, 395 insertions, 388 deletions
diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc index 149dc9f4..61ceacc7 100644 --- a/docs/man/libnng.3.adoc +++ b/docs/man/libnng.3.adoc @@ -124,7 +124,7 @@ mode may need to access the header of messages. === Asynchronous Operations Most applications will interact with _nng_ synchronously; that is that -functions such as <<nng_send.3#,`nng_send()`>> will block the calling +functions such as `<<nng_send.3#,nng_send()>>` will block the calling thread until the operation has completed. NOTE: Synchronous operations which send messages may return before the @@ -136,9 +136,9 @@ Asynchronous operations behave differently. These operations are initiated by the calling thread, but control returns immediately to the calling thread. When the operation is subsequently completed (regardless of whether this was successful or not), then a user supplied function -("callback") is executed. +("`callback`") is executed. -A context structure, an <<nng_aio.5#,`nng_aio`>>, is allocated and +A context structure, an `<<nng_aio.5#,nng_aio>>`, is allocated and associated with each asynchronous operation. Only a single asynchronous operation may be associated with an `nng_aio` at any time. diff --git a/docs/man/nn_bind.3compat.adoc b/docs/man/nn_bind.3compat.adoc index 79ff2c04..42f5c58f 100644 --- a/docs/man/nn_bind.3compat.adoc +++ b/docs/man/nn_bind.3compat.adoc @@ -28,7 +28,7 @@ The `nn_bind()` function arranges for the socket _sock_ to accept connections at the address specified by _url_. An "`endpoint identifier`" for this socket's association with the _url_ is returned to the caller on success. -This ID can be used with `<<nn_shutdown.3compat#,nn_shutdown()>>`` to +This ID can be used with `<<nn_shutdown.3compat#,nn_shutdown()>>` to "`unbind`" the socket from the address at _url_. NOTE: This function is provided for API diff --git a/docs/man/nn_connect.3compat.adoc b/docs/man/nn_connect.3compat.adoc index add14060..f5002b82 100644 --- a/docs/man/nn_connect.3compat.adoc +++ b/docs/man/nn_connect.3compat.adoc @@ -28,7 +28,7 @@ The `nn_connect()` function arranges for the socket _sock_ to inititate connection to a peer at the address specified by _url_. An "`endpoint identifier`" for this socket's association with the _url_ is returned to the caller on success. -This ID can be used with `<<nn_shutdown.3compat#,nn_shutdown()>>`` to +This ID can be used with `<<nn_shutdown.3compat#,nn_shutdown()>>` to "`unbind`" the socket from the address at _url_. NOTE: This function is provided for API diff --git a/docs/man/nn_freemsg.3compat.adoc b/docs/man/nn_freemsg.3compat.adoc index d23d9f0a..cfdc5957 100644 --- a/docs/man/nn_freemsg.3compat.adoc +++ b/docs/man/nn_freemsg.3compat.adoc @@ -25,7 +25,7 @@ int nn_freemsg(void *msg); == DESCRIPTION The `nn_freemsg()` deallocates a message previously allocated with -`<<nn_allocmsg.3compat#,nn_allocmsg()>>`` or similar functions. +`<<nn_allocmsg.3compat#,nn_allocmsg()>>` or similar functions. NOTE: This function is provided for API <<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_. diff --git a/docs/man/nn_poll.3compat.adoc b/docs/man/nn_poll.3compat.adoc index 0a1f02e6..a1e13992 100644 --- a/docs/man/nn_poll.3compat.adoc +++ b/docs/man/nn_poll.3compat.adoc @@ -67,7 +67,7 @@ If the _timeout_ is -1, then the function waits forever, or until one of the requested events occurs. WARNING: This function is only suitable for use with sockets obtained with the -`<<nn_socket.3compat#,nn_socket()>>`` function, and is not compatible +`<<nn_socket.3compat#,nn_socket()>>` function, and is not compatible with file descriptors obtained via any other means. This includes file descriptors obtained using the `NN_SNDFD` or `NN_RCVFD` options with `<<nn_getsockopt.3compat#,nn_getsockopt()>>` diff --git a/docs/man/nn_send.3compat.adoc b/docs/man/nn_send.3compat.adoc index 181d8c7f..79029b61 100644 --- a/docs/man/nn_send.3compat.adoc +++ b/docs/man/nn_send.3compat.adoc @@ -38,7 +38,7 @@ is a pointer to the pointer, an extra level of pointer indirection. The message must have been previously allocated by `<<nn_allocmsg.3compat#,nn_allocmsg()>>` or `<<nn_recvmsg.3compat#,nn_recvmsg()>>`, using the same `NN_MSG` size. -In this case, the "`ownership``" of the message shall remain with +In this case, the "`ownership`" of the message shall remain with the caller, unless the function returns 0, indicating that the function has taken responsibility for delivering or disposing of the message. diff --git a/docs/man/nng.7.adoc b/docs/man/nng.7.adoc index 754d9331..425d2c0f 100644 --- a/docs/man/nng.7.adoc +++ b/docs/man/nng.7.adoc @@ -92,7 +92,7 @@ guarantees by performing their own retry and validation schemes.) Each socket can have zero, one, or many "endpoints", which are either _listeners_ or _dialers_. (A given socket may freely choose whether it uses listeners, dialers, or both.) -These "endpoints" provide access to underlying transports, such as TCP, etc. +These "`endpoints`" provide access to underlying transports, such as TCP, etc. Each endpoint is associated with a URL, which is a service address. For dialers, this will be the service address that will be contacted, whereas @@ -130,13 +130,13 @@ to and from the socket with no extra semantic handling. This is possible using "`raw`" mode sockets. Raw mode sockets are generally constructed with a different function, -such as <<nng_req_open.3#,`nng_req0_open_raw()`>>. +such as `<<nng_req_open.3#,nng_req0_open_raw()>>`. Using these sockets, the application can simply send and receive messages, and is responsible for supplying any additional socket semantics. Typically this means that the application will need to inspect message headers on incoming messages, and supply them on outgoing messages. -TIP: The <<nng_device.3#,`nng_device()`>> function only works with raw mode +TIP: The `<<nng_device.3#,nng_device()>>` function only works with raw mode sockets, but as it only forwards the messages, no additional application processing is needed. diff --git a/docs/man/nng_aio.5.adoc b/docs/man/nng_aio.5.adoc index 4353652d..292d13c1 100644 --- a/docs/man/nng_aio.5.adoc +++ b/docs/man/nng_aio.5.adoc @@ -37,15 +37,15 @@ This callback will be executed exactly once. The asynchronous I/O framework in _nng_ also supports cancellation of operations that are already in progress -(see <<nng_aio_cancel.3#,`nng_aio_cancel()`>>), as well setting a maximum +(see `<<nng_aio_cancel.3#,nng_aio_cancel()>>`), as well setting a maximum timeout for them to complete within -(see <<nng_aio_set_timeout.3#,`nng_aio_set_timeout()`>>). +(see `<<nng_aio_set_timeout.3#,nng_aio_set_timeout()>>`). It is also possible to initiate an asynchronous operation, and wait for it to -complete using <<nng_aio_wait.3#,`nng_aio_wait()`>>. +complete using `<<nng_aio_wait.3#,nng_aio_wait()>>`. -These structures are created using the <<nng_aio_alloc.3#,`nng_aio_alloc()`>>, -and destroyed using <<nng_aio_free.3#,`nng_aio_free()`>>. +These structures are created using the `<<nng_aio_alloc.3#,nng_aio_alloc()>>`, +and destroyed using `<<nng_aio_free.3#,nng_aio_free()>>`. == SEE ALSO diff --git a/docs/man/nng_aio_abort.3.adoc b/docs/man/nng_aio_abort.3.adoc index 4216343e..3a68f015 100644 --- a/docs/man/nng_aio_abort.3.adoc +++ b/docs/man/nng_aio_abort.3.adoc @@ -28,7 +28,7 @@ The `nng_aio_abort()` function aborts an operation previously started with the handle _aio_. If the operation is aborted, then the callback for the handle will be called, and the function -<<nng_aio_result.3#,`nng_aio_result()`>> will return the error _err_. +`<<nng_aio_result.3#,nng_aio_result()>>` will return the error _err_. This function does not wait for the operation to be fully aborted, but returns immediately. diff --git a/docs/man/nng_aio_alloc.3.adoc b/docs/man/nng_aio_alloc.3.adoc index 71521f47..9e92dd4a 100644 --- a/docs/man/nng_aio_alloc.3.adoc +++ b/docs/man/nng_aio_alloc.3.adoc @@ -34,22 +34,22 @@ NOTE: The callback _callb_ must not perform any blocking operations, and must complete it's execution quickly. If _callb_ does block, this can lead ultimately to an apparent "hang" or deadlock in the application. -Asynchronous I/O operations all take an <<nng_aio.5#,`nng_aio`>> +Asynchronous I/O operations all take an `<<nng_aio.5#,nng_aio>>` handle such as allocated by this function. Such operations are usually started by a function that returns immediately. The operation is then run asynchronously, and completes sometime later. When that operation is complete, the callback supplied here is called, and that callback is able to determine the result of the operation using -<<nng_aio_result.3#,`nng_aio_result()`>>, -<<nng_aio_count.3#,`nng_aio_count()`>>, -and <<nng_aio_get_output.3#,`nng_aio_get_output()`>>. +`<<nng_aio_result.3#,nng_aio_result()>>`, +`<<nng_aio_count.3#,nng_aio_count()>>`, +and `<<nng_aio_get_output.3#,nng_aio_get_output()>>`. It is possible to wait synchronously for an otherwise asynchronous operation -by using the function <<nng_aio_wait.3#,`nng_aio_wait()`>>. +by using the function `<<nng_aio_wait.3#,nng_aio_wait()>>`. In that case, it is permissible for _callb_ and _arg_ to both be `NULL`. Note that if these are `NULL`, then it will not be possible to determine when the operation is complete except by calling the aforementioned -<<nng_aio_wait.3#,`nng_aio_wait()`>>. +`<<nng_aio_wait.3#,nng_aio_wait()>>`. == RETURN VALUES diff --git a/docs/man/nng_aio_cancel.3.adoc b/docs/man/nng_aio_cancel.3.adoc index 77573bac..51148fa1 100644 --- a/docs/man/nng_aio_cancel.3.adoc +++ b/docs/man/nng_aio_cancel.3.adoc @@ -16,11 +16,11 @@ nng_aio_cancel - cancel asynchronous I/O operation == SYNOPSIS [source, c] ------------ +---- #include <nng/nng.h> void nng_aio_cancel(nng_aio *aio); ------------ +---- == DESCRIPTION @@ -28,7 +28,7 @@ The `nng_aio_cancel()` function aborts an operation previously started with the handle _aio_. If the operation is aborted, then the callback for the handle will be called, and the function -<<nng_aio_result.3#,`nng_aio_result()`>> will return the error `NNG_ECANCELED`. +`<<nng_aio_result.3#,nng_aio_result()>>` will return the error `NNG_ECANCELED`. This function does not wait for the operation to be fully aborted, but returns immediately. @@ -38,7 +38,7 @@ finished, or no operation has been started yet), then this function has no effect. NOTE: This function is the same as calling -<<nng_aio_abort.3#,`nng_aio_abort()`>> with the error `NNG_ECANCELED`. +`<<nng_aio_abort.3#,nng_aio_abort()>>` with the error `NNG_ECANCELED`. == RETURN VALUES diff --git a/docs/man/nng_aio_count.3.adoc b/docs/man/nng_aio_count.3.adoc index dc467abd..8050ce9a 100644 --- a/docs/man/nng_aio_count.3.adoc +++ b/docs/man/nng_aio_count.3.adoc @@ -33,13 +33,13 @@ transfer user data (they may transfer protocol data though) -- in this case this function will generally return zero. This function is most useful when used with operations that make use of -of a scatter/gather vector (set by <<nng_aio_set_iov.3#,`nng_aio_set_iov()`>>). +of a scatter/gather vector (set by `<<nng_aio_set_iov.3#,nng_aio_set_iov()>>`). NOTE: The return value from this function is undefined if the operation has not completed yet. Either call this from the handle's completion callback, or after waiting for the operation to complete with -<<nng_aio_wait.3#,`nng_aio_wait()`>>. +`<<nng_aio_wait.3#,nng_aio_wait()>>`. == RETURN VALUES diff --git a/docs/man/nng_aio_finish.3.adoc b/docs/man/nng_aio_finish.3.adoc index 9d03d859..ee82ed10 100644 --- a/docs/man/nng_aio_finish.3.adoc +++ b/docs/man/nng_aio_finish.3.adoc @@ -27,7 +27,7 @@ void nng_aio_finish(nng_aio *aio, int err); The `nng_aio_finish()` function marks operation associated with _aio_ as complete, with the status _err_. This will be the result returned by -<<nng_aio_result.3#,`nng_aio_result()`>>. +`<<nng_aio_result.3#,nng_aio_result()>>`. This function causes the callback associated with the _aio_ to called. diff --git a/docs/man/nng_aio_free.3.adoc b/docs/man/nng_aio_free.3.adoc index 19a37198..0b19f4be 100644 --- a/docs/man/nng_aio_free.3.adoc +++ b/docs/man/nng_aio_free.3.adoc @@ -28,7 +28,7 @@ The `nng_aio_free()` function frees an allocated asynchronous I/O handle. If any operation is in progress, the operation is canceled, and the caller is blocked until the operation is completely canceled, to ensure that it is safe to deallocate the handle and any associated resources. -(This is done by implicitly calling <<nng_aio_stop.3#,`nng_aio_stop()`>>.) +(This is done by implicitly calling `<<nng_aio_stop.3#,nng_aio_stop()>>`.) == RETURN VALUES diff --git a/docs/man/nng_aio_get_input.3.adoc b/docs/man/nng_aio_get_input.3.adoc index e0e0d545..018f7d04 100644 --- a/docs/man/nng_aio_get_input.3.adoc +++ b/docs/man/nng_aio_get_input.3.adoc @@ -26,7 +26,7 @@ void *nng_aio_get_input(nng_aio *aio, unsigned int index); The `nng_aio_get_input()` function returns the value of the input parameter previously set at _index_ on _aio_ with the -<<nng_aio_set_input.3#,`nng_aio_set_input()`>> function. +`<<nng_aio_set_input.3#,nng_aio_set_input()>>` function. The valid values of _index_ range from zero (0) to three (3), as no operation currently defined can accept more than four parameters. diff --git a/docs/man/nng_aio_get_msg.3.adoc b/docs/man/nng_aio_get_msg.3.adoc index 4ae1c38b..d884c28b 100644 --- a/docs/man/nng_aio_get_msg.3.adoc +++ b/docs/man/nng_aio_get_msg.3.adoc @@ -26,10 +26,10 @@ nng_msg *nng_aio_get_msg(nng_aio *aio); The `nng_aio_get_msg()` function gets any message stored in _aio_ as either a result of a successful receive -(see <<nng_recv_aio.3#,`nng_recv_aio()`>>) -or that was previously stored with <<nng_aio_set_msg.3#,`nng_aio_set_msg()`>>. +(see `<<nng_recv_aio.3#,nng_recv_aio()>>`) +or that was previously stored with `<<nng_aio_set_msg.3#,nng_aio_set_msg()>>`. -IMPORTANT: The `nng_aio` must not have an operation in progress. +IMPORTANT: The `<<nng_aio.5#,nng_aio>>` must not have an operation in progress. == RETURN VALUES diff --git a/docs/man/nng_aio_result.3.adoc b/docs/man/nng_aio_result.3.adoc index 38208d77..a793b9ad 100644 --- a/docs/man/nng_aio_result.3.adoc +++ b/docs/man/nng_aio_result.3.adoc @@ -33,7 +33,7 @@ NOTE: The return value from this function is undefined if the operation has not completed yet. Either call this from the handle's completion callback, or after waiting for the operation to complete with -<<nng_aio_wait.3#,`nng_aio_wait()`>>. +`<<nng_aio_wait.3#,nng_aio_wait()>>`. == RETURN VALUES diff --git a/docs/man/nng_aio_set_input.3.adoc b/docs/man/nng_aio_set_input.3.adoc index dd921d52..696f1513 100644 --- a/docs/man/nng_aio_set_input.3.adoc +++ b/docs/man/nng_aio_set_input.3.adoc @@ -42,7 +42,7 @@ IMPORTANT: It is an error to call this function while the _aio_ is currently in use by an active asynchronous operation. An input parameter set with this function may be retrieved later with -the <<nng_aio_get_input.3#,`nng_aio_get_input()`>> function. +the `<<nng_aio_get_input.3#,nng_aio_get_input()>>` function. == RETURN VALUES diff --git a/docs/man/nng_aio_set_iov.3.adoc b/docs/man/nng_aio_set_iov.3.adoc index b896f5de..ed200a13 100644 --- a/docs/man/nng_aio_set_iov.3.adoc +++ b/docs/man/nng_aio_set_iov.3.adoc @@ -27,7 +27,7 @@ int nng_aio_set_iov(nng_aio *aio, unsigned int niov, nng_iov *iov); The `nng_aio_set_iov()` function sets a ((scatter/gather)) vector _iov_ on the handle _aio_. -The _iov_ is a pointer to an array of _niov_ <<nng_iov.5#,`nng_iov`>> +The _iov_ is a pointer to an array of _niov_ `<<nng_iov.5#,nng_iov>>` structures, which have the following definition: [source, c] diff --git a/docs/man/nng_aio_set_msg.3.adoc b/docs/man/nng_aio_set_msg.3.adoc index 8f3c594f..c0147e65 100644 --- a/docs/man/nng_aio_set_msg.3.adoc +++ b/docs/man/nng_aio_set_msg.3.adoc @@ -25,9 +25,9 @@ void nng_aio_set_msg(nng_aio *aio, nng_msg *msg); == DESCRIPTION The `nng_aio_set_msg()` function sets the message that will be used -for an asynchronous send operation (see <<nng_send_aio.3#,`nng_send_aio()`>>). +for an asynchronous send operation (see `<<nng_send_aio.3#,nng_send_aio()>>`). -IMPORTANT: The `nng_aio` must not have an operation in progress. +IMPORTANT: The `<<nng_aio.5#,nng_aio>>` must not have an operation in progress. == RETURN VALUES diff --git a/docs/man/nng_aio_set_output.3.adoc b/docs/man/nng_aio_set_output.3.adoc index 8eef410a..2f753db7 100644 --- a/docs/man/nng_aio_set_output.3.adoc +++ b/docs/man/nng_aio_set_output.3.adoc @@ -39,7 +39,7 @@ NOTE: Note that attempts to set results with an _index_ greater than three (3) will be ignored. An output result set with this function may be retrieved later with -the <<nng_aio_get_output.3#,`nng_aio_get_output()`>> function. +the `<<nng_aio_get_output.3#,nng_aio_get_output()>>` function. == RETURN VALUES diff --git a/docs/man/nng_aio_stop.3.adoc b/docs/man/nng_aio_stop.3.adoc index 02c258f8..12e8d1da 100644 --- a/docs/man/nng_aio_stop.3.adoc +++ b/docs/man/nng_aio_stop.3.adoc @@ -41,7 +41,7 @@ completing its callback function. TIP: When multiple asynchronous I/O handles are in use and need to be shut down, it is safest to stop all of them, before deallocating any of -this with <<nng_aio_free.3#,`nng_aio_free()`>>, particularly if the callbacks +this with `<<nng_aio_free.3#,nng_aio_free()>>`, particularly if the callbacks might attempt to reschedule additional operations. == RETURN VALUES diff --git a/docs/man/nng_alloc.3.adoc b/docs/man/nng_alloc.3.adoc index a43140d1..3b6e27dd 100644 --- a/docs/man/nng_alloc.3.adoc +++ b/docs/man/nng_alloc.3.adoc @@ -29,9 +29,9 @@ at least _size_ bytes. The memory will be 64-bit aligned. The returned memory can be used to hold message buffers, in which -case it can be directly passed to <<nng_send.3#,`nng_send()`>> using +case it can be directly passed to `<<nng_send.3#,nng_send()>>` using the flag `NNG_FLAG_ALLOC`. Alternatively, it can be freed when no -longer needed using <<nng_free.3#,`nng_free()`>>. +longer needed using `<<nng_free.3#,nng_free()>>`. IMPORTANT: Do not use the system `free()` function to release this memory. On some platforms this may work, but it is not guaranteed and may lead diff --git a/docs/man/nng_bus.7.adoc b/docs/man/nng_bus.7.adoc index d5c57710..bb993f7c 100644 --- a/docs/man/nng_bus.7.adoc +++ b/docs/man/nng_bus.7.adoc @@ -49,7 +49,7 @@ the more likely that message loss is to occur. === Socket Operations -The <<nng_bus_open.3#,`nng_bus0_open()`>> functions create a bus socket. +The `<<nng_bus_open.3#,nng_bus0_open()>>` functions create a bus socket. This socket may be used to send and receive messages. Sending messages will attempt to deliver to each directly connected peer. diff --git a/docs/man/nng_close.3.adoc b/docs/man/nng_close.3.adoc index 3f1c68f3..e1753dc3 100644 --- a/docs/man/nng_close.3.adoc +++ b/docs/man/nng_close.3.adoc @@ -27,7 +27,7 @@ int nng_close(nng_socket s); The `nng_close()` function closes the supplied socket, _s_. Messages that have been submitted for sending may be flushed or delivered, depending upon the transport and the setting of the -<<nng_options.5#NNG_OPT_LINGER,`NNG_OPT_LINGER`>> option. +`<<nng_options.5#NNG_OPT_LINGER,NNG_OPT_LINGER>>` option. Further attempts to use the socket after this call returns will result in `NNG_ECLOSED`. diff --git a/docs/man/nng_compat.3compat.adoc b/docs/man/nng_compat.3compat.adoc index 42b0942e..77e55313 100644 --- a/docs/man/nng_compat.3compat.adoc +++ b/docs/man/nng_compat.3compat.adoc @@ -80,7 +80,7 @@ ifdef::backend-pdf[] // Add links for the following as they are written. [.hdlist,width=90%, grid=rows,cols="1,2", align="center"] |=== -|`<<nn_socket.3compat#,nn_socket()`>>|create socket +|`<<nn_socket.3compat#,nn_socket()>>`|create socket |`<<nn_getsockopt.3compat#,nn_getsockopt()>>`|get socket option |`<<nn_setsockopt.3compat#,nn_setsockopt()>>`|set socket option |`<<nn_bind.3compat#,nn_bind()>>`|accept connections from remote peers diff --git a/docs/man/nng_ctx.5.adoc b/docs/man/nng_ctx.5.adoc index ada117c3..483a4c1f 100644 --- a/docs/man/nng_ctx.5.adoc +++ b/docs/man/nng_ctx.5.adoc @@ -75,8 +75,8 @@ applications, and should be used in lieu of WARNING: Use of file descriptor polling (with descriptors obtained using the -<<nng_options.5#NNG_OPT_RECVFD,`NNG_OPT_RECVFD`>> or -<<nng_options.5#NNG_OPT_SENDFD,`NNG_OPT_SENDFD`>> options) while contexts +`<<nng_options.5#NNG_OPT_RECVFD,NNG_OPT_RECVFD>>` or +`<<nng_options.5#NNG_OPT_SENDFD,NNG_OPT_SENDFD>>` options) while contexts are in use on the same socket is not supported, and may lead to unpredictable behavior. These asynchronous methods should not be mixed on the same socket. @@ -134,8 +134,8 @@ echo(void *arg) Given the above fragment, the following example shows setting up the service. It assumes that the <<nng_socket.5#,socket>> has already been created and any transports set up as well with functions such as -<<nng_dial.3#,`nng_dial()`>> -or <<nng_listen.3#,`nng_listen()`>>. +`<<nng_dial.3#,nng_dial()>>` +or `<<nng_listen.3#,nng_listen()>>`. [source,c] ---- diff --git a/docs/man/nng_ctx_close.3.adoc b/docs/man/nng_ctx_close.3.adoc index 16d9432e..32cb44f6 100644 --- a/docs/man/nng_ctx_close.3.adoc +++ b/docs/man/nng_ctx_close.3.adoc @@ -27,7 +27,7 @@ int nng_ctx_close(nng_ctx ctx); The `nng_ctx_close()` function closes the context _ctx_. Messages that have been submitted for sending may be flushed or delivered, depending upon the transport and the setting of the -<<nng_options.5#NNG_OPT_LINGER,`NNG_OPT_LINGER`>> option. +`<<nng_options.5#NNG_OPT_LINGER,NNG_OPT_LINGER>>` option. Further attempts to use the context after this call returns will result in `NNG_ECLOSED`. @@ -35,7 +35,7 @@ Threads waiting for operations on the context when this call is executed may also return with an `NNG_ECLOSED` result. NOTE: Closing the socket associated with _ctx_ -(using <<nng_close.3#,`nng_close()`>>) also closes this context. +(using `<<nng_close.3#,nng_close()>>`) also closes this context. == RETURN VALUES diff --git a/docs/man/nng_ctx_getopt.3.adoc b/docs/man/nng_ctx_getopt.3.adoc index b20ea3b4..d6a19a16 100644 --- a/docs/man/nng_ctx_getopt.3.adoc +++ b/docs/man/nng_ctx_getopt.3.adoc @@ -93,9 +93,9 @@ typically for buffer sizes, message maximum sizes, and similar options. ==== `nng_ctx_getopt_string()` This function is used to retrieve a string into _strp_. -This string is created from the source using <<nng_strdup.3#,`nng_strdup()`>> +This string is created from the source using `<<nng_strdup.3#,nng_strdup()>>` and consequently must be freed by the caller using -<<nng_strfree.3#,`nng_strfree()`>> when it is no longer needed. +`<<nng_strfree.3#,nng_strfree()>>` when it is no longer needed. ==== `nng_ctx_getopt_uint64()` This function is used to retrieve a 64-bit unsigned value into the value diff --git a/docs/man/nng_ctx_id.3.adoc b/docs/man/nng_ctx_id.3.adoc index 56d9d7bd..ba79684c 100644 --- a/docs/man/nng_ctx_id.3.adoc +++ b/docs/man/nng_ctx_id.3.adoc @@ -29,10 +29,10 @@ if it is valid. Otherwise it returns `-1`. NOTE: A context is considered valid if it was ever opened with -<<nng_ctx_open.3#,`nng_ctx_open`>> function. +`<<nng_ctx_open.3#,nng_ctx_open()>>` function. Contexts that are allocated on the stack or statically should be initialized with the macro -<<nng_ctx.5#NNG_CTX_INITIALIZER,`NNG_CTX_INITIALIZER`>> to ensure that +`<<nng_ctx.5#NNG_CTX_INITIALIZER,NNG_CTX_INITIALIZER>>` to ensure that they cannot be confused with a valid context before they are opened. == RETURN VALUES diff --git a/docs/man/nng_ctx_recv.3.adoc b/docs/man/nng_ctx_recv.3.adoc index d4e84b00..03aa5de8 100644 --- a/docs/man/nng_ctx_recv.3.adoc +++ b/docs/man/nng_ctx_recv.3.adoc @@ -29,9 +29,9 @@ The `nng_ctx_recv()` receives a <<nng_msg.5#,message>> using the When a message is successfully received by the context, it is stored in the _aio_ by an internal call equivalent to -<<nng_aio_set_msg.3#,`nng_aio_set_msg()`>>, then the completion +`<<nng_aio_set_msg.3#,nng_aio_set_msg()>>`, then the completion callback on the _aio_ is executed. -In this case, <<nng_aio_result.3#,`nng_aio_result()`>> will +In this case, `<<nng_aio_result.3#,nng_aio_result()>>` will return zero. The callback function is responsible for retrieving the message and disposing of it appropriately. @@ -42,7 +42,7 @@ case can lead to memory leaks. If for some reason the asynchronous receive cannot be completed successfully (including by being canceled or timing out), then the callback will still be executed, -but <<nng_aio_result.3#,`nng_aio_result()`>> will be non-zero. +but `<<nng_aio_result.3#,nng_aio_result()>>` will be non-zero. NOTE: The semantics of what receiving a message means varies from protocol to protocol, so examination of the protocol documentation is encouraged. diff --git a/docs/man/nng_ctx_send.3.adoc b/docs/man/nng_ctx_send.3.adoc index 95c1a118..9780c0bd 100644 --- a/docs/man/nng_ctx_send.3.adoc +++ b/docs/man/nng_ctx_send.3.adoc @@ -28,11 +28,11 @@ The `nng_ctx_send()` sends a <<nng_msg.5#,message>> using the <<nng_ctx.5#,context>> _ctx_ asynchronously. The message to send must have previously been set on the _aio_ -using the <<nng_aio_set_msg.3#,`nng_aio_set_msg()`>> function. +using the `<<nng_aio_set_msg.3#,nng_aio_set_msg()>>` function. The function assumes "`ownership`" of the message. If the message was successfully queued for delivery to the socket, -then the _aio_ will be completed, and <<nng_aio_result.3#,`nng_aio_result()`>> +then the _aio_ will be completed, and `<<nng_aio_result.3#,nng_aio_result()>>` will return zero. In this case the socket will dispose of the message when it is finished with it. @@ -44,13 +44,13 @@ may still be buffered in the sending socket, buffered in the receiving socket, or in flight over physical media. If the operation fails for any reason (including cancellation or timeout), -then the _aio_ callback will be executed and <<nng_aio_result.3#,`nng_aio_result()`>> -will return a non-zero error status. +then the _aio_ callback will be executed and +`<<nng_aio_result.3#,nng_aio_result()>>` will return a non-zero error status. In this case, the callback has a responsibity to retrieve the message from -the _aio_ with <<nng_aio_get_msg.3#,`nng_aio_get_msg()`>> and dispose of +the _aio_ with `<<nng_aio_get_msg.3#,nng_aio_get_msg()>>` and dispose of it appropriately. (This may include retrying the send operation on the same or a different -socket, or deallocating the message with <<nng_msg_free.3#,`nng_msg_free()`>>.) +socket, or deallocating the message with `<<nng_msg_free.3#,nng_msg_free()>>`.) NOTE: The semantics of what sending a message means varies from protocol to protocol, so examination of the protocol documentation is encouraged. @@ -58,7 +58,7 @@ protocol, so examination of the protocol documentation is encouraged. TIP: Context send operations are asynchronous. If a synchronous operation is needed, one can be constructed by using a `NULL` callback on the _aio_ and then waiting for the operation using -<<nng_aio_wait.3#,`nng_aio_wait()`>>. +`<<nng_aio_wait.3#,nng_aio_wait()>>`. == RETURN VALUES diff --git a/docs/man/nng_ctx_setopt.3.adoc b/docs/man/nng_ctx_setopt.3.adoc index 4ab36e07..a81b20f4 100644 --- a/docs/man/nng_ctx_setopt.3.adoc +++ b/docs/man/nng_ctx_setopt.3.adoc @@ -67,7 +67,7 @@ The _ival_ is passed to the option. ==== `nng_ctx_setopt_ms()` This function is used to configure time durations (such as timeouts) using -type <<nng_duration.5#,`nng_duration`>>. +type `<<nng_duration.5#,nng_duration>>`. The duration _dur_ is an integer number of milliseconds. ==== `nng_ctx_setopt_size()` diff --git a/docs/man/nng_cv_alloc.3supp.adoc b/docs/man/nng_cv_alloc.3supp.adoc index 0668298f..ac059a92 100644 --- a/docs/man/nng_cv_alloc.3supp.adoc +++ b/docs/man/nng_cv_alloc.3supp.adoc @@ -32,11 +32,11 @@ the mutex _mtx_, and returns it in _cvp_. Every condition variable is associated with a mutex, which must be owned when a thread waits for the condition using -<<nng_cv_wait.3supp#,`nng_cv_wait()`>> or -<<nng_cv_until.3supp#,`nng_cv_until()`>>. +`<<nng_cv_wait.3supp#,nng_cv_wait()>>` or +`<<nng_cv_until.3supp#,nng_cv_until()>>`. The mutex must also be owned when signaling the condition using the -<<nng_cv_wake.3supp#,`nng_cv_wake()`>> or -<<nng_cv_wake1.3supp#,`nng_cv_wake1()`>> functions. +`<<nng_cv_wake.3supp#,nng_cv_wake()>>` or +`<<nng_cv_wake1.3supp#,nng_cv_wake1()>>` functions. == RETURN VALUES diff --git a/docs/man/nng_cv_until.3supp.adoc b/docs/man/nng_cv_until.3supp.adoc index 4d39ecc0..9cf49e4d 100644 --- a/docs/man/nng_cv_until.3supp.adoc +++ b/docs/man/nng_cv_until.3supp.adoc @@ -26,9 +26,9 @@ int nng_cv_wait(nng_cv *cv, nng_time when); == DESCRIPTION The `nng_cv_until()` waits until either the condition variable _cv_ is signaled -by another thread calling either <<nng_cv_wake.3supp#,`nng_cv_wake()`>> or -<<nng_cv_wake1.3supp#,`nng_cv_wake1()`>>, or the system clock (as tracked -by <<nng_clock.3supp#,`nng_clock()`>>) reaches _when_. +by another thread calling either `<<nng_cv_wake.3supp#,nng_cv_wake()>>` or +`<<nng_cv_wake1.3supp#,nng_cv_wake1()>>`, or the system clock (as tracked +by `<<nng_clock.3supp#,nng_clock()>>`) reaches _when_. The caller must have have ownership of the mutex that was used when _cv_ was allocated. diff --git a/docs/man/nng_cv_wait.3supp.adoc b/docs/man/nng_cv_wait.3supp.adoc index 034b3ea9..005fe0c7 100644 --- a/docs/man/nng_cv_wait.3supp.adoc +++ b/docs/man/nng_cv_wait.3supp.adoc @@ -26,8 +26,8 @@ void nng_cv_wait(nng_cv *cv); == DESCRIPTION The `nng_cv_wait()` waits for the condition variable _cv_ to be signaled -by another thread calling either <<nng_cv_wake.3supp#,`nng_cv_wake()`>> or -<<nng_cv_wake1.3supp#,`nng_cv_wake1()`>>. +by another thread calling either `<<nng_cv_wake.3supp#,nng_cv_wake()>>` or +`<<nng_cv_wake1.3supp#,nng_cv_wake1()>>`. The caller must have have ownership of the mutex that was used when _cv_ was allocated. diff --git a/docs/man/nng_cv_wake.3supp.adoc b/docs/man/nng_cv_wake.3supp.adoc index ad8dadfe..75642884 100644 --- a/docs/man/nng_cv_wake.3supp.adoc +++ b/docs/man/nng_cv_wake.3supp.adoc @@ -26,8 +26,8 @@ void nng_cv_wake(nng_cv *cv); == DESCRIPTION The `nng_cv_wake()` wakes any threads waiting for the condition variable _cv_ -to be signaled in the <<nng_cv_wait.3supp#,`nng_cv_wait()`>> or -<<nng_cv_until.3supp#,`nng_cv_until()`>> functions. +to be signaled in the `<<nng_cv_wait.3supp#,nng_cv_wait()>>` or +`<<nng_cv_until.3supp#,nng_cv_until()>>` functions. The caller must have have ownership of the mutex that was used when _cv_ was allocated. @@ -38,7 +38,7 @@ will check, while holding the mutex. TIP: This function wakes all threads, which is generally safer but can lead to a problem known as the "`thundering herd`" when there are many waiters, as they are all woken simultaneously. -See <<nng_cv_wake1.3supp#,`nng_cv_wake1()`>> for a solution to this problem. +See `<<nng_cv_wake1.3supp#,nng_cv_wake1()>>` for a solution to this problem. == RETURN VALUES diff --git a/docs/man/nng_cv_wake1.3supp.adoc b/docs/man/nng_cv_wake1.3supp.adoc index 1938a702..29a4ed88 100644 --- a/docs/man/nng_cv_wake1.3supp.adoc +++ b/docs/man/nng_cv_wake1.3supp.adoc @@ -27,8 +27,8 @@ void nng_cv_wake1(nng_cv *cv); The `nng_cv_wake1()` wakes at most one thread waiting for the condition variable _cv_ -to be signaled in the <<nng_cv_wait.3supp#,`nng_cv_wait()`>> or -<<nng_cv_until.3supp#,`nng_cv_until()`>> functions. +to be signaled in the `<<nng_cv_wait.3supp#,nng_cv_wait()>>` or +`<<nng_cv_until.3supp#,nng_cv_until()>>` functions. The caller must have have ownership of the mutex that was used when _cv_ was allocated. @@ -39,7 +39,7 @@ will check, while holding the mutex. TIP: While this function avoids the "`thundering herd`" problem, the caller cannot predict which waiter will be woken, and so the design must ensure that it is sufficient that _any_ waiter be woken. -When in doubt, it is safer to use <<nng_cv_wake.3supp#,`nng_cv_wake()`>>. +When in doubt, it is safer to use `<<nng_cv_wake.3supp#,nng_cv_wake()>>`. == RETURN VALUES diff --git a/docs/man/nng_device.3.adoc b/docs/man/nng_device.3.adoc index aaf71af6..4f036d03 100644 --- a/docs/man/nng_device.3.adoc +++ b/docs/man/nng_device.3.adoc @@ -34,15 +34,15 @@ reliability, and isolation. Only <<nng_options.5#NNG_OPT_RAW,raw>> mode sockets may be used with this function. These can be created using `_raw` forms of the various socket constructors, -such as <<nng_req_open.3#,`nng_req0_open_raw()`>>. +such as `<<nng_req_open.3#,nng_req0_open_raw()>>`. The `nng_device()` function does not return until one of the sockets is closed. === Reflectors -One of the sockets may be passed the special value `-1` (cast to an, -<<nng_socket.5#,`nng_socket`>> of course). +One of the sockets may be passed an inititalize `-1` (cast to an, +`<<nng_socket.5#,nng_socket>>` of course). If this is the case, then the other socket must be valid, and must be a protocol that is bidirectional and can peer with itself (such as <<nng_pair.7#,_pair_>> or @@ -81,7 +81,7 @@ In these cases, the default limit (usually 8), ensures that messages will self-terminate when they have passed through too many forwarders, protecting the network from unlimited message amplification that can arise through misconfiguration. -This is controlled via the <<nng_options.5#NNG_OPT_MAXTTL,`NNG_OPT_MAXTTL`>> +This is controlled via the `<<nng_options.5#NNG_OPT_MAXTTL,NNG_OPT_MAXTTL>>` option. IMPORTANT: Not all protocols have support for guarding against forwarding loops, diff --git a/docs/man/nng_dial.3.adoc b/docs/man/nng_dial.3.adoc index 525f092a..d2eb7605 100644 --- a/docs/man/nng_dial.3.adoc +++ b/docs/man/nng_dial.3.adoc @@ -25,7 +25,7 @@ int nng_dial(nng_socket s, const char *url, nng_dialer *dp, int flags); == DESCRIPTION The `nng_dialer()` function creates a newly initialized -<<nng_dialer.5#,`nng_dialer`>> object, +`<<nng_dialer.5#,nng_dialer>>` object, associated with socket _s_, and configured to listen at the address specified by _url_, and starts it. If the value of _dp_ is not `NULL`, then @@ -62,8 +62,8 @@ it also generally makes diagnosing failures somewhat more difficult. Because the dialer is started immediately, it is generally not possible to apply extra configuration; if that is needed applications should consider -using <<nng_dialer_create.3#,`nng_dialer_create()`>> and -<<nng_dialer_start.3#,`nng_dialer_start()`>> instead. +using `<<nng_dialer_create.3#,nng_dialer_create()>>` and +`<<nng_dialer_start.3#,nng_dialer_start()>>` instead. == RETURN VALUES diff --git a/docs/man/nng_dialer.5.adoc b/docs/man/nng_dialer.5.adoc index 3f742c21..b2c24325 100644 --- a/docs/man/nng_dialer.5.adoc +++ b/docs/man/nng_dialer.5.adoc @@ -26,7 +26,7 @@ typedef struct nng_dialer_s nng_dialer; (((dialer))) An `nng_dialer` is a handle to a "`dialer`" object, which is responsible for -creating a single <<nng_pipe.5#,`nng_pipe`>> at a time by +creating a single `<<nng_pipe.5#,nng_pipe>>` at a time by establishing an outgoing connection. If the connection is broken, or fails, the dialer object will automatically @@ -34,16 +34,16 @@ attempt to reconnect, and will keep doing so until the dialer or socket is destroyed. Dialer objects are created by the -<<nng_dialer_create.3#,`nng_dialer_create()`>> -or <<nng_dial.3#,`nng_dial()`>> functions, and are always "`owned`" -by a single <<nng_socket.5#,`nng_socket`>>. +`<<nng_dialer_create.3#,nng_dialer_create()>>` +or `<<nng_dial.3#,nng_dial()>>` functions, and are always "`owned`" +by a single `<<nng_socket.5#,nng_socket>>`. IMPORTANT: The `nng_dialer` structure is always passed by value (both for input parameters and return values), and should be treated opaquely. Passing structures this way ensures gives the compiler a chance to perform accurate type checks in functions passing values of this type. -TIP: A given <<nng_socket.5#,`nng_socket`>> may have multiple dialer +TIP: A given `<<nng_socket.5#,nng_socket>>` may have multiple dialer objects, multiple <<nng_listener.5#,listener>> objects, or even some of both. @@ -55,7 +55,7 @@ This orthogonality can lead to innovative solutions to otherwise challenging communications problems. Dialer objects may be destroyed by the -<<nng_dialer_close.3#,`nng_pipe_close()`>> function. +`<<nng_dialer_close.3#,nng_dialer_close()>>` function. They are also closed when their "`owning`" socket is closed. [[NNG_DIALER_INITIALIZER]] diff --git a/docs/man/nng_dialer_close.3.adoc b/docs/man/nng_dialer_close.3.adoc index 01ac91ed..a89ad683 100644 --- a/docs/man/nng_dialer_close.3.adoc +++ b/docs/man/nng_dialer_close.3.adoc @@ -25,7 +25,7 @@ int nng_dialer_close(nng_dialer d); == DESCRIPTION The `nng_dialer_close()` function closes the listener _d_. -This also closes any <<nng_pipe.5#,`nng_pipe`>> ojects that have +This also closes any `<<nng_pipe.5#,nng_pipe>>` ojects that have been created by the dialer. Once this function returns, the dialer _d_ and any of its resources diff --git a/docs/man/nng_dialer_create.3.adoc b/docs/man/nng_dialer_create.3.adoc index 3181f10e..b7ce82fa 100644 --- a/docs/man/nng_dialer_create.3.adoc +++ b/docs/man/nng_dialer_create.3.adoc @@ -25,7 +25,7 @@ int nng_dialer_create(nng_dialer *dialerp, nng_socket s, const char *url); == DESCRIPTION The `nng_dialer_create()` function creates a newly initialized -<<nng_dialer.5#,`nng_dialer`>> object, associated with socket _s_, +`<<nng_dialer.5#,nng_dialer>>` object, associated with socket _s_, and configured to connect to the address specified by _url_, and stores a pointer to at the location referenced by _dialerp_. @@ -47,13 +47,13 @@ socket might have associated dialers, but might also have associated listeners. It may even have some of each at the same time! The dialer is not started, but may be further configured with -the <<nng_dialer_setopt.3#,`nng_dialer_setopt()`>> family of functions. +the `<<nng_dialer_setopt.3#,nng_dialer_setopt()>>` family of functions. Once it is fully configured, the dialer may be started using the -<<nng_dialer_start.3#,`nng_dialer_start()`>> function. +`<<nng_dialer_start.3#,nng_dialer_start()>>` function. TIP: If no specific configuration is required, consider using the -simpler <<nng_dial.3#,`nng_dial()`>> function instead. +simpler `<<nng_dial.3#,nng_dial()>>` function instead. == RETURN VALUES diff --git a/docs/man/nng_dialer_getopt.3.adoc b/docs/man/nng_dialer_getopt.3.adoc index bdabc5d9..e9054b89 100644 --- a/docs/man/nng_dialer_getopt.3.adoc +++ b/docs/man/nng_dialer_getopt.3.adoc @@ -103,15 +103,15 @@ This function is used to retrieve a size into the pointer _zp_, typically for buffer sizes, message maximum sizes, and similar options. ==== `nng_dialer_getopt_sockaddr()` -This function is used to retrieve an <<nng_sockaddr.5#,`nng_sockaddr`>> +This function is used to retrieve an `<<nng_sockaddr.5#,nng_sockaddr>>` into the value referenced by _sap_. ==== `nng_dialer_getopt_string()` This function is used to retrieve a string into _strp_. -This string is created from the source using <<nng_strdup.3#,`nng_strdup()`>> +This string is created from the source using `<<nng_strdup.3#,nng_strdup()>>` and consequently must be freed by the caller using -<<nng_strfree.3#,`nng_strfree()`>> when it is no longer needed. +`<<nng_strfree.3#,nng_strfree()>>` when it is no longer needed. ==== `nng_dialer_getopt_uint64()` This function is used to retrieve a 64-bit unsigned value into the value diff --git a/docs/man/nng_dialer_id.3.adoc b/docs/man/nng_dialer_id.3.adoc index cf8936b5..a25125f4 100644 --- a/docs/man/nng_dialer_id.3.adoc +++ b/docs/man/nng_dialer_id.3.adoc @@ -29,11 +29,11 @@ if it is valid. Otherwise it returns `-1`. NOTE: A dialer is considered valid if it was ever created with the -<<nng_dialer_create.3#,`nng_dialer_create`>> or -<<nng_dial.3#,`nng_dial`>> functions. +`<<nng_dialer_create.3#,nng_dialer_create>>` or +`<<nng_dial.3#,nng_dial>>` functions. Dialers that are allocated on the stack or statically should be initialized with the macro -<<nng_ctx.5#NNG_DIALER_INITIALIZER,`NNG_DIALER_INITIALIZER`>> to ensure that +`<<nng_ctx.5#NNG_DIALER_INITIALIZER,NNG_DIALER_INITIALIZER>>` to ensure that they cannot be confused with a valid dialer before they are created properly. == RETURN VALUES diff --git a/docs/man/nng_dialer_setopt.3.adoc b/docs/man/nng_dialer_setopt.3.adoc index 330657d0..540d5c2b 100644 --- a/docs/man/nng_dialer_setopt.3.adoc +++ b/docs/man/nng_dialer_setopt.3.adoc @@ -75,14 +75,14 @@ The _ival_ is passed to the option. ==== `nng_dialer_setopt_ms()` This function is used to configure time durations (such as timeouts) using -type <<nng_duration.5#,`nng_duration`>>. +type `<<nng_duration.5#,nng_duration>>`. The duration _dur_ is an integer number of milliseconds. ==== `nng_dialer_setopt_ptr()` This function is used to pass a pointer, _ptr_, to structured data. The data referenced by _ptr_ is generally managed by other functions. For example, TLS configuration objects created with -(<<nng_tls_config_alloc.3tls#,`nng_tls_config_alloc()`>>) +(`<<nng_tls_config_alloc.3tls#,nng_tls_config_alloc()>>`) can be passed this way. Note that this form is somewhat special in that the object is generally not copied, but instead the *pointer* to the object is copied. diff --git a/docs/man/nng_free.3.adoc b/docs/man/nng_free.3.adoc index d17f3da5..ac110db1 100644 --- a/docs/man/nng_free.3.adoc +++ b/docs/man/nng_free.3.adoc @@ -25,8 +25,8 @@ void nng_free(void *ptr, size_t size); == DESCRIPTION The `nng_free()` function deallocates a memory region of size _size_, -that was previously allocated by <<nng_alloc.3#,`nng_alloc()`>> or -<<nng_recv.3#,`nng_recv()`>> with the `NNG_FLAG_ALLOC` flag. +that was previously allocated by `<<nng_alloc.3#,nng_alloc()>>` or +`<<nng_recv.3#,nng_recv()>>` with the `NNG_FLAG_ALLOC` flag. IMPORTANT: It is very important that _size_ match the allocation size used to allocate the memory. diff --git a/docs/man/nng_getopt.3.adoc b/docs/man/nng_getopt.3.adoc index 306efbe9..45c5a295 100644 --- a/docs/man/nng_getopt.3.adoc +++ b/docs/man/nng_getopt.3.adoc @@ -101,9 +101,9 @@ typically for buffer sizes, message maximum sizes, and similar options. ==== `nng_getopt_string()` This function is used to retrieve a string into _strp_. -This string is created from the source using <<nng_strdup.3#,`nng_strdup()`>> +This string is created from the source using `<<nng_strdup.3#,nng_strdup()>>` and consequently must be freed by the caller using -<<nng_strfree.3#,`nng_strfree()`>> when it is no longer needed. +`<<nng_strfree.3#,nng_strfree()>>` when it is no longer needed. ==== `nng_getopt_uint64()` This function is used to retrieve a 64-bit unsigned value into the value diff --git a/docs/man/nng_http_client_connect.3http.adoc b/docs/man/nng_http_client_connect.3http.adoc index 47fcb4e0..397c7f2f 100644 --- a/docs/man/nng_http_client_connect.3http.adoc +++ b/docs/man/nng_http_client_connect.3http.adoc @@ -31,12 +31,12 @@ _client_ was configured with. The result of the operation will be stored in the _aio_ when the operation is complete, and will be obtainable via -<<nng_aio_result.3#,`nng_aio_result()`>>. +`<<nng_aio_result.3#,nng_aio_result()>>`. On success, a pointer to the underlying HTTP client (type `nng_http_conn *`) will be stored in the first output result of the _aio_, and can be obtained by -<<nng_aio_get_output.3#,`nng_aio_get_output()`>> with an _index_ of zero (0). +`<<nng_aio_get_output.3#,nng_aio_get_output()>>` with an _index_ of zero (0). == RETURN VALUES diff --git a/docs/man/nng_http_client_free.3http.adoc b/docs/man/nng_http_client_free.3http.adoc index 6158143c..33d6cf05 100644 --- a/docs/man/nng_http_client_free.3http.adoc +++ b/docs/man/nng_http_client_free.3http.adoc @@ -29,7 +29,7 @@ The `nng_http_client_free()` frees the HTTP client and any associated resources referenced by _client_. NOTE: Any connections created by -<<nng_http_client_connect.3http#,`nng_http_client_connect()`>> are unaffected, +`<<nng_http_client_connect.3http#,nng_http_client_connect()>>` are unaffected, and so the caller must close those explicitly if desired. == RETURN VALUES diff --git a/docs/man/nng_http_client_set_tls.3http.adoc b/docs/man/nng_http_client_set_tls.3http.adoc index 75686778..5ed8bda8 100644 --- a/docs/man/nng_http_client_set_tls.3http.adoc +++ b/docs/man/nng_http_client_set_tls.3http.adoc @@ -30,10 +30,10 @@ The `nng_http_client_set_tls()` sets the TLS configuration of _client_ to _cfg_. This change overwrites any previous TLS configuration. IMPORTANT: This also invalidates any previously obtained values from -<<nng_http_client_get_tls.3http#,`nng_http_client_get_tls()`>>. +`<<nng_http_client_get_tls.3http#,nng_http_client_get_tls()>>`. NOTE: Any connections established with -<<nng_http_client_connect.3http#,`nng_http_client_connect()`>> +`<<nng_http_client_connect.3http#,nng_http_client_connect()>>` will continue to use any TLS configuration that they were started with. == RETURN VALUES diff --git a/docs/man/nng_http_conn_read.3http.adoc b/docs/man/nng_http_conn_read.3http.adoc index d6094ff0..f6e9fad1 100644 --- a/docs/man/nng_http_conn_read.3http.adoc +++ b/docs/man/nng_http_conn_read.3http.adoc @@ -29,20 +29,20 @@ The `nng_http_conn_read()` function starts an asynchronous read from the HTTP connection _conn_, into the scatter/gather vector located in the asynchronous I/O structure _aio_. -NOTE: The <<nng_aio_set_iov.3#,`nng_aio_set_iov()`>> function must have been +NOTE: The `<<nng_aio_set_iov.3#,nng_aio_set_iov()>>` function must have been called first, to set the scatter/gather vector for _aio_. 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.3#,`nng_aio_result()`>>. +`<<nng_aio_result.3#,nng_aio_result()>>`. That result will either be zero or an error code. The I/O operation completes as soon as at least one byte has been read, or an error has occurred. Therefore, the number of bytes read may be less than requested. The actual number of bytes read can be determined with -<<nng_aio_count.3#,`nng_aio_count()`>>. +`<<nng_aio_count.3#,nng_aio_count()>>`. TIP: This function is intended to facilitate uses cases that involve changing the protocol from HTTP, such as WebSocket. diff --git a/docs/man/nng_http_conn_read_all.3http.adoc b/docs/man/nng_http_conn_read_all.3http.adoc index 78a89a13..0a8140fd 100644 --- a/docs/man/nng_http_conn_read_all.3http.adoc +++ b/docs/man/nng_http_conn_read_all.3http.adoc @@ -29,21 +29,22 @@ The `nng_http_conn_read_all()` function starts an asynchronous read from the HTTP connection _conn_, into the scatter/gather vector located in the asynchronous I/O structure _aio_. -NOTE: The <<nng_aio_set_iov.3#,`nng_aio_set_iov()`>> function must have been +NOTE: The `<<nng_aio_set_iov.3#,nng_aio_set_iov()>>` function must have been called first, to set the scatter/gather vector for _aio_. -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.3#,`nng_aio_result()`>>. That result will -either be zero or an error code. +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.3#,nng_aio_result()>>`. +That result will either be zero or an error code. The I/O operation completes only when the entire amount of data -requested has been read, or an error has occurred. If the operation +requested has been read, or an error has occurred. +If the operation completes successfully, then the entire requested data has been read. -It is still possible for a partial read to complete in the event of an -error. The actual number of bytes read can be determined with -<<nng_aio_count.3#,`nng_aio_count()`>>. +It is still possible for a partial read to complete in the event of an error. +The actual number of bytes read can be determined with +`<<nng_aio_count.3#,nng_aio_count()>>`. TIP: The main purpose for this function is to faciliate reading HTTP body content, after first determining the length of the body content diff --git a/docs/man/nng_http_conn_read_req.3http.adoc b/docs/man/nng_http_conn_read_req.3http.adoc index e667455d..4e1c5bf3 100644 --- a/docs/man/nng_http_conn_read_req.3http.adoc +++ b/docs/man/nng_http_conn_read_req.3http.adoc @@ -33,12 +33,12 @@ of the related headers. NOTE: Any HTTP entity/body data associated with the request is *not* read automatically. The caller should use -<<nng_http_conn_read_all.3http#,`nng_http_conn_read_all()`>> +`<<nng_http_conn_read_all.3http#,nng_http_conn_read_all()>>` to read the entity data, based on the details of the request itself. 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.3#,`nng_aio_result()`>>. +may be obtained via `<<nng_aio_result.3#,nng_aio_result()>>`. That result will either be zero or an error code. == RETURN VALUES diff --git a/docs/man/nng_http_conn_read_res.3http.adoc b/docs/man/nng_http_conn_read_res.3http.adoc index 6e00adc8..4a31d0c8 100644 --- a/docs/man/nng_http_conn_read_res.3http.adoc +++ b/docs/man/nng_http_conn_read_res.3http.adoc @@ -33,13 +33,13 @@ of the related headers. NOTE: Any HTTP entity/body data associated with the response is *not* read automatically. The caller should use -<<nng_http_conn_read_all.3http#,`nng_http_conn_read_all`>> to read the entity +`<<nng_http_conn_read_all.3http#,nng_http_conn_read_all>>` to read the entity data, based on the details of the response itself. 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.3#,`nng_aio_result()`>>. +obtained via `<<nng_aio_result.3#,nng_aio_result()>>`. That result will either be zero or an error code. == RETURN VALUES diff --git a/docs/man/nng_http_conn_write.3http.adoc b/docs/man/nng_http_conn_write.3http.adoc index d4f65cac..24daa0b7 100644 --- a/docs/man/nng_http_conn_write.3http.adoc +++ b/docs/man/nng_http_conn_write.3http.adoc @@ -29,19 +29,19 @@ The `nng_http_conn_write()` function starts an asynchronous write to the HTTP connection _conn_ from the scatter/gather vector located in the asynchronous I/O structure _aio_. -NOTE: The <<nng_aio_set_iov.3#,`nng_aio_set_iov()`>> function must have been +NOTE: The `<<nng_aio_set_iov.3#,nng_aio_set_iov()>>` function must have been called first, to set the scatter/gather vector for _aio_. 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.3#,`nng_aio_result()`>>. +result may be obtained via `<<nng_aio_result.3#,nng_aio_result()>>`. That result will either be zero or an error code. The I/O operation completes as soon as at least one byte has been written, or an error has occurred. Therefore, the number of bytes written may be less than requested. The actual number of bytes written can be determined with -<<nng_aio_count.3#,`nng_aio_count()`>>. +`<<nng_aio_count.3#,nng_aio_count()>>`. TIP: This function is intended to facilitate uses cases that involve changing the protocol from HTTP, such as WebSocket. diff --git a/docs/man/nng_http_conn_write_all.3http.adoc b/docs/man/nng_http_conn_write_all.3http.adoc index f517a9a5..d29af75e 100644 --- a/docs/man/nng_http_conn_write_all.3http.adoc +++ b/docs/man/nng_http_conn_write_all.3http.adoc @@ -29,37 +29,38 @@ The `nng_http_conn_write_all()` function starts an asynchronous write to the HTTP connection _conn_, into the scatter/gather vector located in the asynchronous I/O structure _aio_. -NOTE: The <<nng_aio_set_iov.3#,`nng_aio_set_iov()`>> function must have been +NOTE: The `<<nng_aio_set_iov.3#,nng_aio_set_iov()>>` function must have been called first, to set the scatter/gather vector for _aio_. 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.3#,`nng_aio_result()`>>. +final result may be obtained via `<<nng_aio_result.3#,nng_aio_result()>>`. That result will either be zero or an error code. The I/O operation completes only when the entire amount of data -requested has been written, or an error has occurred. If the operation -completes successfully, then the entire requested data has been written. +requested has been written, or an error has occurred. +If the operation completes successfully, then the entire requested data has +been written. It is still possible for a partial write to complete in the event of an error. The actual number of bytes written can be determined with -<<nng_aio_count.3#,`nng_aio_count()`>>. +`<<nng_aio_count.3#,nng_aio_count()>>`. TIP: The main purpose for this function is to faciliate writing HTTP body content. TIP: Usually an HTTP request or response will have been written immediately -prior to this with <<nng_http_conn_write_req.3http#,`http_conn_write_req()`>> or -<<nng_http_conn_write_res.3http#,`http_conn_write_res()`>>. +prior to this with `<<nng_http_conn_write_req.3http#,http_conn_write_req()>>` or +`<<nng_http_conn_write_res.3http#,http_conn_write_res()>>`. In that case the request or response should have also contained an `Content-Length` header, and possibly a `Content-Type` header. TIP: An easier solution to sending HTTP content data, is to include the conten with the request or reply using a function like -<<nng_http_req_copy_data.3http#,`nng_http_req_copy_data()`>>. +`<<nng_http_req_copy_data.3http#,nng_http_req_copy_data()>>`. In that case, the body data will be written automatically by the -<<nng_http_conn_write_req.3http#,`http_conn_write_req()`>> or -<<nng_http_conn_write_req.3http#,`http_conn_write_res()`>> function. +`<<nng_http_conn_write_req.3http#,http_conn_write_req()>>` or +`<<nng_http_conn_write_req.3http#,http_conn_write_res()>>` function. == RETURN VALUES diff --git a/docs/man/nng_http_conn_write_req.3http.adoc b/docs/man/nng_http_conn_write_req.3http.adoc index 2d614206..faffb3ca 100644 --- a/docs/man/nng_http_conn_write_req.3http.adoc +++ b/docs/man/nng_http_conn_write_req.3http.adoc @@ -31,12 +31,12 @@ the HTTP request _req_ to the connection _conn_. The entire request is sent, including headers, and if present, the request body data. (The request body can be set with -<<nng_http_req_set_data.3http#,`nng_http_req_set_data()`>> or -<<nng_http_req_copy_data.3http#,`nng_http_req_copy_data()`>>.) +`<<nng_http_req_set_data.3http#,nng_http_req_set_data()>>` or +`<<nng_http_req_copy_data.3http#,nng_http_req_copy_data()>>`.) 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.3#,`nng_aio_result()`>>. +may be obtained via `<<nng_aio_result.3#,nng_aio_result()>>`. That result willeither be zero or an error code. == RETURN VALUES diff --git a/docs/man/nng_http_conn_write_res.3http.adoc b/docs/man/nng_http_conn_write_res.3http.adoc index c8d0077b..219b771e 100644 --- a/docs/man/nng_http_conn_write_res.3http.adoc +++ b/docs/man/nng_http_conn_write_res.3http.adoc @@ -31,12 +31,12 @@ the HTTP response _res_ to the connection _conn_. The entire response is sent, including headers, and if present, the response body data. (The response body can be set with -<<nng_http_res_set_data.3http#,`nng_http_res_set_data()`>> or -<<nng_http_res_copy_data.3http#,`nng_http_res_copy_data()`>>.) +`<<nng_http_res_set_data.3http#,nng_http_res_set_data()>>` or +`<<nng_http_res_copy_data.3http#,nng_http_res_copy_data()>>`.) 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.3#,`nng_aio_result()`>>. +may be obtained via `<<nng_aio_result.3#,nng_aio_result()>>`. That result will either be zero or an error code. === Persistent Connections diff --git a/docs/man/nng_http_handler_alloc.3http.adoc b/docs/man/nng_http_handler_alloc.3http.adoc index 12c6043a..be6f2568 100644 --- a/docs/man/nng_http_handler_alloc.3http.adoc +++ b/docs/man/nng_http_handler_alloc.3http.adoc @@ -49,38 +49,38 @@ considered when determining whether the handler should be called. Additionally each handler has a method it is registered to handle (the default is "GET", see -<<nng_http_handler_set_method.3http#,`nng_http_handler_set_method()`>>), and +`<<nng_http_handler_set_method.3http#,nng_http_handler_set_method()>>`), and optionally a 'Host' header it can be matched against (see -<<nng_http_handler_set_host.3http#,`nng_http_handler_set_host()`>>). +`<<nng_http_handler_set_host.3http#,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.3http#,`nng_http_handler_set_tree()`>>). +(See `<<nng_http_handler_set_tree.3http#,nng_http_handler_set_tree()>>`). === Custom Handler The generic (first) form of this creates a handler that uses a user-supplied function to process HTTP requests. This function uses the asynchronous I/O framework. -The function takes a pointer to an <<nng_aio.5#,`nng_aio`>> structure. +The function takes a pointer to an `<<nng_aio.5#,nng_aio>>` structure. That structure will be passed with the following input values (retrieved with -<<nng_aio_get_input.3#,`nng_aio_get_input()`>>): +`<<nng_aio_get_input.3#,nng_aio_get_input()>>`): 0: `nng_http_req *` __request__:: The client's HTTP request. 1: `nng_http_handler *` __handler__:: Pointer to the handler object. 2: `nng_http_conn *` __conn__:: The underlying HTTP connection. The handler should create an `nng_http_res *` response (such as via -<<nng_http_res_alloc.3http#,`nng_http_res_alloc()`>> or -<<nng_http_res_alloc_error.3http#,`nng_http_res_alloc_error()`>>) and store that +`<<nng_http_res_alloc.3http#,nng_http_res_alloc()>>` or +`<<nng_http_res_alloc_error.3http#,nng_http_res_alloc_error()>>`) and store that in as the first output (index 0) with -<<nng_aio_set_output.3#,`nng_aio_set_output()`>>. +`<<nng_aio_set_output.3#,nng_aio_set_output()>>`. Alternatively, the handler may send the HTTP response (and any associated body data) itself using the connection. In that case the output at index 0 of the _aio_ should be NULL. -Finally, using the <<nng_aio_finish.3#,`nng_aio_finish()`>> function, the +Finally, using the `<<nng_aio_finish.3#,nng_aio_finish()>>` function, the _aio_ should be completed successfully. If any non-zero status is returned back to the caller instead, then a generic 500 response will be created and diff --git a/docs/man/nng_http_handler_get_data.3http.adoc b/docs/man/nng_http_handler_get_data.3http.adoc index b179fd34..f1a1a700 100644 --- a/docs/man/nng_http_handler_get_data.3http.adoc +++ b/docs/man/nng_http_handler_get_data.3http.adoc @@ -28,7 +28,7 @@ int nng_http_handler_get_data(nng_http_handler *handler, void *data, The `nng_http_handler_get_data()` function returns the data previously stored on _handler_ using the function -<<nng_http_handler_set_data.3http#,`nng_http_handler_set_data()`>>. +`<<nng_http_handler_set_data.3http#,nng_http_handler_set_data()>>`. == RETURN VALUES diff --git a/docs/man/nng_http_handler_set_data.3http.adoc b/docs/man/nng_http_handler_set_data.3http.adoc index 318919a9..a6be46fb 100644 --- a/docs/man/nng_http_handler_set_data.3http.adoc +++ b/docs/man/nng_http_handler_set_data.3http.adoc @@ -29,7 +29,7 @@ void *nng_http_handler_get_data(nng_http_handler *handler, void *data, The `nng_http_handler_set_data()` function is used to set an additional _data_ for the _handler_. The stored _data_ can be retrieved later in the handler function using -<<nng_http_handler_get_data.3http#,`nng_http_handler_get_data()`>>. +`<<nng_http_handler_get_data.3http#,nng_http_handler_get_data()>>`. Additionally, when the handler is deallocated, if _dtor_ is not `NULL`, then it will be called with _data_ as its argument. diff --git a/docs/man/nng_http_handler_set_method.3http.adoc b/docs/man/nng_http_handler_set_method.3http.adoc index d2ae88d0..1ddbb15a 100644 --- a/docs/man/nng_http_handler_set_method.3http.adoc +++ b/docs/man/nng_http_handler_set_method.3http.adoc @@ -40,7 +40,7 @@ NOTE: No validation of the _method_ is performed, but HTTP specifications insist that the actual method sent over the wire be capitalized. The handler may always examine the actual method used using the -<<nng_http_req_get_method.3http#,`nng_http_req_get_method()`>> function. +`<<nng_http_req_get_method.3http#,nng_http_req_get_method()>>` function. == RETURN VALUES diff --git a/docs/man/nng_http_hijack.3http.adoc b/docs/man/nng_http_hijack.3http.adoc index 61f6d471..d10bacfc 100644 --- a/docs/man/nng_http_hijack.3http.adoc +++ b/docs/man/nng_http_hijack.3http.adoc @@ -33,13 +33,13 @@ 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.3http#,`nng_http_handler_alloc()`>>.) +(See `<<nng_http_handler_alloc.3http#,nng_http_handler_alloc()>>`.) NOTE: 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_conn_write_res.3http#,`nng_http_conn_write_res()`>>.) +(See `<<nng_http_conn_write_res.3http#,nng_http_conn_write_res()>>`.) TIP: This function is intended to facilitate uses cases that involve changing the protocol from HTTP, such as WebSocket. diff --git a/docs/man/nng_http_req_add_header.3http.adoc b/docs/man/nng_http_req_add_header.3http.adoc index d47e112e..e6eb8844 100644 --- a/docs/man/nng_http_req_add_header.3http.adoc +++ b/docs/man/nng_http_req_add_header.3http.adoc @@ -37,7 +37,7 @@ If no such header already exists, then one is created with the value _val_. TIP: The HTTP specification requires that duplicate headers be treated identically to a single header with multiple comma-delimited values. -TIP: See <<nng_http_req_set_header.3http#,`nng_http_req_set_header()`>> if +TIP: See `<<nng_http_req_set_header.3http#,nng_http_req_set_header()>>` if replacement of an existing header rather than appending to it is desired. The value of _key_ is case insensitive, and should not include the final diff --git a/docs/man/nng_http_req_copy_data.3http.adoc b/docs/man/nng_http_req_copy_data.3http.adoc index 1e08cea0..5b52dcf2 100644 --- a/docs/man/nng_http_req_copy_data.3http.adoc +++ b/docs/man/nng_http_req_copy_data.3http.adoc @@ -30,7 +30,7 @@ and sets the HTTP body for the request _req_ to it. The copy will be deallocated automatically when _req_ is freed. The copied body data will be automatically sent with the request when it -is sent using <<nng_http_conn_write_req.3http#,`nni_http_conn_write_req()`>>. +is sent using `<<nng_http_conn_write_req.3http#,nni_http_conn_write_req()>>`. This also updates the relevant `Content-Length` header of _req_. @@ -38,7 +38,7 @@ NOTE: The current framework does not support sending data via chunked transfer-encoding. TIP: To avoid copying data, the -<<nng_http_req_set_data.3http#,`nng_http_req_set_data()`>> may be used instead. +`<<nng_http_req_set_data.3http#,nng_http_req_set_data()>>` may be used instead. TIP: It is a good idea to also set the `Content-Type` header. diff --git a/docs/man/nng_http_req_set_data.3http.adoc b/docs/man/nng_http_req_set_data.3http.adoc index e8fb7bd4..1161476a 100644 --- a/docs/man/nng_http_req_set_data.3http.adoc +++ b/docs/man/nng_http_req_set_data.3http.adoc @@ -28,7 +28,7 @@ int nng_http_req_set_data(nng_http_req *req, const void *body, size_t size); The `nng_http_req_set_data()` sets the HTTP body associated with the request _req_ to _body_, and the size of the body to _size_. This body data will be automatically sent with the request when it -is sent using <<nng_http_conn_write_req.3http#,`nni_http_conn_write_req()`>>. +is sent using `<<nng_http_conn_write_req.3http#,nni_http_conn_write_req()>>`. This also updates the relevant `Content-Length` header of _req_. @@ -40,7 +40,7 @@ until the _req_ is deallocated. TIP: To have a local copy allocated with _req_ that will be automatically deallocated when _req_ is freed, -see <<nng_http_req_copy_data.3http#,`nng_http_req_copy_data()`>>. +see `<<nng_http_req_copy_data.3http#,nng_http_req_copy_data()>>`. TIP: It is a good idea to also set the `Content-Type` header. diff --git a/docs/man/nng_http_req_set_header.3http.adoc b/docs/man/nng_http_req_set_header.3http.adoc index b70e1603..4102881a 100644 --- a/docs/man/nng_http_req_set_header.3http.adoc +++ b/docs/man/nng_http_req_set_header.3http.adoc @@ -31,7 +31,7 @@ _req_ and the _key_ to the _val_. The _key_ and _val_ are copied. Any previous header with the same _key_ is replaced. -TIP: See <<nng_http_req_add_header.3http#,`nng_http_req_add_header()`>> to +TIP: See `<<nng_http_req_add_header.3http#,nng_http_req_add_header()>>` to add additional headers with the same _key_ without replacing them. The value of _key_ is case insensitive, and should not include the final diff --git a/docs/man/nng_http_req_set_uri.3http.adoc b/docs/man/nng_http_req_set_uri.3http.adoc index 8a9c3c1e..25cd42a3 100644 --- a/docs/man/nng_http_req_set_uri.3http.adoc +++ b/docs/man/nng_http_req_set_uri.3http.adoc @@ -35,7 +35,7 @@ A local copy of the _uri_ is made in the request _req_. NOTE: No validation or canonicalization of the _uri_ is performed. -TIP: The <<nng_url_parse.3#,`nng_url_parse()`>> function can be used to +TIP: The `<<nng_url_parse.3#,nng_url_parse()>>` function can be used to perform validation and canonicalization. The `u_requri` member will contain a suitable value that can be used with this function. diff --git a/docs/man/nng_http_res_add_header.3http.adoc b/docs/man/nng_http_res_add_header.3http.adoc index 851331d6..cdc325ed 100644 --- a/docs/man/nng_http_res_add_header.3http.adoc +++ b/docs/man/nng_http_res_add_header.3http.adoc @@ -38,7 +38,7 @@ If no such header already exists, then one is created with the value _val_. TIP: The HTTP specification requires that duplicate headers be treated identically to a single header with multiple comma-delimited values. -TIP: See <<nng_http_res_set_header.3http#,`nng_http_res_set_header()`>> if +TIP: See `<<nng_http_res_set_header.3http#,nng_http_res_set_header()>>` if replacement of an existing header rather than appending to it is desired. The value of _key_ is case insensitive, and should not include the final diff --git a/docs/man/nng_http_res_alloc.3http.adoc b/docs/man/nng_http_res_alloc.3http.adoc index 10638ee7..e54f1ad7 100644 --- a/docs/man/nng_http_res_alloc.3http.adoc +++ b/docs/man/nng_http_res_alloc.3http.adoc @@ -32,7 +32,7 @@ with status code 200 (`NNG_HTTP_STATUS_OK`), and a reason phrase of "OK", and HTTP protocol version "HTTP/1.1". TIP: When an error response is needed, consider using -<<nng_http_res_alloc_error.3http#,`nng_http_res_alloc_error()`>> instead. +`<<nng_http_res_alloc_error.3http#,nng_http_res_alloc_error()>>` instead. == RETURN VALUES diff --git a/docs/man/nng_http_res_copy_data.3http.adoc b/docs/man/nng_http_res_copy_data.3http.adoc index 5542c441..3831d45b 100644 --- a/docs/man/nng_http_res_copy_data.3http.adoc +++ b/docs/man/nng_http_res_copy_data.3http.adoc @@ -30,7 +30,7 @@ and sets the HTTP body for the response _res_ to it. The copy will be deallocated automatically when _res_ is freed. The copied body data will be automatically sent with the response when it -is sent using <<nng_http_conn_write_res.3http#,`nni_http_conn_write_res()`>>. +is sent using `<<nng_http_conn_write_res.3http#,nni_http_conn_write_res()>>`. This also updates the relevant `Content-Length` header of _res_. @@ -38,7 +38,7 @@ NOTE: The current framework does not support sending data via chunked transfer-encoding. TIP: To avoid copying data, the -<<nng_http_res_set_data.3http#,`nng_http_res_set_data()`>> may be used instead. +`<<nng_http_res_set_data.3http#,nng_http_res_set_data()>>` may be used instead. TIP: It is a good idea to also set the `Content-Type` header. diff --git a/docs/man/nng_http_res_get_reason.3http.adoc b/docs/man/nng_http_res_get_reason.3http.adoc index 053b4cf1..7251f1cc 100644 --- a/docs/man/nng_http_res_get_reason.3http.adoc +++ b/docs/man/nng_http_res_get_reason.3http.adoc @@ -25,11 +25,11 @@ const char *nng_http_res_get_reason(nng_http_res *res); == DESCRIPTION -The `nng_http_res_get_reason()` returns a string representing the "reason -phrase" associated with the response _res_. +The `nng_http_res_get_reason()` returns a string representing the +"`reason phrase`" associated with the response _res_. This is a human-readable explanation of the status code that would be obtained from -<<nng_http_res_get_status.3http#,`nng_http_res_get_status()`>>. +`<<nng_http_res_get_status.3http#,nng_http_res_get_status()>>`. == RETURN VALUES diff --git a/docs/man/nng_http_res_get_status.3http.adoc b/docs/man/nng_http_res_get_status.3http.adoc index f519e659..ac780a24 100644 --- a/docs/man/nng_http_res_get_status.3http.adoc +++ b/docs/man/nng_http_res_get_status.3http.adoc @@ -97,8 +97,8 @@ enum { ---- TIP: When displaying status information to users (or logging such information), -consider also including the "reason phrase" obtained with -<<nng_http_res_get_reason.3http#,`nng_http_res_get_reason()`>>. +consider also including the "`reason phrase`" obtained with +`<<nng_http_res_get_reason.3http#,nng_http_res_get_reason()>>`. == RETURN VALUES diff --git a/docs/man/nng_http_res_set_data.3http.adoc b/docs/man/nng_http_res_set_data.3http.adoc index d7ed073b..ab522ca9 100644 --- a/docs/man/nng_http_res_set_data.3http.adoc +++ b/docs/man/nng_http_res_set_data.3http.adoc @@ -28,7 +28,7 @@ int nng_http_res_set_data(nng_http_res *res, const void *body, size_t size); The `nng_http_res_set_data()` sets the HTTP body associated with the response _res_ to _body_, and the size of the body to _size_. This body data will be automatically sent with the response when it -is sent using <<nng_http_conn_write_res.3http#,`nni_http_conn_write_res()`>>. +is sent using `<<nng_http_conn_write_res.3http#,nni_http_conn_write_res()>>`. This also updates the relevant `Content-Length` header of _res_. @@ -40,7 +40,7 @@ until the _res_ is deallocated. TIP: To have a local copy allocated with _res_ that will be automatically deallocated when _res_ is freed, -see <<nng_http_res_copy_data.3http#,`nng_http_res_copy_data()`>>. +see `<<nng_http_res_copy_data.3http#,nng_http_res_copy_data()>>`. TIP: It is a good idea to also set the `Content-Type` header. diff --git a/docs/man/nng_http_res_set_header.3http.adoc b/docs/man/nng_http_res_set_header.3http.adoc index 7e55b605..4d79739a 100644 --- a/docs/man/nng_http_res_set_header.3http.adoc +++ b/docs/man/nng_http_res_set_header.3http.adoc @@ -31,7 +31,7 @@ _res_ and the _key_ to the _val_. The _key_ and _val_ are copied. Any previous header with the same _key_ is replaced. -TIP: See <<nng_http_res_add_header.3http#,`nng_http_res_add_header()`>> to +TIP: See `<<nng_http_res_add_header.3http#,nng_http_res_add_header()>>` to add additional headers with the same _key_ without replacing them. The value of _key_ is case insensitive, and should not include the final diff --git a/docs/man/nng_http_res_set_reason.3http.adoc b/docs/man/nng_http_res_set_reason.3http.adoc index 096be393..fed03c2f 100644 --- a/docs/man/nng_http_res_set_reason.3http.adoc +++ b/docs/man/nng_http_res_set_reason.3http.adoc @@ -30,7 +30,7 @@ associated with the response _res_ to _reason_. If the value of _reason_ is `NULL` (the default), then a default reason phrase is supplied based upon the value of the status code (see -<<nng_http_res_set_status.3http#,`nng_http_res_set_status()`>>). +`<<nng_http_res_set_status.3http#,nng_http_res_set_status()>>`). TIP: The _reason_ is never parsed automatically, but it can be a hint for humans to help them understand the nature of any erroroneous result. diff --git a/docs/man/nng_http_res_set_status.3http.adoc b/docs/man/nng_http_res_set_status.3http.adoc index 24149735..b3b9700c 100644 --- a/docs/man/nng_http_res_set_status.3http.adoc +++ b/docs/man/nng_http_res_set_status.3http.adoc @@ -102,9 +102,9 @@ enum { Please see the relevant HTTP RFCs for the semantics and correct use of these status codes. -TIP: It is a good idea to also set the "reason phrase" with -<<nng_http_res_set_reason.3http#,`nng_http_set_reason()`>>. -This will help any humans who may have to diagnose any failure. +TIP: It is a good idea to also set the "`reason phrase`" with +`<<nng_http_res_set_reason.3http#,nng_http_set_reason()>>`. +This will help any humans who may have to diagnose a failure. == RETURN VALUES diff --git a/docs/man/nng_http_server_add_handler.3http.adoc b/docs/man/nng_http_server_add_handler.3http.adoc index 489489b1..31285ede 100644 --- a/docs/man/nng_http_server_add_handler.3http.adoc +++ b/docs/man/nng_http_server_add_handler.3http.adoc @@ -35,7 +35,7 @@ If a handler is added to a server, and the server is subsequently deallocated, the handler and any of its resources will also be deallocated. Handlers that are added to a server may be subsequently removed using the -<<nng_http_server_del_handler.3http#,`nng_http_server_del_handler()`>> function. +`<<nng_http_server_del_handler.3http#,nng_http_server_del_handler()>>` function. == RETURN VALUES diff --git a/docs/man/nng_http_server_hold.3http.adoc b/docs/man/nng_http_server_hold.3http.adoc index 70929c92..164a7487 100644 --- a/docs/man/nng_http_server_hold.3http.adoc +++ b/docs/man/nng_http_server_hold.3http.adoc @@ -37,7 +37,7 @@ with an initial reference count of one (1). The server instance is not started, and can have additional configuration applied to it before it is later started with -<<nng_http_server_start.3http#,`nng_http_server_start()`>>. +`<<nng_http_server_start.3http#,nng_http_server_start()>>`. NOTE: The URL matching logic in determining servers is unable to distinguish between different aliases for the same local IP address. diff --git a/docs/man/nng_http_server_release.3http.adoc b/docs/man/nng_http_server_release.3http.adoc index b17e44af..9f3ab798 100644 --- a/docs/man/nng_http_server_release.3http.adoc +++ b/docs/man/nng_http_server_release.3http.adoc @@ -27,7 +27,7 @@ void nng_http_server_release(nng_http_server *server); The `nng_http_server_release()` releases an instance of an HTTP _server_ that was previously held with -<<nng_http_server_hold.3http#,`nng_http_server_hold()`>>. +`<<nng_http_server_hold.3http#,nng_http_server_hold()>>`. This effectively drops the reference count on the server instance. When the reference count drops to zero, then the _server_ and all resources diff --git a/docs/man/nng_http_server_set_tls.3http.adoc b/docs/man/nng_http_server_set_tls.3http.adoc index 2b200653..25d26fa5 100644 --- a/docs/man/nng_http_server_set_tls.3http.adoc +++ b/docs/man/nng_http_server_set_tls.3http.adoc @@ -31,14 +31,14 @@ _cfg_. This change overwrites any previous TLS configuration. IMPORTANT: This also invalidates any previously obtained values from -<<nng_http_server_get_tls.3http#,`nng_http_server_get_tls()`>>. +`<<nng_http_server_get_tls.3http#,nng_http_server_get_tls()>>`. If the server is already running (i.e. it has been started with -<<nng_http_server_start.3http#,`nng_http_server_start()`>>) then this will +`<<nng_http_server_start.3http#,nng_http_server_start()>>`) then this will fail with `NNG_EBUSY`. TIP: Generally, the _cfg_ must have a configured private key, set with -<<nng_tls_config_own_cert.3tls#,`nng_tls_config_own_cert()`>> or similar. +`<<nng_tls_config_own_cert.3tls#,nng_tls_config_own_cert()>>` or similar. == RETURN VALUES diff --git a/docs/man/nng_inproc.7.adoc b/docs/man/nng_inproc.7.adoc index 363ad705..987f6b84 100644 --- a/docs/man/nng_inproc.7.adoc +++ b/docs/man/nng_inproc.7.adoc @@ -53,9 +53,9 @@ that URI. === Socket Address -When using an <<nng_sockaddr.5#,`nng_sockaddr`>> structure, +When using an `<<nng_sockaddr.5#,nng_sockaddr>>` structure, the actual structure is of type -<<nng_sockaddr_inproc.5#,`nng_sockaddr_inproc`>>. +`<<nng_sockaddr_inproc.5#,nng_sockaddr_inproc>>`. === Transport Options diff --git a/docs/man/nng_iov.5.adoc b/docs/man/nng_iov.5.adoc index 63d8b03b..55c2d19e 100644 --- a/docs/man/nng_iov.5.adoc +++ b/docs/man/nng_iov.5.adoc @@ -35,8 +35,8 @@ For example, it may be useful to send a message with header data from one part of memory, and a user payload from another. The operations that do this typically store an array of these in -an <<nng_aio.5#,`nng_aio`>> structure using the -<<nng_aio_set_iov.3#,`nng_aio_set_iov()`>> function. +an `<<nng_aio.5#,nng_aio>>` structure using the +`<<nng_aio_set_iov.3#,nng_aio_set_iov()>>` function. The following structure members are present: diff --git a/docs/man/nng_ipc.7.adoc b/docs/man/nng_ipc.7.adoc index 5a73ce25..5e711dc2 100644 --- a/docs/man/nng_ipc.7.adoc +++ b/docs/man/nng_ipc.7.adoc @@ -61,8 +61,8 @@ Therefore, always use an absolute path name if interoperability is required. === Socket Address -When using an <<nng_sockaddr.5#,`nng_sockaddr`>> structure, -the actual structure is of type <<nng_sockaddr_ipc.5#,`nng_sockaddr_ipc`>>. +When using an `<<nng_sockaddr.5#,nng_sockaddr>>` structure, +the actual structure is of type `<<nng_sockaddr_ipc.5#,nng_sockaddr_ipc>>`. === Transport Options diff --git a/docs/man/nng_listen.3.adoc b/docs/man/nng_listen.3.adoc index bc4222ab..6a9e8f6f 100644 --- a/docs/man/nng_listen.3.adoc +++ b/docs/man/nng_listen.3.adoc @@ -25,14 +25,14 @@ int nng_listen(nng_socket s, const char *url, nng_listener *lp, int flags); == DESCRIPTION The `nng_listen()` function creates a newly initialized -<<nng_listener.5#,`nng_listener`>> object, associated with socket _s_, +`<<nng_listener.5#,nng_listener>>` object, associated with socket _s_, and configured to listen at the address specified by _url_, and starts it. If the value of _lp_ is not `NULL`, then the newly created listener is stored at the address indicated by _lp_. Listeners are used to accept connections initiated by remote dialers. An incoming connection generally results in and -<<nng_pipe.5#,`nng_pipe`>> object being created and attached to the socket _s_. +`<<nng_pipe.5#,nng_pipe>>` object being created and attached to the socket _s_. Unlike dialers, listeners generally can create many pipes, which may be open concurrently. @@ -56,8 +56,8 @@ it also generally makes diagnosing failures somewhat more difficult. Because the listener is started immediately, it is generally not possible to apply extra configuration; if that is needed applications should consider -using <<nng_listener_create.3#,`nng_listener_create()`>> and -<<nng_listener_start.3#,`nng_listener_start()`>> instead. +using `<<nng_listener_create.3#,nng_listener_create()>>` and +`<<nng_listener_start.3#,nng_listener_start()>>` instead. The created listener will continue to accept new connections, associating their pipes with the socket, until either it or the socket _s_ is closed. diff --git a/docs/man/nng_listener.5.adoc b/docs/man/nng_listener.5.adoc index e7187a61..6da63f36 100644 --- a/docs/man/nng_listener.5.adoc +++ b/docs/man/nng_listener.5.adoc @@ -26,21 +26,21 @@ typedef struct nng_listener_s nng_listener; (((listener))) An `nng_listener` is a handle to a "`listener`" object, which is responsible for -creating <<nng_pipe.5#,`nng_pipe`>> objects by accepting incoming connections. -A given listener object may create many pipes at the same time, much like an HTTP -server can have many connections to multiple clients simultaneously. +creating `<<nng_pipe.5#,nng_pipe>>` objects by accepting incoming connections. +A given listener object may create many pipes at the same time, much like an +HTTP server can have many connections to multiple clients simultaneously. Listener objects are created by the -<<nng_listener_create.3#,`nng_listener_create()`>> -or <<nng_listen.3#,`nng_listen()`>> functions, and are always "`owned`" -by a single <<nng_socket.5#,`nng_socket`>>. +`<<nng_listener_create.3#,nng_listener_create()>>` +or `<<nng_listen.3#,nng_listen()>>` functions, and are always "`owned`" +by a single `<<nng_socket.5#,nng_socket>>`. IMPORTANT: The `nng_listener` structure is always passed by value (both for input parameters and return values), and should be treated opaquely. Passing structures this way ensures gives the compiler a chance to perform accurate type checks in functions passing values of this type. -TIP: A given <<nng_socket.5#,`nng_socket`>> may have multiple listener +TIP: A given `<<nng_socket.5#,nng_socket>>` may have multiple listener objects, multiple <<nng_dialer.5#,dialer>> objects, or even some of both. @@ -52,7 +52,7 @@ This orthogonality can lead to innovative solutions to otherwise challenging communications problems. Listener objects may be destroyed by the -<<nng_listener_close.3#,`nng_listener_close()`>> function. +`<<nng_listener_close.3#,nng_listener_close()>>` function. They are also closed when their "`owning`" socket is closed. [[NNG_LISTENER_INITIALIZER]] diff --git a/docs/man/nng_listener_create.3.adoc b/docs/man/nng_listener_create.3.adoc index cd7f80da..7ea926c8 100644 --- a/docs/man/nng_listener_create.3.adoc +++ b/docs/man/nng_listener_create.3.adoc @@ -25,7 +25,7 @@ int nng_listener_create(nng_listener *listenerp, nng_socket s, const char *url); == DESCRIPTION The `nng_listener_create()` function creates a newly initialized -<<nng_listener.5#,`nng_listener`>> object, associated with socket _s_, +`<<nng_listener.5#,nng_listener>>` object, associated with socket _s_, and configured to listen at the address specified by _url_, and stores a pointer to at the location referenced by _listenerp_. @@ -43,14 +43,14 @@ but might also have associated listeners. It may even have some of each at the same time! The listener is not started, but may be further configured with -the <<nng_listener_setopt.3#,`nng_listener_setopt()`>> family of +the `<<nng_listener_setopt.3#,nng_listener_setopt()>>` family of functions. Once it is fully configured, the listener may be started using the -<<nng_listener_start.3#,`nng_listener_start()`>> function. +`<<nng_listener_start.3#,nng_listener_start()>>` function. TIP: If no specific configuration is required, consider using the -simpler <<nng_listen.3#,`nng_listen()`>> function instead. +simpler `<<nng_listen.3#,nng_listen()>>` function instead. == RETURN VALUES diff --git a/docs/man/nng_listener_getopt.3.adoc b/docs/man/nng_listener_getopt.3.adoc index 3fe79868..14cc6a06 100644 --- a/docs/man/nng_listener_getopt.3.adoc +++ b/docs/man/nng_listener_getopt.3.adoc @@ -101,14 +101,14 @@ This function is used to retrieve a size into the pointer _zp_, typically for buffer sizes, message maximum sizes, and similar options. ==== `nng_listener_getopt_sockaddr()` -This function is used to retrieve an <<nng_sockaddr.5#,`nng_sockaddr`>> +This function is used to retrieve an `<<nng_sockaddr.5#,nng_sockaddr>>` into the value referenced by _sap_. ==== `nng_listener_getopt_string()` This function is used to retrieve a string into _strp_. -This string is created from the source using <<nng_strdup.3#,`nng_strdup()`>> +This string is created from the source using `<<nng_strdup.3#,nng_strdup()>>` and consequently must be freed by the caller using -<<nng_strfree.3#,`nng_strfree()`>> when it is no longer needed. +`<<nng_strfree.3#,nng_strfree()>>` when it is no longer needed. ==== `nng_listener_getopt_uint64()` This function is used to retrieve a 64-bit unsigned value into the value diff --git a/docs/man/nng_listener_id.3.adoc b/docs/man/nng_listener_id.3.adoc index 44404e14..6c3537b0 100644 --- a/docs/man/nng_listener_id.3.adoc +++ b/docs/man/nng_listener_id.3.adoc @@ -29,11 +29,11 @@ listener _l_, if it is valid. Otherwise it returns `-1`. NOTE: A listener is considered valid if it was ever created with the -<<nng_listener_create.3#,`nng_listener_create`>> or -<<nng_listen.3#,`nng_listen`>> functions. +`<<nng_listener_create.3#,nng_listener_create>>` or +`<<nng_listen.3#,nng_listen>>` functions. listeners that are allocated on the stack or statically should be initialized with the macro -<<nng_ctx.5#NNG_LISTENER_INITIALIZER,`NNG_LISTENER_INITIALIZER`>> to ensure that +`<<nng_ctx.5#NNG_LISTENER_INITIALIZER,NNG_LISTENER_INITIALIZER>>` to ensure that they cannot be confused with a valid listener before they are created properly. == RETURN VALUES diff --git a/docs/man/nng_listener_setopt.3.adoc b/docs/man/nng_listener_setopt.3.adoc index d24a4f06..99b74124 100644 --- a/docs/man/nng_listener_setopt.3.adoc +++ b/docs/man/nng_listener_setopt.3.adoc @@ -73,14 +73,14 @@ The _ival_ is passed to the option. ==== `nng_listener_setopt_ms()` This function is used to configure time durations (such as timeouts) using -type <<nng_duration.5#,`nng_duration`>>. +type `<<nng_duration.5#,nng_duration>>`. The duration _dur_ is an integer number of milliseconds. ==== `nng_listener_setopt_ptr()` This function is used to pass a pointer, _ptr_, to structured data. The data referenced by _ptr_ is generally managed by other functions. For example, TLS configuration objects created with -(<<nng_tls_config_alloc.3tls#,`nng_tls_config_alloc()`>>) +(`<<nng_tls_config_alloc.3tls#,nng_tls_config_alloc()>>`) can be passed this way. Note that this form is somewhat special in that the object is generally not copied, but instead the *pointer* to the object is copied. diff --git a/docs/man/nng_listener_start.3.adoc b/docs/man/nng_listener_start.3.adoc index 5938e784..4b3f9083 100644 --- a/docs/man/nng_listener_start.3.adoc +++ b/docs/man/nng_listener_start.3.adoc @@ -29,7 +29,7 @@ The `nng_listener_start()` function starts the listener _l_. This causes the listener to bind to the address it was created with, and to start accepting connections from remote dialers. -Each new connection results in an <<nng_pipe.5#,`nng_pipe`>> object, +Each new connection results in an `<<nng_pipe.5#,nng_pipe>>` object, which will be attached to the listener's socket. Normally, the act of "`binding`" to it's address is done diff --git a/docs/man/nng_msg.5.adoc b/docs/man/nng_msg.5.adoc index 3b26bcf0..46aa11da 100644 --- a/docs/man/nng_msg.5.adoc +++ b/docs/man/nng_msg.5.adoc @@ -34,8 +34,8 @@ TIP: Using the message-oriented functions in the <<nng.7#,_nng_>> API is a good way to reduce the likelihood of data copies and improve application performance. -Messages are allocated using the <<nng_msg_alloc.3#,`nng_msg_alloc()`>> -function, and are deallocated using the <<nng_msg_free.3#,`nng_msg_free`>> +Messages are allocated using the `<<nng_msg_alloc.3#,nng_msg_alloc()>>` +function, and are deallocated using the `<<nng_msg_free.3#,nng_msg_free()>>` function. In addition there are other functions used to access message contents, diff --git a/docs/man/nng_msg_body.3.adoc b/docs/man/nng_msg_body.3.adoc index 12701b0f..f2de29a2 100644 --- a/docs/man/nng_msg_body.3.adoc +++ b/docs/man/nng_msg_body.3.adoc @@ -30,12 +30,12 @@ content of the message _msg_. NOTE: The value returned by this is invalidated by a call to any of the functions that modify the message itself. Such functions are -<<nng_msg_free.3#,`nng_msg_free()`>>, -<<nng_msg_realloc.3#,`nng_msg_realloc()`>>, -any of the <<nng_msg_trim.3#,`nng_msg_trim()`>>, -<<nng_msg_chop.3#,`nng_msg_chop()`>>, -<<nng_msg_append.3#,`nng_msg_append()`>>, -or <<nng_msg_insert.3#,`nng_msg_insert()`>> variants. +`<<nng_msg_free.3#,nng_msg_free()>>`, +`<<nng_msg_realloc.3#,nng_msg_realloc()>>`, +any of the `<<nng_msg_trim.3#,nng_msg_trim()>>`, +`<<nng_msg_chop.3#,nng_msg_chop()>>`, +`<<nng_msg_append.3#,nng_msg_append()>>`, +or `<<nng_msg_insert.3#,nng_msg_insert()>>` variants. == RETURN VALUES diff --git a/docs/man/nng_msg_get_pipe.3.adoc b/docs/man/nng_msg_get_pipe.3.adoc index 4a38c9ff..e12a956c 100644 --- a/docs/man/nng_msg_get_pipe.3.adoc +++ b/docs/man/nng_msg_get_pipe.3.adoc @@ -24,7 +24,7 @@ nng_pipe nng_msg_get_pipe(nng_msg *msg); == DESCRIPTION -The `nng_msg_get_pipe()` returns the <<nng_pipe.5#,`nng_pipe`>> object +The `nng_msg_get_pipe()` returns the `<<nng_pipe.5#,nng_pipe>>` object associated with message _msg_. On receive, this is the pipe from which a message was received. On transmit, this would be the pipe that the message should be delivered @@ -36,7 +36,7 @@ The most usual use case for this is to obtain information about the peer from which the message was received. This can be used to provide different behaviors for different peers, such as a higher level of authentication for peers located on an untrusted network. -The <<nng_pipe_getopt.3#,`nng_pipe_getopt()`>> function +The `<<nng_pipe_getopt.3#,nng_pipe_getopt()>>` function is useful in this situation. diff --git a/docs/man/nng_msg_header.3.adoc b/docs/man/nng_msg_header.3.adoc index 053ea849..b4679b0c 100644 --- a/docs/man/nng_msg_header.3.adoc +++ b/docs/man/nng_msg_header.3.adoc @@ -30,7 +30,7 @@ content of the message _msg_. NOTE: The message header contains protocol-specific header content. Most applications should not need to access this content, but it is available for raw mode sockets (set with the -<<nng_options.5#NNG_OPT_RAW,`NNG_OPT_RAW`>> option.) +`<<nng_options.5#NNG_OPT_RAW,NNG_OPT_RAW>>` option.) NOTE: The value returned by this is invalidated by a call to any of the functions that modify the message or the header content. diff --git a/docs/man/nng_msg_realloc.3.adoc b/docs/man/nng_msg_realloc.3.adoc index 59c2a2da..b1308fff 100644 --- a/docs/man/nng_msg_realloc.3.adoc +++ b/docs/man/nng_msg_realloc.3.adoc @@ -31,11 +31,11 @@ and will reuse the existing memory when possible. TIP: One way to further reduce message allocations is to allocate a message larger than needed, then use this function or -<<nng_msg_chop.3#,`nng_msg_chop()`>> to reduce the message size +`<<nng_msg_chop.3#,nng_msg_chop()>>` to reduce the message size to that actually needed. The extra space left over will still be present in the message, so that when the message size -needs to grow due to this function or <<nng_msg_append.3#,`nng_msg_append()`>> +needs to grow due to this function or `<<nng_msg_append.3#,nng_msg_append()>>` no actual memory allocations need to take place. NOTE: Pointers to message body and header content obtained prior to this diff --git a/docs/man/nng_mtx_lock.3supp.adoc b/docs/man/nng_mtx_lock.3supp.adoc index 54aacd37..8ea4bdd6 100644 --- a/docs/man/nng_mtx_lock.3supp.adoc +++ b/docs/man/nng_mtx_lock.3supp.adoc @@ -27,7 +27,7 @@ void nng_mtx_lock(nng_mtx *mtx); The `nng_mtx_lock()` acquires exclusive ownership of the mutex _mtx_. If the lock is already owned, this function will wait until the current -owner releases it with <<nng_mtx_unlock.3supp#,`nng_mtx_unlock()`>>. +owner releases it with `<<nng_mtx_unlock.3supp#,nng_mtx_unlock()>>`. If multiple threads are waiting for the lock, the order of acquisition is not specified. @@ -40,8 +40,8 @@ It is a programming error for the owner of a mutex to attempt to reacquire it. **** -_NNG_ offers neither a "`trylock`" operation, nor recursive mutexes. -This is by design, as _NNG_ itself does not use such things, +_nng_ offers neither a "`trylock`" operation, nor recursive mutexes. +This is by design, as _nng_ itself does not use such things, and most often the need for them is the result of poor design. If such capabilities are needed, they may be synthesized fairly easily from mutexes and condition variables. diff --git a/docs/man/nng_mtx_unlock.3supp.adoc b/docs/man/nng_mtx_unlock.3supp.adoc index 281a3f1e..996908d3 100644 --- a/docs/man/nng_mtx_unlock.3supp.adoc +++ b/docs/man/nng_mtx_unlock.3supp.adoc @@ -26,7 +26,7 @@ void nng_mtx_unlock(nng_mtx *mtx); == DESCRIPTION The `nng_mtx_unlock()` reqlinquishes ownership of the mutex _mtx_ that -was previously acquired via <<nng_mtx_lock.3supp#,`nng_mtx_lock()`>>. +was previously acquired via `<<nng_mtx_lock.3supp#,nng_mtx_lock()>>`. IMPORTANT: A mutex can _only_ be unlocked by the thread that locked it. Attempting to unlock a mutex that is not owned by the caller will result diff --git a/docs/man/nng_options.5.adoc b/docs/man/nng_options.5.adoc index 9db3d660..4850730d 100644 --- a/docs/man/nng_options.5.adoc +++ b/docs/man/nng_options.5.adoc @@ -47,22 +47,22 @@ nng_options - socket, dialer, listener, and pipe options This page documents the various standard options that can be set or retrieved on objects in the _nng_ library. -Sockets (<<nng_socket.5#,`nng_socket`>> objects) use the functions -<<nng_getopt.3#,`nng_getopt()`>> -and <<nng_setopt.3#,`nng_setopt()`>> to set and retrieve option values. +Sockets (`<<nng_socket.5#,nng_socket>>` objects) use the functions +`<<nng_getopt.3#,nng_getopt()>>` +and `<<nng_setopt.3#,nng_setopt()>>` to set and retrieve option values. -Dialers (<<nng_dialer.5#,`nng_dialer`>> objects) use the functions -<<nng_dialer_getopt.3#,`nng_dialer_getopt()`>> and -<<nng_dialer_setopt.3#,`nng_dialer_setopt()`>> to set and retrieve option +Dialers (`<<nng_dialer.5#,nng_dialer>>` objects) use the functions +`<<nng_dialer_getopt.3#,nng_dialer_getopt()>>` and +`<<nng_dialer_setopt.3#,nng_dialer_setopt()>>` to set and retrieve option values. -Listeners (<<nng_listener.5#,`nng_listener`>> objects) use the functions -<<nng_listener_getopt.3#,`nng_listener_getopt()`>> -and <<nng_listener_setopt.3#,`nng_listener_setopt()`>> to set and +Listeners (`<<nng_listener.5#,nng_listener>>` objects) use the functions +`<<nng_listener_getopt.3#,nng_listener_getopt()>>` +and `<<nng_listener_setopt.3#,nng_listener_setopt()>>` to set and retrieve option values. -Pipes (<<nng_pipe.5#,`nng_pipe`>> objects) can only retrieve option values using -the <<nng_pipe_getopt.3#,`nng_pipe_getopt()`>> function. +Pipes (`<<nng_pipe.5#,nng_pipe>>` objects) can only retrieve option values using +the `<<nng_pipe_getopt.3#,nng_pipe_getopt()>>` function. In addition to the options listed here, transports and protocols will generally have some of their own options, which will be documented with the transport @@ -159,14 +159,14 @@ be readable. IMPORTANT: Appplications should never attempt to read or write to the returned file descriptor. Furthermore, applications should not attempt to use the actual socket (of -type <<nng_socket.5#,`nng_socket`>>) with polling functions, +type `<<nng_socket.5#,nng_socket>>`) with polling functions, since it is merely an internal identifier and will not necessarily referency any operting system object or handle. TIP: While this option may help applications integrate into existing polling loops, it is more efficient, and often easier, to use the asynchronous I/O -objects instead. See <<nng_aio_alloc.3#,`nng_aio_alloc()`>>. +objects instead. See `<<nng_aio_alloc.3#,nng_aio_alloc()>>`. [[NNG_OPT_RECVMAXSZ]] ((`NNG_OPT_RECVMAXSZ`)):: @@ -235,14 +235,14 @@ the descriptor will *not* be readable. IMPORTANT: Appplications should never attempt to read or write to the returned file descriptor. Furthermore, applications should not attempt to use the actual socket (of -type <<nng_socket.5#,`nng_socket`>>) with polling functions, +type `<<nng_socket.5#,nng_socket>>`) with polling functions, since it is merely an internal identifier and will not necessarily referency any operting system object or handle. TIP: While this option may help applications integrate into existing polling loops, it is more efficient, and often easier, to use the asynchronous I/O -objects instead. See <<nng_aio_alloc.3#,`nng_aio_alloc`()>>. +objects instead. See `<<nng_aio_alloc.3#,nng_aio_alloc()>>`. [[NNG_OPT_SENDTIMEO]] ((`NNG_OPT_SENDTIMEO`)):: @@ -268,7 +268,7 @@ The string must fit within 64-bytes, including the terminating (`int`) (((time-to-live))) This is the maximum number of "`hops`" a message may traverse (see -<<nng_device.3#,`nng_device()`>>). +`<<nng_device.3#,nng_device()>>`). The intention here is to prevent ((forwarding loops)) in device chains. When this is supported, it can have a value between 1 and 255, inclusive. @@ -317,7 +317,7 @@ the socket. [[NNG_OPT_TCP_NODELAY]] ((`NNG_OPT_TCP_NODELAY`)):: -(`bool``) +(`bool`) This option is used to disable (or enable) the use of Nagle's algorithm for TCP connections. When `true` (the default), messages are sent immediately by the underlying @@ -332,7 +332,7 @@ See the transport documentation for each transport for details. [[NNG_OPT_TCP_KEEPALIVE]] ((`NNG_OPT_TCP_KEEPALIVE`)):: -(`bool``) +(`bool`) This option is used to enable the sending of keep-alive messages on the underlying TCP stream. This option is `false` by default. diff --git a/docs/man/nng_pair.7.adoc b/docs/man/nng_pair.7.adoc index f03a4a5f..3d070d00 100644 --- a/docs/man/nng_pair.7.adoc +++ b/docs/man/nng_pair.7.adoc @@ -39,15 +39,15 @@ some additional sophistication in the application. === Socket Operations -The <<nng_pair_open.3#,`nng_pair_open()`>> functions create _pair_ socket. +The `<<nng_pair_open.3#,nng_pair_open()>>` functions create _pair_ socket. Normally, this pattern will block when attempting to send a message if no peer is able to receive the message. NOTE: Even though this mode may appear to be "reliable", because back-pressure prevents discarding messages most of the time, there are topologies involving -_devices_ (see <<nng_device.3#,`nng_device()`>>) or raw mode sockets -(see <<nng_options.5#NNG_OPT_RAW,`NNG_OPT_RAW`>>) where +_devices_ (see `<<nng_device.3#,nng_device()>>`) or raw mode sockets +(see `<<nng_options.5#NNG_OPT_RAW,NNG_OPT_RAW>>`) where messages may be discarded. Applications that require reliable delivery semantics should consider using <<nng_req.7#,_req_>> sockets, or @@ -68,7 +68,7 @@ including the legacy https://github.com/nanomsg/nanomsg[nanomsg] library or https://github.com/go-mangos/mangos[mangos]. Version 1 of the protocol offers improved protection against loops when -used with <<nng_device.3#,`nng_device()`>>. +used with `<<nng_device.3#,nng_device()>>`. It also offers _polyamorous_ mode for forming multiple partnerships on a single socket. @@ -84,11 +84,11 @@ In ((_polyamorous_ mode)), which is only available with version 1, a socket can support many one-to-one connections. In this mode, the application must choose the remote peer to receive an ougoing message by setting the -<<nng_pipe.5#,`nng_pipe`>> to use for the outgoing message with -the <<nng_msg_set_pipe.3#,`nng_msg_set_pipe()`>> function. +`<<nng_pipe.5#,nng_pipe>>` to use for the outgoing message with +the `<<nng_msg_set_pipe.3#,nng_msg_set_pipe()>>` function. Most often the value of the outgoing pipe will be obtained from an incoming -message using the <<nng_msg_get_pipe.3#,`nng_msg_get_pipe()`>> function, +message using the `<<nng_msg_get_pipe.3#,nng_msg_get_pipe()>>` function, such as when replying to an incoming message. In order to prevent head-of-line blocking, if the peer on the given pipe @@ -106,7 +106,7 @@ The following protocol-specific options are available. The value is read-write, and takes an integer boolean value. The default false value (0) indicates that legacy monogamous mode should be used. -<<nng_options.5#NNG_OPT_MAXTTL,`NNG_OPT_MAXTTL`>>:: +`<<nng_options.5#NNG_OPT_MAXTTL,NNG_OPT_MAXTTL>>`:: (`int`, version 1 only). Maximum time-to-live. @@ -117,7 +117,7 @@ Version 0 of the pair protocol has no protocol-specific headers. Version 1 of the pair protocol uses a single 32-bit unsigned value. The low-order (big-endian) byte of this value contains a "hop" count, and is used in conjuction with the -<<nng_options.5#NNG_OPT_MAXTTL,`NNG_OPT_MAXTTL`>> option to guard against +`<<nng_options.5#NNG_OPT_MAXTTL,NNG_OPT_MAXTTL>>` option to guard against device forwarding loops. This value is initialized to 1, and incremented each time the message is received by a new node. diff --git a/docs/man/nng_pipe.5.adoc b/docs/man/nng_pipe.5.adoc index a7423884..a777c0d0 100644 --- a/docs/man/nng_pipe.5.adoc +++ b/docs/man/nng_pipe.5.adoc @@ -42,12 +42,12 @@ 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 (<<nng_dialer.5#,`nng_dialer`>> objects) -and listeners (<<nng_listener.5#,`nng_listener`>> objects), which can be +Pipe objects are created by dialers (`<<nng_dialer.5#,nng_dialer>>` objects) +and listeners (`<<nng_listener.5#,nng_listener>>` objects), which can be thought of as "`owning`" the pipe. Pipe objects may be destroyed by the -<<nng_pipe_close.3#,`nng_pipe_close()`>> function. +`<<nng_pipe_close.3#,nng_pipe_close()>>` function. They are also closed when their "`owning`" dialer or listener is closed, or when the remote peer closes the underlying connection. diff --git a/docs/man/nng_pipe_close.3.adoc b/docs/man/nng_pipe_close.3.adoc index 2128caec..5e8cb851 100644 --- a/docs/man/nng_pipe_close.3.adoc +++ b/docs/man/nng_pipe_close.3.adoc @@ -27,7 +27,7 @@ int nng_pipe_close(nng_pipe p); 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 and the setting of the -<<nng_options.5#NNG_OPT_LINGER,`NNG_OPT_LINGER`>> option. +`<<nng_options.5#NNG_OPT_LINGER,NNG_OPT_LINGER>>` option. Further attempts to use the pipe after this call returns will result in `NNG_ECLOSED`. diff --git a/docs/man/nng_pipe_getopt.3.adoc b/docs/man/nng_pipe_getopt.3.adoc index 66216a73..64cad9a3 100644 --- a/docs/man/nng_pipe_getopt.3.adoc +++ b/docs/man/nng_pipe_getopt.3.adoc @@ -51,8 +51,8 @@ documented with the transports andp protocols themselves. NOTE: All "`options`" on a pipe are read-only values, and intended to facilitate understanding the identity of an associated peer. Modification of options must be done on the listener or dialer using either -<<nng_listener_setopt.3#,`nng_listener_setopt()`>> or -<<nng_dialer_getopt.3#,`nng_dialer_getopt()`>> +`<<nng_listener_setopt.3#,nng_listener_setopt()>>` or +`<<nng_dialer_getopt.3#,nng_dialer_setopt()>>`. Any option that is set on a dialer or listener will normally be retrievable from pipes created by that dialer or listener. @@ -98,7 +98,7 @@ The value will be stored at _ivalp_. For booleans the value will be eiher 0 ==== `nng_pipe_getopt_ms()` This function is used to retrieve time durations -(<<nng_duration.5#,`nng_duration`>>) in milliseconds, which are stored in +(`<<nng_duration.5#,nng_duration>>`) in milliseconds, which are stored in _durp_. ==== `nng_pipe_getopt_ptr()` @@ -114,15 +114,15 @@ typically for buffer sizes, message maximum sizes, and similar options. ==== `nng_pipe_getopt_sockaddr()` -This function is used to retrieve an <<nng_sockaddr.5#,`nng_sockaddr`>> +This function is used to retrieve an `<<nng_sockaddr.5#,nng_sockaddr>>` into _sap_. ==== `nng_pipe_getopt_string()` This function is used to retrieve a string into _strp_. -This string is created from the source using <<nng_strdup.3#,`nng_strdup()`>> +This string is created from the source using `<<nng_strdup.3#,nng_strdup()>>` and consequently must be freed by the caller using -<<nng_strfree.3#,`nng_strfree()`>> when it is no longer needed. +`<<nng_strfree.3#,nng_strfree()>>` when it is no longer needed. ==== `nng_pipe_getopt_uint64()` diff --git a/docs/man/nng_pipe_id.3.adoc b/docs/man/nng_pipe_id.3.adoc index b327dac2..19eed4f6 100644 --- a/docs/man/nng_pipe_id.3.adoc +++ b/docs/man/nng_pipe_id.3.adoc @@ -28,12 +28,11 @@ The `nng_pipe_id()` function returns a positive identifier for the pipe _p_, if it is valid. Otherwise it returns `-1`. -NOTE: A pipe is considered valid if it was ever opened with -<<nng_pipe_open.3#,`nng_pipe_open`>> function. +NOTE: 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.5#NNG_PIPE_INITIALIZER,`NNG_PIPE_INITIALIZER`>> to ensure that -they cannot be confused with a valid pipe before they are opened. +`<<nng_pipe.5#NNG_PIPE_INITIALIZER,NNG_PIPE_INITIALIZER>>` to ensure that +they cannot be confused with a valid pipe. == RETURN VALUES diff --git a/docs/man/nng_pub.7.adoc b/docs/man/nng_pub.7.adoc index e45201b7..6aec8c9e 100644 --- a/docs/man/nng_pub.7.adoc +++ b/docs/man/nng_pub.7.adoc @@ -44,7 +44,7 @@ Applications should construct their messages accordingly. === Socket Operations -The <<nng_pub_open.3#,`nng_pub0_open()`>> functions create a publisher socket. +The `<<nng_pub_open.3#,nng_pub0_open()>>` functions create a publisher socket. This socket may be used to send messages, but is unable to receive them. Attempts to receive messages will result in `NNG_ENOTSUP`. diff --git a/docs/man/nng_pull.7.adoc b/docs/man/nng_pull.7.adoc index c57515c5..59607e7e 100644 --- a/docs/man/nng_pull.7.adoc +++ b/docs/man/nng_pull.7.adoc @@ -35,7 +35,7 @@ This property makes this pattern useful in ((load-balancing)) scenarios. === Socket Operations -The <<nng_pull_open.3#,`nng_pull0_open()`>> functions create a puller socket. +The `<<nng_pull_open.3#,nng_pull0_open()>>` functions create a puller socket. This socket may be used to receive messages, but is unable to send them. Attempts to send messages will result in `NNG_ENOTSUP`. diff --git a/docs/man/nng_push.7.adoc b/docs/man/nng_push.7.adoc index e2ab50ab..800c0bd6 100644 --- a/docs/man/nng_push.7.adoc +++ b/docs/man/nng_push.7.adoc @@ -34,7 +34,7 @@ This property makes this pattern useful in ((load-balancing)) scenarios. === Socket Operations -The <<nng_push_open.3#,`nng_push0_open()`>> call creates a pusher socket. +The `<<nng_push_open.3#,nng_push0_open()>>` call creates a pusher socket. This socket may be used to send messages, but is unable to receive them. Attempts to receive messages will result in `NNG_ENOTSUP`. diff --git a/docs/man/nng_recv.3.adoc b/docs/man/nng_recv.3.adoc index 47ce4cbe..5ab180f0 100644 --- a/docs/man/nng_recv.3.adoc +++ b/docs/man/nng_recv.3.adoc @@ -38,13 +38,13 @@ In this case the caller must set the value of _data_ to the location of another pointer (of type `void *`), and the _sizep_ pointer must be set to a location to receive the size of the message body. The function will then allocate a message buffer -(as if by <<nng_alloc.3#,`nng_alloc()`>>), fill it with +(as if by `<<nng_alloc.3#,nng_alloc()>>`), fill it with the message body, and store it at the address referenced by _data_, and update the size referenced by _sizep_. When this flag is present, the caller assumes responsibility for disposing of the received buffer either by the function -<<nng_free.3#,`nng_free()`>> or reusing the message for sending (with the same -size) in a call to <<nng_send.3#,`nng_send()`>>. +`<<nng_free.3#,nng_free()>>` or reusing the message for sending (with the same +size) in a call to `<<nng_send.3#,nng_send()>>`. NOTE: The semantics of what receiving a message means vary from protocol to protocol, so examination of the protocol documentation is encouraged. diff --git a/docs/man/nng_recv_aio.3.adoc b/docs/man/nng_recv_aio.3.adoc index 7e30996c..774577bf 100644 --- a/docs/man/nng_recv_aio.3.adoc +++ b/docs/man/nng_recv_aio.3.adoc @@ -29,9 +29,9 @@ The `nng_recv_aio()` receives a <<nng_msg.5#,message>> using the When a message is successfully received by the socket, it is stored in the _aio_ by an internal call equivalent to -<<nng_aio_set_msg.3#,`nng_aio_set_msg()`>>, then the completion +`<<nng_aio_set_msg.3#,nng_aio_set_msg()>>`, then the completion callback on the _aio_ is executed. -In this case, <<nng_aio_result.3#,`nng_aio_result()`>> will +In this case, `<<nng_aio_result.3#,nng_aio_result()>>` will return zero. The callback function is responsible for retrieving the message and disposing of it appropriately. @@ -42,13 +42,13 @@ case can lead to memory leaks. If for some reason the asynchronous receive cannot be completed successfully (including by being canceled or timing out), then the callback will still be executed, -but <<nng_aio_result.3#,`nng_aio_result()`>> will be non-zero. +but `<<nng_aio_result.3#,nng_aio_result()>>` will be non-zero. NOTE: The semantics of what receiving a message means varies from protocol to protocol, so examination of the protocol documentation is encouraged. (For example, with a <<nng_pub.7#,_pub_>> socket the data is broadcast, so that any peers who have a suitable subscription will be able to receive it using -<<nng_recv.3#,`nng_recv()`>> or a similar function.) +`<<nng_recv.3#,nng_recv()>>` or a similar function.) Furthermore, some protocols may not support receiving (such as <<nng_pub.7#,_pub_>>) or may require other conditions. (For example, <<nng_req.7#,_req_>> sockets cannot normally receive data, which diff --git a/docs/man/nng_recvmsg.3.adoc b/docs/man/nng_recvmsg.3.adoc index c2276511..abe7c723 100644 --- a/docs/man/nng_recvmsg.3.adoc +++ b/docs/man/nng_recvmsg.3.adoc @@ -28,7 +28,7 @@ The `nng_recvmsg()` receives a message on socket _s_, storing the received message at the location pointed to by _msgp_. TIP: Using this function gives access to the message structure, and thus may -offer more functionality than the simpler <<nng_recv.3#,`nng_recv()`>> function. +offer more functionality than the simpler `<<nng_recv.3#,nng_recv()>>` function. The _flags_ may contain the following value: diff --git a/docs/man/nng_rep.7.adoc b/docs/man/nng_rep.7.adoc index 789b515d..962056be 100644 --- a/docs/man/nng_rep.7.adoc +++ b/docs/man/nng_rep.7.adoc @@ -38,7 +38,7 @@ The _rep_ protocol is the replier side, and the === Socket Operations -The <<nng_rep_open.3#,`nng_rep0_open()`>> functions create a replier socket. +The `<<nng_rep_open.3#,nng_rep0_open()>>` functions create a replier socket. This socket may be used to receive messages (requests), and then to send replies. @@ -55,7 +55,7 @@ Any additional concurrent receive operations will result in `NNG_ESTATE`. === Context Operations This protocol supports the creation of <<nng_ctx.5#,contexts>> for concurrent -use cases using <<nng_ctx_open.3#,`nng_ctx_open()`>>. +use cases using `<<nng_ctx_open.3#,nng_ctx_open()>>`. Each context may have at most one outstanding request, and operates independently from the others. diff --git a/docs/man/nng_req.7.adoc b/docs/man/nng_req.7.adoc index 221023c4..282c1db5 100644 --- a/docs/man/nng_req.7.adoc +++ b/docs/man/nng_req.7.adoc @@ -41,10 +41,10 @@ some reason.) (((load-balancing))) The requester generally only has one outstanding request at a time unless in "raw" mode (via -<<nng_options.5#NNG_OPT_RAW,`NNG_OPT_RAW`>>), +`<<nng_options.5#NNG_OPT_RAW,NNG_OPT_RAW>>`), and it will generally attempt to spread work requests to different peer repliers. -TIP: This property, when combined with <<nng_device.3#,`nng_device()`>> +TIP: This property, when combined with `<<nng_device.3#,nng_device()>>` can help provide a degree of load-balancing. The _req_ protocol is the requester side, and the @@ -52,7 +52,7 @@ The _req_ protocol is the requester side, and the === Socket Operations -The <<nng_req_open.3#,`nng_req0_open()`>> functions create a requester socket. +The `<<nng_req_open.3#,nng_req0_open()>>` functions create a requester socket. This socket may be used to send messages (requests), and then to receive replies. Generally a reply can only be received after sending a request. @@ -74,12 +74,14 @@ that has already been placed on the wire. === Context Operations This protocol supports the creation of <<nng_ctx.5#,contexts>> for concurrent -use cases using <<nng_ctx_open.3#,`nng_ctx_open()`>>. +use cases using `<<nng_ctx_open.3#,nng_ctx_open()>>`. + The `NNG_OPT_REQ_RESENDTIME` value may be configured differently on contexts created this way. Each context may have at most one outstanding request, and operates independently from the others. + The restrictions for order of operations with sockets apply equally well for contexts, except that each context will be treated as if it were a separate socket. @@ -95,11 +97,12 @@ The following protocol-specific option is available. ((`NNG_OPT_REQ_RESENDTIME`)):: - This read/write option is a duration (32-bit unsigned integer) representing - a relative number of milliseconds. + This read/write option is a duration (`<<nng_duration.5#,nng_duration>>`) + representing a relative number of milliseconds. When a new request is started, a timer of this duration is also started. If no reply is received before this timer expires, then the request will - be resent. (Requests are also automatically resent if the peer to whom + be resent. + (Requests are also automatically resent if the peer to whom the original request was sent disconnects, or if a peer becomes available while the requester is waiting for an available peer.) @@ -107,7 +110,7 @@ The following protocol-specific option is available. (((backtrace))) This protocol uses a _backtrace_ in the header. -This form uses a "stack" of 32-bit big-endian identifiers. +This form uses a "`stack`" of 32-bit big-endian identifiers. There *must* be at least one identifier, the __request ID__, which will be the last element in the array, and *must* have the most significant bit set. @@ -116,14 +119,14 @@ These will be distinguishable from the request ID by having their most significant bit clear. When a request message is received by a forwarding node (see -<<nng_device.3#,`nng_device()`>>), the forwarding node prepends a +`<<nng_device.3#,nng_device()>>`), the forwarding node prepends a 32-bit peer ID (which *must* have the most significant bit clear), which is the forwarder's way of identifying the directly connected peer from which it received the message. (This peer ID, except for the most significant bit, has meaning only to the forwarding node itself.) -It may help to think of prepending a peer ID as "pushing" a peer ID onto the +It may help to think of prepending a peer ID as "`pushing`" a peer ID onto the front of the stack of headers for the message. (It will use the peer ID it popped from the front to determine the next intermediate destination @@ -132,7 +135,7 @@ for the reply.) When a reply message is created, it is created using the same headers that the request contained. -A forwarding node can "pop" the peer ID it originally pushed on the +A forwarding node can "`pop`" the peer ID it originally pushed on the message, stripping it from the front of the message as it does so. When the reply finally arrives back at the initiating requestor, it diff --git a/docs/man/nng_respondent.7.adoc b/docs/man/nng_respondent.7.adoc index b2060d8e..b03fa75f 100644 --- a/docs/man/nng_respondent.7.adoc +++ b/docs/man/nng_respondent.7.adoc @@ -39,7 +39,7 @@ The _respondent_ protocol is the respondent side, and the === Socket Operations -The <<nng_respondent_open.3#,`nng_respondent0_open()`>> functions create a +The `<<nng_respondent_open.3#,nng_respondent0_open()>>` functions create a respondent socket. This socket may be used to receive messages, and then to send replies. A reply can only be sent after receiving a survey, and generally the @@ -47,13 +47,13 @@ reply will be sent to surveyor from whom the last survey was received. Respondents may discard a survey by simply not replying to it. -Raw mode sockets (set with <<nng_options.5#NNG_OPT_RAW,`NNG_OPT_RAW`>>) +Raw mode sockets (set with `<<nng_options.5#NNG_OPT_RAW,NNG_OPT_RAW>>`) ignore all these restrictions. === Context Operations This protocol supports the creation of <<nng_ctx.5#,contexts>> for concurrent -use cases using <<nng_ctx_open.3#,`nng_ctx_open()`>>. +use cases using `<<nng_ctx_open.3#,nng_ctx_open()>>`. Incoming surveys will be routed to and received by only one context. Additional surveys may be received by other contexts in parallel. diff --git a/docs/man/nng_send.3.adoc b/docs/man/nng_send.3.adoc index 22e09a80..7a1ed0fb 100644 --- a/docs/man/nng_send.3.adoc +++ b/docs/man/nng_send.3.adoc @@ -16,11 +16,11 @@ nng_send - send data == SYNOPSIS [source, c] ------------ +---- #include <nng/nng.h> int nng_send(nng_socket s, void *data, size_t size, int flags); ------------ +---- == DESCRIPTION @@ -31,7 +31,7 @@ NOTE: The semantics of what sending a message means vary from protocol to protocol, so examination of the protocol documentation is encouraged. (For example, with an <<nng_pub.7#,_nng_>> socket the data is broadcast, so that any peers who have a suitable subscription will be able to receive it using -<<nng_recv.3#,`nng_recv()`>> or a similar function.) +`<<nng_recv.3#,nng_recv()>>` or a similar function.) Furthermore, some protocols may not support sending data (such as <<nng_sub.7#,_sub_>>) or may require other conditions. (For example, <<nng_rep.7#,_rep_>> sockets cannot normally send data, @@ -48,12 +48,12 @@ The _flags_ may contain either of (or neither of) the following values: then the function will block if such a condition exists. `NNG_FLAG_ALLOC`:: - The _data_ was allocated using <<nng_alloc.3#,`nng_alloc()`>>, or was - obtained from a call to <<nng_recv.3#,`nng_recv()`>> with + The _data_ was allocated using `<<nng_alloc.3#,nng_alloc()>>`, or was + obtained from a call to `<<nng_recv.3#,nng_recv()>>` with the `NNG_FLAG_ALLOC` flag. If this function returns success, then the _data_ is "owned" by the function, and it will assume responsibility for calling - <<nng_free.3#,`nng_free()`>> when it is no longer needed. + `<<nng_free.3#,nng_free()>>` when it is no longer needed. In the absence of this flag, the _data_ is copied by the implementation before the function returns to the caller. diff --git a/docs/man/nng_send_aio.3.adoc b/docs/man/nng_send_aio.3.adoc index bb110015..47f9df14 100644 --- a/docs/man/nng_send_aio.3.adoc +++ b/docs/man/nng_send_aio.3.adoc @@ -28,11 +28,11 @@ The `nng_send_aio()` sends a <<nng_msg.5#,message>> using the <<nng_socket.5#,socket>> _s_ asynchronously. The message to send must have previously been set on the _aio_ -using the <<nng_aio_set_msg.3#,`nng_aio_set_msg()`>> function. +using the `<<nng_aio_set_msg.3#,nng_aio_set_msg()>>` function. The function assumes "`ownership`" of the message. If the message was successfully queued for delivery to the socket, -then the _aio_ will be completed, and <<nng_aio_result.3#,`nng_aio_result()`>> +then the _aio_ will be completed, and `<<nng_aio_result.3#,nng_aio_result()>>` will return zero. In this case the socket will dispose of the message when it is finished with it. @@ -44,19 +44,20 @@ may still be buffered in the sending socket, buffered in the receiving socket, or in flight over physical media. If the operation fails for any reason (including cancellation or timeout), -then the _aio_ callback will be executed and <<nng_aio_result.3#,`nng_aio_result()`>> +then the _aio_ callback will be executed and +`<<nng_aio_result.3#,nng_aio_result()>>` will return a non-zero error status. In this case, the callback has a responsibity to retrieve the message from -the _aio_ with <<nng_aio_get_msg.3#,`nng_aio_get_msg()`>> and dispose of -it appropriately. +the _aio_ with +`<<nng_aio_get_msg.3#,nng_aio_get_msg()>>` and dispose of it appropriately. (This may include retrying the send operation on the same or a different -socket, or deallocating the message with <<nng_msg_free.3#,`nng_msg_free()`>>.) +socket, or deallocating the message with `<<nng_msg_free.3#,nng_msg_free()>>`.) NOTE: The semantics of what sending a message means varies from protocol to protocol, so examination of the protocol documentation is encouraged. (For example, with a <<nng_pub.7#,_pub_>> socket the data is broadcast, so that any peers who have a suitable subscription will be able to receive it using -<<nng_recv.3#,`nng_recv()`>> or a similar function.) +`<<nng_recv.3#,nng_recv()>>` or a similar function.) Furthermore, some protocols may not support sending (such as <<nng_sub.7#,_sub_>>) or may require other conditions. (For example, <<nng_rep.7#,_rep_>> sockets cannot normally send data, which diff --git a/docs/man/nng_sendmsg.3.adoc b/docs/man/nng_sendmsg.3.adoc index e6d653b3..dffb042f 100644 --- a/docs/man/nng_sendmsg.3.adoc +++ b/docs/man/nng_sendmsg.3.adoc @@ -36,13 +36,13 @@ to dispose of the _msg_, which may include freeing it, sending it to another socket, or simply trying again later. TIP: Using this function gives access to the message structure, and may -offer more functionality than the simpler <<nng_send.3#,`nng_send()`>> function. +offer more functionality than the simpler `<<nng_send.3#,nng_send()>>` function. NOTE: The semantics of what sending a message means vary from protocol to protocol, so examination of the protocol documentation is encouraged. (For example, with a <<nng_pub.7#,_pub_>> socket the data is broadcast, so that any peers who have a suitable subscription will be able to receive it using -<<nng_recv.3#,`nng_recv()`>> or a similar function.) +`<<nng_recv.3#,nng_recv()>>` or a similar function.) Furthermore, some protocols may not support sending (such as <<nng_sub.7#,_sub_>>) or may require other conditions. (For example, <<nng_rep.7#,_rep_>> sockets cannot normally send data, which diff --git a/docs/man/nng_setopt.3.adoc b/docs/man/nng_setopt.3.adoc index 91e54225..d54b7f27 100644 --- a/docs/man/nng_setopt.3.adoc +++ b/docs/man/nng_setopt.3.adoc @@ -70,14 +70,14 @@ The _ival_ is passed to the option. ==== `nng_setopt_ms()` This function is used to configure time durations (such as timeouts) using -type <<nng_duration.5#,`nng_duration`>>. +type `<<nng_duration.5#,nng_duration>>`. The duration _dur_ is an integer number of milliseconds. ==== `nng_setopt_ptr()` This function is used to pass a pointer, _ptr_, to structured data. The data referenced by _ptr_ is generally managed by other functions. For example, TLS configuration objects created with -(<<nng_tls_config_alloc.3tls#,`nng_tls_config_alloc()`>>) +(`<<nng_tls_config_alloc.3tls#,nng_tls_config_alloc()>>`) can be passed this way. Note that this form is somewhat special in that the object is generally not copied, but instead the *pointer* to the object is copied. diff --git a/docs/man/nng_sleep_aio.3.adoc b/docs/man/nng_sleep_aio.3.adoc index 280d0422..c243d6bc 100644 --- a/docs/man/nng_sleep_aio.3.adoc +++ b/docs/man/nng_sleep_aio.3.adoc @@ -29,7 +29,7 @@ causing the callback for _aio_ to be executed after _msec_ milliseconds. If the sleep finishes completely, the result will always be zero. NOTE: If a timeout is set on _aio_ using -<<nng_aio_set_timeout.3#,`nng_aio_set_timeout()`>>, and it is shorter +`<<nng_aio_set_timeout.3#,nng_aio_set_timeout()>>`, and it is shorter than _msec_, then the sleep will wake up early, with a result code of `NNG_ETIMEDOUT`. diff --git a/docs/man/nng_sockaddr.5.adoc b/docs/man/nng_sockaddr.5.adoc index 3d7b4fc2..595f3116 100644 --- a/docs/man/nng_sockaddr.5.adoc +++ b/docs/man/nng_sockaddr.5.adoc @@ -48,8 +48,8 @@ addresses, IPC paths, and so forth. **** The name `sockaddr` is based on it's similarity with POSIX `struct sockaddr`, but in the _nng_ library, these addreses are more closely affiliated with -instances of <<nng_pipe.5#,`nng_pipe`>> -than of <<nng_socket.5#,`nng_socket`>>. +instances of `<<nng_pipe.5#,nng_pipe>>` +than of `<<nng_socket.5#,nng_socket>>`. The naming confusion is unfortunate. **** diff --git a/docs/man/nng_sockaddr_in.5.adoc b/docs/man/nng_sockaddr_in.5.adoc index 94fa18be..5dcc02c6 100644 --- a/docs/man/nng_sockaddr_in.5.adoc +++ b/docs/man/nng_sockaddr_in.5.adoc @@ -33,12 +33,12 @@ typedef struct { == DESCRIPTION (((socket, address, IPv4))) -An `nng_sockaddr_in` is the flavor of <<nng_sockaddr.5#,`nng_sockaddr`>> +An `nng_sockaddr_in` is the flavor of `<<nng_sockaddr.5#,nng_sockaddr>>` used to represent TCP (and sometimes UDP) addresses, including the Internet Protocol (IP) address and port number.(((port number, TCP))) This structure is used with IPv4 addresses. -A different structure, <<nng_sockaddr_in6.5#,`nng_sockaddr_in6`>>, is used +A different structure, `<<nng_sockaddr_in6.5#,nng_sockaddr_in6>>`, is used for IPv6 addresses. The following structure members are present: diff --git a/docs/man/nng_sockaddr_in6.5.adoc b/docs/man/nng_sockaddr_in6.5.adoc index 95e6ec8c..6ac809ba 100644 --- a/docs/man/nng_sockaddr_in6.5.adoc +++ b/docs/man/nng_sockaddr_in6.5.adoc @@ -33,12 +33,12 @@ typedef struct { == DESCRIPTION (((socket, address, IPv6))) -An `nng_sockaddr_in6` is the flavor of <<nng_sockaddr.5#,`nng_sockaddr`>> +An `nng_sockaddr_in6` is the flavor of `<<nng_sockaddr.5#,nng_sockaddr>>` used to represent TCP (and sometimes UDP) addresses, including the Internet Protocol (IP) address and port number.(((port number, TCP))) This structure is used with IPv6 addresses. -A different structure, <<nng_sockaddr_in.5#,`nng_sockaddr_in`>>, is used +A different structure, `<<nng_sockaddr_in.5#,nng_sockaddr_in>>`, is used for IPv4 addresses. The following structure members are present: diff --git a/docs/man/nng_sockaddr_inproc.5.adoc b/docs/man/nng_sockaddr_inproc.5.adoc index b65c3abe..c7901c63 100644 --- a/docs/man/nng_sockaddr_inproc.5.adoc +++ b/docs/man/nng_sockaddr_inproc.5.adoc @@ -32,7 +32,7 @@ typedef struct { == DESCRIPTION (((socket, address, inproc))) -An `nng_sockaddr_inproc` is the flavor of <<nng_sockaddr.5#,`nng_sockaddr`>> +An `nng_sockaddr_inproc` is the flavor of `<<nng_sockaddr.5#,nng_sockaddr>>` used to represent addresses associated with intra-process communication using the <<nng_inproc.7#,_inproc_>> transport. diff --git a/docs/man/nng_sockaddr_ipc.5.adoc b/docs/man/nng_sockaddr_ipc.5.adoc index 3003d51e..3fac561b 100644 --- a/docs/man/nng_sockaddr_ipc.5.adoc +++ b/docs/man/nng_sockaddr_ipc.5.adoc @@ -32,7 +32,7 @@ typedef struct { == DESCRIPTION (((socket, address, IPC))) -An `nng_sockaddr_ipc` is the flavor of <<nng_sockaddr.5#,`nng_sockaddr`>> +An `nng_sockaddr_ipc` is the flavor of `<<nng_sockaddr.5#,nng_sockaddr>>` used to represent addresses associated with IPC communication using the <<nng_ipc.7#,_ipc_>> transport. diff --git a/docs/man/nng_sockaddr_zt.5.adoc b/docs/man/nng_sockaddr_zt.5.adoc index 0ff36276..e601e974 100644 --- a/docs/man/nng_sockaddr_zt.5.adoc +++ b/docs/man/nng_sockaddr_zt.5.adoc @@ -34,7 +34,7 @@ typedef struct { == DESCRIPTION (((socket, address, ZeroTier))) -An `nng_sockaddr_zt` is the flavor of <<nng_sockaddr.5#,`nng_sockaddr`>> +An `nng_sockaddr_zt` is the flavor of `<<nng_sockaddr.5#,nng_sockaddr>>` used to represent ZeroTier addresses, including the (((port number, ZeroTier)))port number used by the <<nng_zerotier.7#,_zt_>> transport. diff --git a/docs/man/nng_socket.5.adoc b/docs/man/nng_socket.5.adoc index 2d8d7256..35a6a3c6 100644 --- a/docs/man/nng_socket.5.adoc +++ b/docs/man/nng_socket.5.adoc @@ -27,9 +27,9 @@ typedef struct nng_socket_s nng_socket; An `nng_socket`(((socket))) is a handle to an underlying "`socket`" object. All communication between the application and remote Scalability Protocol peers is done through sockets. -A given socket can have multiple dialers (<<nng_dialer.5#,`nng_dialer`>>) -and/or (<<nng_listener.5#,`nng_listener`>>), and multiple -pipes (<<nng_pipe.5#,`nng_pipe`>>), and +A given socket can have multiple dialers (`<<nng_dialer.5#,nng_dialer>>`) +and/or listeners (`<<nng_listener.5#,nng_listener>>`), and multiple +pipes (`<<nng_pipe.5#,nng_pipe>>`), and may be connected to multiple transports at the same time. However, a given socket will have exactly one "`protocol`" associated with it, and is responsible for any state machines or other protocol-specific logic. @@ -40,9 +40,9 @@ Passing structures this way ensures gives the compiler a chance to perform accurate type checks in functions passing values of this type. Each `nng_socket` is created by a protocol-specific constructor, such as -<<nng_rep_open.3#,`nng_rep_open()`>>. +`<<nng_rep_open.3#,nng_rep_open()>>`. When the socket is no longer needed, it can be closed with -<<nng_close.3#,`nng_close()`>>. +`<<nng_close.3#,nng_close()>>`. [[NNG_SOCKET_INITIALIZER]] === Initialization diff --git a/docs/man/nng_socket_id.3.adoc b/docs/man/nng_socket_id.3.adoc index b5acc98b..e9379a6b 100644 --- a/docs/man/nng_socket_id.3.adoc +++ b/docs/man/nng_socket_id.3.adoc @@ -29,10 +29,10 @@ if it is valid. Otherwise it returns `-1`. NOTE: A socket is considered valid if it was ever opened with a protocol -constructor, such as the <<nng_req0_open.3#,`nng_req0_open`>> function. +constructor, such as the `<<nng_req0_open.3#,nng_req0_open()>>` function. Sockets that are allocated on the stack or statically should be initialized with the macro -<<nng_socket.5#NNG_SOCKET_INITIALIZER,`NNG_SOCKET_INITIALIZER`>> to ensure that +`<<nng_socket.5#NNG_SOCKET_INITIALIZER,NNG_SOCKET_INITIALIZER>>` to ensure that they cannot be confused with a valid socket before they are opened. == RETURN VALUES diff --git a/docs/man/nng_strdup.3.adoc b/docs/man/nng_strdup.3.adoc index 23e23a43..6efacc37 100644 --- a/docs/man/nng_strdup.3.adoc +++ b/docs/man/nng_strdup.3.adoc @@ -26,14 +26,14 @@ char *nng_strdup(const char *src); The `nng_strdup()` duplicates the string _src_ and returns it. -This is logically equiavlent to using <<nng_alloc.3#,`nng_alloc()`>> +This is logically equiavlent to using `<<nng_alloc.3#,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.3#,`nng_strfree()`>>, or may be deallocated using the -<<nng_free.3#,`nng_free()`>> using the length of the returned string plus +`<<nng_strfree.3#,nng_strfree()>>`, or may be deallocated using the +`<<nng_free.3#,nng_free()>>` using the length of the returned string plus one (for the `NUL` terminating byte). IMPORTANT: Do not use the system `free()` or similar functions to deallocate diff --git a/docs/man/nng_strfree.3.adoc b/docs/man/nng_strfree.3.adoc index 2e6569a8..9b91306f 100644 --- a/docs/man/nng_strfree.3.adoc +++ b/docs/man/nng_strfree.3.adoc @@ -25,20 +25,20 @@ void nng_strfree(char *str); == DESCRIPTION The `nng_strfree()` function deallocates the string _str_. -This is equivalent to using <<nng_free.3#,`nng_free()`>> with +This is equivalent to using `<<nng_free.3#,nng_free()>>` with the length of _str_ plus one (for the `NUL` terminating byte) as the size. IMPORTANT: This should only be used with strings that were allocated -by <<nng_strdup.3#,`nng_strdup()`>> or -<<nng_alloc.3#,`nng_alloc()`>>. +by `<<nng_strdup.3#,nng_strdup()>>` or +`<<nng_alloc.3#,nng_alloc()>>`. In all cases, the allocation size of the string must be the same as `strlen(__str__) + 1`. IMPORTANT: Consequently, if the a string created with -<<nng_strdup.3#,`nng_strdup()`>> is modified to be shorter, then +`<<nng_strdup.3#,nng_strdup()>>` is modified to be shorter, then it is incorrect to call this function. -(The <<nng_free.3#,`nng_free()`>> function can be used instead in that +(The `<<nng_free.3#,nng_free()>>` function can be used instead in that case, using the length of the original string plus one for the size.) == RETURN VALUES diff --git a/docs/man/nng_sub.7.adoc b/docs/man/nng_sub.7.adoc index 18606f2b..904f844e 100644 --- a/docs/man/nng_sub.7.adoc +++ b/docs/man/nng_sub.7.adoc @@ -43,7 +43,7 @@ Applications should construct their messages accordingly. === Socket Operations -The <<nng_sub_open.3#,`nng_sub0_open()`>> functions create a subscriber socket. +The `<<nng_sub_open.3#,nng_sub0_open()>>` functions create a subscriber socket. This socket may be used to receive messages, but is unable to send them. Attempts to send messages will result in `NNG_ENOTSUP`. diff --git a/docs/man/nng_surveyor.7.adoc b/docs/man/nng_surveyor.7.adoc index 7a8d2073..69936748 100644 --- a/docs/man/nng_surveyor.7.adoc +++ b/docs/man/nng_surveyor.7.adoc @@ -40,7 +40,7 @@ The _surveyor_ protocol is the surveyor side, and the === Socket Operations -The <<nng_surveyor_open.3#,`nng_surveyor0_open()`>> +The `<<nng_surveyor_open.3#,nng_surveyor0_open()>>` functions create a surveyor socket. This socket may be used to send messages (surveys), and then to receive replies. A reply can only be received after sending a survey. @@ -62,14 +62,16 @@ survey that arrive after this will be discarded. === Context Operations This protocol supports the creation of <<nng_ctx.5#,contexts>> for concurrent -use cases using <<nng_ctx_open.3#,`nng_ctx_open()`>>. +use cases using `<<nng_ctx_open.3#,nng_ctx_open()>>`. Each context can initiate its own surveys, and it will receive only responses to its own outstanding surveys. Other contexts on the same socket may have overlapping surveys operating at the same time. + Each of these may have their own timeouts established with `NNG_OPT_SURVEYOR_SURVEYTIME`. + Additionally, sending a survey on a context will only cancel an outstanding survey on the same context. @@ -92,7 +94,7 @@ The following protocol-specific options is available. ((`NNG_OPT_SURVEYOR_SURVEYTIME`)):: - This read/write option is an <<nng_duration.5#,`nng_duration`>> + This read/write option is an `<<nng_duration.5#,nng_duration>>` representing a postive number of milliseconds that following surveys will last. When a new survey is started, a timer of this duration is also started. @@ -105,7 +107,7 @@ The following protocol-specific options is available. === Protocol Headers (((backtrace))) -This form uses a "stack" of 32-bit big-endian identifiers. +This form uses a "`stack`" of 32-bit big-endian identifiers. There *must* be at least one identifier, the __survey ID__, which will be the last element in the array, and *must* have the most significant bit set. @@ -114,14 +116,14 @@ These will be distinguishable from the survey ID by having their most significant bit clear. When a survey message is received by a forwarding node (see -<<nng_device.3#,`nng_device()`>>), the forwarding node prepends a +`<<nng_device.3#,nng_device()>>`), the forwarding node prepends a 32-bit peer ID (which *must* have the most significant bit clear), which is the forwarder's way of identifying the directly connected peer from which it received the message. (This peer ID, except for the most significant bit, has meaning only to the forwarding node itself.) -It may help to think of prepending a peer ID as "pushing" a peer ID onto the +It may help to think of prepending a peer ID as "`pushing`" a peer ID onto the front of the stack of headers for the message. (It will use the peer ID it popped from the front to determine the next intermediate destination @@ -130,7 +132,7 @@ for the response.) When a response message is created, it is created using the same headers that the survey contained. -A forwarding node can "pop" the peer ID it originally pushed on the +A forwarding node can "`pop`" the peer ID it originally pushed on the message, stripping it from the front of the message as it does so. When the response finally arrives back at the initiating surveyor, it diff --git a/docs/man/nng_tcp.7.adoc b/docs/man/nng_tcp.7.adoc index 1d925b79..aa90364e 100644 --- a/docs/man/nng_tcp.7.adoc +++ b/docs/man/nng_tcp.7.adoc @@ -74,10 +74,10 @@ The entire URI must be less than `NNG_MAXADDRLEN` bytes long. === Socket Address -When using an <<nng_sockaddr.5#,`nng_sockaddr`>> structure, +When using an `<<nng_sockaddr.5#,nng_sockaddr>>` structure, the actual structure is either of type -<<nng_sockaddr_in.5#,`nng_sockaddr_in`>> (for IPv4) or -<<nng_sockaddr_in6.5#,`nng_sockaddr_in6`>> (for IPv6). +`<<nng_sockaddr_in.5#,nng_sockaddr_in>>` (for IPv4) or +`<<nng_sockaddr_in6.5#,nng_sockaddr_in6>>` (for IPv6). === Transport Options diff --git a/docs/man/nng_thread_create.3supp.adoc b/docs/man/nng_thread_create.3supp.adoc index 359dabab..b458cf96 100644 --- a/docs/man/nng_thread_create.3supp.adoc +++ b/docs/man/nng_thread_create.3supp.adoc @@ -42,7 +42,7 @@ programs that use simple sequential execution, using functions in the _NNG_ suite that would otherwise normally "`block`". When the thread is no longer needed, the -<<nng_thread_destroy.3supp#,`nng_thread_destroy()`>> +`<<nng_thread_destroy.3supp#,nng_thread_destroy()>>` function should be used to reap it. (This function will block waiting for _func_ to return.) @@ -61,7 +61,7 @@ TIP: The system may impose limits on the number of threads that can be created. Typically applications should not create more than a few dozen of these. If greater concurrency or scalability is needed, consider instead using -an asynchronous model using <<nng_aio.5#,`nng_aio`>> structures. +an asynchronous model using `<<nng_aio.5#,nng_aio>>` structures. TIP: Threads can be synchronized using <<nng_mtx_alloc.3supp#,mutexes>> and diff --git a/docs/man/nng_tls.7.adoc b/docs/man/nng_tls.7.adoc index c783f739..249159b7 100644 --- a/docs/man/nng_tls.7.adoc +++ b/docs/man/nng_tls.7.adoc @@ -38,7 +38,7 @@ http://nanomsg.org/rfcs/sp-tls-v1.html[TLS Mapping for Scalability Protocols]. Depending upon how the library was built, it may be necessary to register the transport by calling -<<nng_tls_register.3#,`nng_tls_register()`>>. +`<<nng_tls_register.3#,nng_tls_register()>>`. === Availability @@ -100,10 +100,10 @@ The entire URI must be less than `NNG_MAXADDRLEN` bytes long. === Socket Address -When using an <<nng_sockaddr.5#,`nng_sockaddr`>> structure, +When using an `<<nng_sockaddr.5#,nng_sockaddr>>` structure, the actual structure is either of type -<<nng_sockaddr_in.5#,`nng_sockaddr_in`>> (for IPv4) or -<<nng_sockaddr_in6.5#,`nng_sockaddr_in6`>> (for IPv6). +`<<nng_sockaddr_in.5#,nng_sockaddr_in>>` (for IPv4) or +`<<nng_sockaddr_in6.5#,nng_sockaddr_in6>>` (for IPv6). === Transport Options @@ -138,7 +138,7 @@ TIP: Use this option when advanced TLS configuration is required. This is a write-only option used to load certificates associated associated private key from a file. -See <<nng_tls_config_ca_file.3tls#,`nng_tls_config_ca_file()`>> for more +See `<<nng_tls_config_ca_file.3tls#,nng_tls_config_ca_file()>>` for more information. ((`NNG_OPT_TLS_CERT_KEY_FILE`)):: @@ -147,7 +147,7 @@ This is a write-only option used to load the local certificate and associated private key from a file. The private key used must be unencrypted. (Use the `NNG_OPT_TLS_CONFIG` option to access the underlying TLS configuration if more advanced configuration is needed.) -See <<nng_tls_config_own_cert.3tls#,`nng_tls_config_own_cert()`>> for more +See `<<nng_tls_config_own_cert.3tls#,nng_tls_config_own_cert()>>` for more information. ((`NNG_OPT_TLS_AUTH_MODE`)):: @@ -155,7 +155,7 @@ information. This is a write-only option used to configure the authentication mode used. It can take an integer with value `NNG_TLS_AUTH_MODE_NONE`, `NNG_TLS_AUTH_MODE_REQUIRED`, or `NNG_TLS_AUTH_MODE_OPTIONAL`. -See <<nng_tls_config_auth_mode.3tls#,`nng_tls_config_auth_mode()`>> for +See `<<nng_tls_config_auth_mode.3tls#,nng_tls_config_auth_mode()>>` for more details. ((`NNG_OPT_TLS_VERIFIED`)):: diff --git a/docs/man/nng_ws.7.adoc b/docs/man/nng_ws.7.adoc index d3b68b99..bc0d9d51 100644 --- a/docs/man/nng_ws.7.adoc +++ b/docs/man/nng_ws.7.adoc @@ -37,11 +37,11 @@ http://nanomsg.org/rfcs/sp-websocket-v1.html[WebSocket Mapping for Scalability P === Registration Depending upon how the library was built, it may be necessary to -register the transport by calling <<nng_ws_register.3#,`nng_ws_register()`>>. +register the transport by calling `<<nng_ws_register.3#,nng_ws_register()>>`. If ((TLS)) support is enabled in the library, secure WebSockets (over TLS v1.2) can be used as well, but the secure transport may have to be registered using -the <<nng_wss_register.3#,`nng_wss_register()`>> function. +the `<<nng_wss_register.3#,nng_wss_register()>>` function. === URI Format @@ -82,10 +82,10 @@ permitted, with IPv4 addresses mapped to IPv6 addresses.) === Socket Address -When using an <<nng_sockaddr.5#,`nng_sockaddr`>> structure, +When using an `<<nng_sockaddr.5#,nng_sockaddr>>` structure, the actual structure is either of type -<<nng_sockaddr_in.5#,`nng_sockaddr_in`>> (for IPv4) or -<<nng_sockaddr_in6.5#,`nng_sockaddr_in6`>> (for IPv6). +`<<nng_sockaddr_in.5#,nng_sockaddr_in>>` (for IPv4) or +`<<nng_sockaddr_in6.5#,nng_sockaddr_in6>>` (for IPv6). === Server Instances @@ -143,7 +143,7 @@ TIP: Use this option when advanced TLS configuration is required. (string) This is a write-only option used to load certificates associated associated private key from a file. -See <<nng_tls_config_ca_file.3tls#,`nng_tls_config_ca_file()`>> for more +See `<<nng_tls_config_ca_file.3tls#,nng_tls_config_ca_file()>>` for more information. ((`NNG_OPT_TLS_CERT_KEY_FILE`)):: @@ -153,7 +153,7 @@ associated private key from a file. The private key used must be unencrypted. (Use the `NNG_OPT_TLS_CONFIG` option to access the underlying TLS configuration if more advanced configuration is needed.) -See <<nng_tls_config_own_cert.3tls#,`nng_tls_config_own_cert()`>> for more +See `<<nng_tls_config_own_cert.3tls#,nng_tls_config_own_cert()>>` for more information. ((`NNG_OPT_TLS_AUTH_MODE`)):: @@ -162,7 +162,7 @@ information. used. It can take an integer with value `NNG_TLS_AUTH_MODE_NONE`, `NNG_TLS_AUTH_MODE_REQUIRED`, or `NNG_TLS_AUTH_MODE_OPTIONAL`. -See <<nng_tls_config_auth_mode.3tls#,`nng_tls_config_auth_mode()`>> for more +See `<<nng_tls_config_auth_mode.3tls#,nng_tls_config_auth_mode()>>` for more details. `NNG_OPT_TLS_VERIFIED`:: diff --git a/docs/man/nng_zerotier.7.adoc b/docs/man/nng_zerotier.7.adoc index c26f1f50..6325bbb3 100644 --- a/docs/man/nng_zerotier.7.adoc +++ b/docs/man/nng_zerotier.7.adoc @@ -59,7 +59,7 @@ concepts and administration. Depending upon how the library was built, it may be necessary to register the transport by calling -<<nng_zt_register.3#,`nng_zt_register()`>>. +`<<nng_zt_register.3#,nng_zt_register()>>`. This function returns zero on success, or an nng error value if the transport cannot be initialized for any reason. @@ -81,13 +81,13 @@ the node's own node number. Listeners may use port 0 to indicate that a suitable port number be selected automatically. Applications using this must determine the selected port number using the -<<nng_listener_getopt.3#,`nng_listener_getopt()`>> function. +`<<nng_listener_getopt.3#,nng_listener_getopt()>>` function. === Socket Address -When using an <<nng_sockaddr.5#,`nng_sockaddr`>> structure, +When using an `<<nng_sockaddr.5#,nng_sockaddr>>` structure, the actual structure is of type -<<nng_sockaddr_zt.5#,`nng_sockaddr_zt`>>. +`<<nng_sockaddr_zt.5#,nng_sockaddr_zt>>`. === Node Presence @@ -176,7 +176,7 @@ in this fashion. [[NNG_OPT_ZT_CONN_TIME]] ((`NNG_OPT_ZT_CONN_TIME`)):: The time to wait between sending connection attempts. - This is an <<nng_duration.5#,`nng_duration`>> (msec), + This is an `<<nng_duration.5#,nng_duration>>` (msec), and is only used with dialers. The default is 500 msec. @@ -192,7 +192,7 @@ in this fashion. ((`NNG_OPT_ZT_PING_TIME`)):: If no traffic has been received from the ZeroTier peer after this period of time, then a "`ping`" message is sent to check if the peer - is still alive. This is an <<nng_duration.5#,`nng_duration`>> (msec). + is still alive. This is an `<<nng_duration.5#,nng_duration>>` (msec). [[NNG_OPT_ZT_PING_TRIES]] ((`NNG_OPT_ZT_PING_TRIES`)):: |