From 3d3fa690c4f81bf4ed0a2de42c3c8fbb9f4cca5c Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Tue, 1 May 2018 17:11:32 -0700 Subject: [PATCH] Markup fixes, ensuring links are colored properly. It turns out that when creating cross references, we need to make any text styling (generally literal characters) outside of the link, to avoid having the styling override the link color. (We prefer to have links colored for ease of use.) While here a few other markup, and actual content, errors were fixed. --- docs/man/libnng.3.adoc | 6 ++-- docs/man/nn_bind.3compat.adoc | 2 +- docs/man/nn_connect.3compat.adoc | 2 +- docs/man/nn_freemsg.3compat.adoc | 2 +- docs/man/nn_poll.3compat.adoc | 2 +- docs/man/nn_send.3compat.adoc | 2 +- docs/man/nng.7.adoc | 6 ++-- docs/man/nng_aio.5.adoc | 10 +++--- docs/man/nng_aio_abort.3.adoc | 2 +- docs/man/nng_aio_alloc.3.adoc | 12 +++---- docs/man/nng_aio_cancel.3.adoc | 8 ++--- docs/man/nng_aio_count.3.adoc | 4 +-- docs/man/nng_aio_finish.3.adoc | 2 +- docs/man/nng_aio_free.3.adoc | 2 +- docs/man/nng_aio_get_input.3.adoc | 2 +- docs/man/nng_aio_get_msg.3.adoc | 6 ++-- docs/man/nng_aio_result.3.adoc | 2 +- docs/man/nng_aio_set_input.3.adoc | 2 +- docs/man/nng_aio_set_iov.3.adoc | 2 +- docs/man/nng_aio_set_msg.3.adoc | 4 +-- docs/man/nng_aio_set_output.3.adoc | 2 +- docs/man/nng_aio_stop.3.adoc | 2 +- docs/man/nng_alloc.3.adoc | 4 +-- docs/man/nng_bus.7.adoc | 2 +- docs/man/nng_close.3.adoc | 2 +- docs/man/nng_compat.3compat.adoc | 2 +- docs/man/nng_ctx.5.adoc | 8 ++--- docs/man/nng_ctx_close.3.adoc | 4 +-- docs/man/nng_ctx_getopt.3.adoc | 4 +-- docs/man/nng_ctx_id.3.adoc | 4 +-- docs/man/nng_ctx_recv.3.adoc | 6 ++-- docs/man/nng_ctx_send.3.adoc | 14 ++++---- docs/man/nng_ctx_setopt.3.adoc | 2 +- docs/man/nng_cv_alloc.3supp.adoc | 8 ++--- docs/man/nng_cv_until.3supp.adoc | 6 ++-- docs/man/nng_cv_wait.3supp.adoc | 4 +-- docs/man/nng_cv_wake.3supp.adoc | 6 ++-- docs/man/nng_cv_wake1.3supp.adoc | 6 ++-- docs/man/nng_device.3.adoc | 8 ++--- docs/man/nng_dial.3.adoc | 6 ++-- docs/man/nng_dialer.5.adoc | 12 +++---- docs/man/nng_dialer_close.3.adoc | 2 +- docs/man/nng_dialer_create.3.adoc | 8 ++--- docs/man/nng_dialer_getopt.3.adoc | 6 ++-- docs/man/nng_dialer_id.3.adoc | 6 ++-- docs/man/nng_dialer_setopt.3.adoc | 4 +-- docs/man/nng_free.3.adoc | 4 +-- docs/man/nng_getopt.3.adoc | 4 +-- docs/man/nng_http_client_connect.3http.adoc | 4 +-- docs/man/nng_http_client_free.3http.adoc | 2 +- docs/man/nng_http_client_set_tls.3http.adoc | 4 +-- docs/man/nng_http_conn_read.3http.adoc | 6 ++-- docs/man/nng_http_conn_read_all.3http.adoc | 19 +++++----- docs/man/nng_http_conn_read_req.3http.adoc | 4 +-- docs/man/nng_http_conn_read_res.3http.adoc | 4 +-- docs/man/nng_http_conn_write.3http.adoc | 6 ++-- docs/man/nng_http_conn_write_all.3http.adoc | 21 +++++------ docs/man/nng_http_conn_write_req.3http.adoc | 6 ++-- docs/man/nng_http_conn_write_res.3http.adoc | 6 ++-- docs/man/nng_http_handler_alloc.3http.adoc | 18 +++++----- docs/man/nng_http_handler_get_data.3http.adoc | 2 +- docs/man/nng_http_handler_set_data.3http.adoc | 2 +- .../nng_http_handler_set_method.3http.adoc | 2 +- docs/man/nng_http_hijack.3http.adoc | 4 +-- docs/man/nng_http_req_add_header.3http.adoc | 2 +- docs/man/nng_http_req_copy_data.3http.adoc | 4 +-- docs/man/nng_http_req_set_data.3http.adoc | 4 +-- docs/man/nng_http_req_set_header.3http.adoc | 2 +- docs/man/nng_http_req_set_uri.3http.adoc | 2 +- docs/man/nng_http_res_add_header.3http.adoc | 2 +- docs/man/nng_http_res_alloc.3http.adoc | 2 +- docs/man/nng_http_res_copy_data.3http.adoc | 4 +-- docs/man/nng_http_res_get_reason.3http.adoc | 6 ++-- docs/man/nng_http_res_get_status.3http.adoc | 4 +-- docs/man/nng_http_res_set_data.3http.adoc | 4 +-- docs/man/nng_http_res_set_header.3http.adoc | 2 +- docs/man/nng_http_res_set_reason.3http.adoc | 2 +- docs/man/nng_http_res_set_status.3http.adoc | 6 ++-- .../nng_http_server_add_handler.3http.adoc | 2 +- docs/man/nng_http_server_hold.3http.adoc | 2 +- docs/man/nng_http_server_release.3http.adoc | 2 +- docs/man/nng_http_server_set_tls.3http.adoc | 6 ++-- docs/man/nng_inproc.7.adoc | 4 +-- docs/man/nng_iov.5.adoc | 4 +-- docs/man/nng_ipc.7.adoc | 4 +-- docs/man/nng_listen.3.adoc | 8 ++--- docs/man/nng_listener.5.adoc | 16 ++++----- docs/man/nng_listener_create.3.adoc | 8 ++--- docs/man/nng_listener_getopt.3.adoc | 6 ++-- docs/man/nng_listener_id.3.adoc | 6 ++-- docs/man/nng_listener_setopt.3.adoc | 4 +-- docs/man/nng_listener_start.3.adoc | 2 +- docs/man/nng_msg.5.adoc | 4 +-- docs/man/nng_msg_body.3.adoc | 12 +++---- docs/man/nng_msg_get_pipe.3.adoc | 4 +-- docs/man/nng_msg_header.3.adoc | 2 +- docs/man/nng_msg_realloc.3.adoc | 4 +-- docs/man/nng_mtx_lock.3supp.adoc | 6 ++-- docs/man/nng_mtx_unlock.3supp.adoc | 2 +- docs/man/nng_options.5.adoc | 36 +++++++++---------- docs/man/nng_pair.7.adoc | 18 +++++----- docs/man/nng_pipe.5.adoc | 6 ++-- docs/man/nng_pipe_close.3.adoc | 2 +- docs/man/nng_pipe_getopt.3.adoc | 12 +++---- docs/man/nng_pipe_id.3.adoc | 7 ++-- docs/man/nng_pub.7.adoc | 2 +- docs/man/nng_pull.7.adoc | 2 +- docs/man/nng_push.7.adoc | 2 +- docs/man/nng_recv.3.adoc | 6 ++-- docs/man/nng_recv_aio.3.adoc | 8 ++--- docs/man/nng_recvmsg.3.adoc | 2 +- docs/man/nng_rep.7.adoc | 4 +-- docs/man/nng_req.7.adoc | 25 +++++++------ docs/man/nng_respondent.7.adoc | 6 ++-- docs/man/nng_send.3.adoc | 12 +++---- docs/man/nng_send_aio.3.adoc | 15 ++++---- docs/man/nng_sendmsg.3.adoc | 4 +-- docs/man/nng_setopt.3.adoc | 4 +-- docs/man/nng_sleep_aio.3.adoc | 2 +- docs/man/nng_sockaddr.5.adoc | 4 +-- docs/man/nng_sockaddr_in.5.adoc | 4 +-- docs/man/nng_sockaddr_in6.5.adoc | 4 +-- docs/man/nng_sockaddr_inproc.5.adoc | 2 +- docs/man/nng_sockaddr_ipc.5.adoc | 2 +- docs/man/nng_sockaddr_zt.5.adoc | 2 +- docs/man/nng_socket.5.adoc | 10 +++--- docs/man/nng_socket_id.3.adoc | 4 +-- docs/man/nng_strdup.3.adoc | 6 ++-- docs/man/nng_strfree.3.adoc | 10 +++--- docs/man/nng_sub.7.adoc | 2 +- docs/man/nng_surveyor.7.adoc | 16 +++++---- docs/man/nng_tcp.7.adoc | 6 ++-- docs/man/nng_thread_create.3supp.adoc | 4 +-- docs/man/nng_tls.7.adoc | 14 ++++---- docs/man/nng_ws.7.adoc | 16 ++++----- docs/man/nng_zerotier.7.adoc | 12 +++---- 136 files changed, 395 insertions(+), 388 deletions(-) diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc index 149dc9f46..61ceacc7f 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 <> will block the calling +functions such as `<>` 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 <>, is allocated and +A context structure, an `<>`, 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 79ff2c044..42f5c58f6 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 `<>`` to +This ID can be used with `<>` 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 add140603..f5002b822 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 `<>`` to +This ID can be used with `<>` 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 d23d9f0a7..cfdc59573 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 -`<>`` or similar functions. +`<>` or similar functions. NOTE: This function is provided for API <> with legacy _libnanomsg_. diff --git a/docs/man/nn_poll.3compat.adoc b/docs/man/nn_poll.3compat.adoc index 0a1f02e66..a1e139925 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 -`<>`` function, and is not compatible +`<>` 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 `<>` diff --git a/docs/man/nn_send.3compat.adoc b/docs/man/nn_send.3compat.adoc index 181d8c7fd..79029b618 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 `<>` or `<>`, 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 754d93318..425d2c0f8 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 <>. +such as `<>`. 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 <> function only works with raw mode +TIP: The `<>` 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 4353652d9..292d13c1c 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 <>), as well setting a maximum +(see `<>`), as well setting a maximum timeout for them to complete within -(see <>). +(see `<>`). It is also possible to initiate an asynchronous operation, and wait for it to -complete using <>. +complete using `<>`. -These structures are created using the <>, -and destroyed using <>. +These structures are created using the `<>`, +and destroyed using `<>`. == SEE ALSO diff --git a/docs/man/nng_aio_abort.3.adoc b/docs/man/nng_aio_abort.3.adoc index 4216343e2..3a68f0151 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 -<> will return the error _err_. +`<>` 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 71521f470..9e92dd4aa 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 <> +Asynchronous I/O operations all take an `<>` 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 -<>, -<>, -and <>. +`<>`, +`<>`, +and `<>`. It is possible to wait synchronously for an otherwise asynchronous operation -by using the function <>. +by using the function `<>`. 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 -<>. +`<>`. == RETURN VALUES diff --git a/docs/man/nng_aio_cancel.3.adoc b/docs/man/nng_aio_cancel.3.adoc index 77573bac3..51148fa1f 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 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 -<> will return the error `NNG_ECANCELED`. +`<>` 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 -<> with the error `NNG_ECANCELED`. +`<>` 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 dc467abd4..8050ce9ad 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 <>). +of a scatter/gather vector (set by `<>`). 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 -<>. +`<>`. == RETURN VALUES diff --git a/docs/man/nng_aio_finish.3.adoc b/docs/man/nng_aio_finish.3.adoc index 9d03d8597..ee82ed10a 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 -<>. +`<>`. 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 19a371985..0b19f4bec 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 <>.) +(This is done by implicitly calling `<>`.) == RETURN VALUES diff --git a/docs/man/nng_aio_get_input.3.adoc b/docs/man/nng_aio_get_input.3.adoc index e0e0d5457..018f7d045 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 -<> function. +`<>` 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 4ae1c38bb..d884c28b4 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 <>) -or that was previously stored with <>. +(see `<>`) +or that was previously stored with `<>`. -IMPORTANT: The `nng_aio` must not have an operation in progress. +IMPORTANT: The `<>` 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 38208d77d..a793b9ad2 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 -<>. +`<>`. == RETURN VALUES diff --git a/docs/man/nng_aio_set_input.3.adoc b/docs/man/nng_aio_set_input.3.adoc index dd921d52a..696f15136 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 <> function. +the `<>` function. == RETURN VALUES diff --git a/docs/man/nng_aio_set_iov.3.adoc b/docs/man/nng_aio_set_iov.3.adoc index b896f5de0..ed200a13b 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_ <> +The _iov_ is a pointer to an array of _niov_ `<>` 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 8f3c594fa..c0147e658 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 <>). +for an asynchronous send operation (see `<>`). -IMPORTANT: The `nng_aio` must not have an operation in progress. +IMPORTANT: The `<>` 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 8eef410a5..2f753db7e 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 <> function. +the `<>` function. == RETURN VALUES diff --git a/docs/man/nng_aio_stop.3.adoc b/docs/man/nng_aio_stop.3.adoc index 02c258f8c..12e8d1da6 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 <>, particularly if the callbacks +this with `<>`, 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 a43140d11..3b6e27ddf 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 <> using +case it can be directly passed to `<>` using the flag `NNG_FLAG_ALLOC`. Alternatively, it can be freed when no -longer needed using <>. +longer needed using `<>`. 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 d5c577107..bb993f7cf 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 <> functions create a bus socket. +The `<>` 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 3f1c68f3a..e1753dc36 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 -<> option. +`<>` 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 42b0942e8..77e55313b 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"] |=== -|`<>|create socket +|`<>`|create socket |`<>`|get socket option |`<>`|set socket option |`<>`|accept connections from remote peers diff --git a/docs/man/nng_ctx.5.adoc b/docs/man/nng_ctx.5.adoc index ada117c3a..483a4c1f3 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 -<> or -<> options) while contexts +`<>` or +`<>` 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 <> has already been created and any transports set up as well with functions such as -<> -or <>. +`<>` +or `<>`. [source,c] ---- diff --git a/docs/man/nng_ctx_close.3.adoc b/docs/man/nng_ctx_close.3.adoc index 16d9432e4..32cb44f6b 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 -<> option. +`<>` 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 <>) also closes this context. +(using `<>`) 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 b20ea3b4c..d6a19a164 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 <> +This string is created from the source using `<>` and consequently must be freed by the caller using -<> when it is no longer needed. +`<>` 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 56d9d7bdb..ba79684c7 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 -<> function. +`<>` function. Contexts that are allocated on the stack or statically should be initialized with the macro -<> to ensure that +`<>` 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 d4e84b00d..03aa5de89 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 <> using the When a message is successfully received by the context, it is stored in the _aio_ by an internal call equivalent to -<>, then the completion +`<>`, then the completion callback on the _aio_ is executed. -In this case, <> will +In this case, `<>` 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 <> will be non-zero. +but `<>` 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 95c1a118e..9780c0bdf 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 <> using the <> _ctx_ asynchronously. The message to send must have previously been set on the _aio_ -using the <> function. +using the `<>` 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 <> +then the _aio_ will be completed, and `<>` 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 <> -will return a non-zero error status. +then the _aio_ callback will be executed and +`<>` will return a non-zero error status. In this case, the callback has a responsibity to retrieve the message from -the _aio_ with <> and dispose of +the _aio_ with `<>` and dispose of it appropriately. (This may include retrying the send operation on the same or a different -socket, or deallocating the message with <>.) +socket, or deallocating the message with `<>`.) 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 -<>. +`<>`. == RETURN VALUES diff --git a/docs/man/nng_ctx_setopt.3.adoc b/docs/man/nng_ctx_setopt.3.adoc index 4ab36e079..a81b20f45 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 <>. +type `<>`. 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 0668298f8..ac059a927 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 -<> or -<>. +`<>` or +`<>`. The mutex must also be owned when signaling the condition using the -<> or -<> functions. +`<>` or +`<>` functions. == RETURN VALUES diff --git a/docs/man/nng_cv_until.3supp.adoc b/docs/man/nng_cv_until.3supp.adoc index 4d39ecc0a..9cf49e4d3 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 <> or -<>, or the system clock (as tracked -by <>) reaches _when_. +by another thread calling either `<>` or +`<>`, or the system clock (as tracked +by `<>`) 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 034b3ea9d..005fe0c70 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 <> or -<>. +by another thread calling either `<>` or +`<>`. 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 ad8dadfe9..756428842 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 <> or -<> functions. +to be signaled in the `<>` or +`<>` 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 <> for a solution to this problem. +See `<>` 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 1938a7020..29a4ed88e 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 <> or -<> functions. +to be signaled in the `<>` or +`<>` 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 <>. +When in doubt, it is safer to use `<>`. == RETURN VALUES diff --git a/docs/man/nng_device.3.adoc b/docs/man/nng_device.3.adoc index aaf71af69..4f036d03e 100644 --- a/docs/man/nng_device.3.adoc +++ b/docs/man/nng_device.3.adoc @@ -34,15 +34,15 @@ reliability, and isolation. Only <> mode sockets may be used with this function. These can be created using `_raw` forms of the various socket constructors, -such as <>. +such as `<>`. 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, -<> of course). +One of the sockets may be passed an inititalize `-1` (cast to an, +`<>` 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 <> 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 <> +This is controlled via the `<>` 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 525f092ad..d2eb76058 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 -<> object, +`<>` 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 <> and -<> instead. +using `<>` and +`<>` instead. == RETURN VALUES diff --git a/docs/man/nng_dialer.5.adoc b/docs/man/nng_dialer.5.adoc index 3f742c217..b2c243255 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 <> at a time by +creating a single `<>` 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 -<> -or <> functions, and are always "`owned`" -by a single <>. +`<>` +or `<>` functions, and are always "`owned`" +by a single `<>`. 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 <> may have multiple dialer +TIP: A given `<>` may have multiple dialer objects, multiple <> 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 -<> function. +`<>` 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 01ac91ed3..a89ad6831 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 <> ojects that have +This also closes any `<>` 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 3181f10e0..b7ce82fa4 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 -<> object, associated with socket _s_, +`<>` 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 <> family of functions. +the `<>` family of functions. Once it is fully configured, the dialer may be started using the -<> function. +`<>` function. TIP: If no specific configuration is required, consider using the -simpler <> function instead. +simpler `<>` function instead. == RETURN VALUES diff --git a/docs/man/nng_dialer_getopt.3.adoc b/docs/man/nng_dialer_getopt.3.adoc index bdabc5d9d..e9054b898 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 <> +This function is used to retrieve an `<>` 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 <> +This string is created from the source using `<>` and consequently must be freed by the caller using -<> when it is no longer needed. +`<>` 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 cf8936b51..a25125f49 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 -<> or -<> functions. +`<>` or +`<>` functions. Dialers that are allocated on the stack or statically should be initialized with the macro -<> to ensure that +`<>` 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 330657d01..540d5c2b1 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 <>. +type `<>`. 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 -(<>) +(`<>`) 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 d17f3da5f..ac110db1f 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 <> or -<> with the `NNG_FLAG_ALLOC` flag. +that was previously allocated by `<>` or +`<>` 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 306efbe90..45c5a295b 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 <> +This string is created from the source using `<>` and consequently must be freed by the caller using -<> when it is no longer needed. +`<>` 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 47fcb4e07..397c7f2fd 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 -<>. +`<>`. 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 -<> with an _index_ of zero (0). +`<>` 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 6158143c2..33d6cf055 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 -<> are unaffected, +`<>` 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 756867786..5ed8bda81 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 -<>. +`<>`. NOTE: Any connections established with -<> +`<>` 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 d6094ff01..f6e9fad17 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 <> function must have been +NOTE: The `<>` 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 -<>. +`<>`. 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 -<>. +`<>`. 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 78a89a13d..0a8140fdd 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 <> function must have been +NOTE: The `<>` 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 <>. 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 `<>`. +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 -<>. +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 +`<>`. 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 e667455df..4e1c5bf3c 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 -<> +`<>` 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 <>. +may be obtained via `<>`. 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 6e00adc89..4a31d0c89 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 -<> to read the entity +`<>` 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 <>. +obtained via `<>`. 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 d4f65cacb..24daa0b74 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 <> function must have been +NOTE: The `<>` 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 <>. +result may be obtained via `<>`. 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 -<>. +`<>`. 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 f517a9a51..d29af75e2 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 <> function must have been +NOTE: The `<>` 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 <>. +final result may be obtained via `<>`. 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 -<>. +`<>`. 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 <> or -<>. +prior to this with `<>` or +`<>`. 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 -<>. +`<>`. In that case, the body data will be written automatically by the -<> or -<> function. +`<>` or +`<>` 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 2d614206c..faffb3ca2 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 -<> or -<>.) +`<>` or +`<>`.) 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 <>. +may be obtained via `<>`. 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 c8d0077b3..219b771e8 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 -<> or -<>.) +`<>` or +`<>`.) 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 <>. +may be obtained via `<>`. 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 12c6043a0..be6f25682 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 -<>), and +`<>`), and optionally a 'Host' header it can be matched against (see -<>). +`<>`). In some cases, a handler may reference a logical tree rather (directory) rather than just a single element. -(See <>). +(See `<>`). === 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 <> structure. +The function takes a pointer to an `<>` structure. That structure will be passed with the following input values (retrieved with -<>): +`<>`): 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 -<> or -<>) and store that +`<>` or +`<>`) and store that in as the first output (index 0) with -<>. +`<>`. 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 <> function, the +Finally, using the `<>` 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 b179fd341..f1a1a7007 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 -<>. +`<>`. == 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 318919a99..a6be46fb3 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 -<>. +`<>`. 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 d2ae88d01..1ddbb15a0 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 -<> function. +`<>` function. == RETURN VALUES diff --git a/docs/man/nng_http_hijack.3http.adoc b/docs/man/nng_http_hijack.3http.adoc index 61f6d471a..d10bacfca 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 <>.) +(See `<>`.) 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 <>.) +(See `<>`.) 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 d47e112e1..e6eb88449 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 <> if +TIP: See `<>` 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 1e08cea07..5b52dcf24 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 <>. +is sent using `<>`. 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 -<> may be used instead. +`<>` 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 e8fb7bd4c..1161476a2 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 <>. +is sent using `<>`. 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 <>. +see `<>`. 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 b70e16035..4102881ac 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 <> to +TIP: See `<>` 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 8a9c3c1e4..25cd42a39 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 <> function can be used to +TIP: The `<>` 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 851331d6b..cdc325edb 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 <> if +TIP: See `<>` 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 10638ee7a..e54f1ad7b 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 -<> instead. +`<>` 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 5542c441a..3831d45b5 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 <>. +is sent using `<>`. 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 -<> may be used instead. +`<>` 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 053b4cf1d..7251f1cc1 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 -<>. +`<>`. == 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 f519e659f..ac780a242 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 -<>. +consider also including the "`reason phrase`" obtained with +`<>`. == 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 d7ed073bb..ab522ca99 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 <>. +is sent using `<>`. 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 <>. +see `<>`. 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 7e55b605b..4d79739a8 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 <> to +TIP: See `<>` 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 096be3939..fed03c2f6 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 -<>). +`<>`). 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 241497350..b3b9700ce 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 -<>. -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 +`<>`. +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 489489b1f..31285ede0 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 -<> function. +`<>` function. == RETURN VALUES diff --git a/docs/man/nng_http_server_hold.3http.adoc b/docs/man/nng_http_server_hold.3http.adoc index 70929c92b..164a74878 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 -<>. +`<>`. 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 b17e44af6..9f3ab7988 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 -<>. +`<>`. 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 2b200653d..25d26fa5a 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 -<>. +`<>`. If the server is already running (i.e. it has been started with -<>) then this will +`<>`) then this will fail with `NNG_EBUSY`. TIP: Generally, the _cfg_ must have a configured private key, set with -<> or similar. +`<>` or similar. == RETURN VALUES diff --git a/docs/man/nng_inproc.7.adoc b/docs/man/nng_inproc.7.adoc index 363ad705b..987f6b841 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 <> structure, +When using an `<>` structure, the actual structure is of type -<>. +`<>`. === Transport Options diff --git a/docs/man/nng_iov.5.adoc b/docs/man/nng_iov.5.adoc index 63d8b03b9..55c2d19e1 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 <> structure using the -<> function. +an `<>` structure using the +`<>` function. The following structure members are present: diff --git a/docs/man/nng_ipc.7.adoc b/docs/man/nng_ipc.7.adoc index 5a73ce25f..5e711dc2e 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 <> structure, -the actual structure is of type <>. +When using an `<>` structure, +the actual structure is of type `<>`. === Transport Options diff --git a/docs/man/nng_listen.3.adoc b/docs/man/nng_listen.3.adoc index bc4222ab1..6a9e8f6f9 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 -<> object, associated with socket _s_, +`<>` 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 -<> object being created and attached to the socket _s_. +`<>` 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 <> and -<> instead. +using `<>` and +`<>` 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 e7187a61e..6da63f362 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 <> 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 `<>` 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 -<> -or <> functions, and are always "`owned`" -by a single <>. +`<>` +or `<>` functions, and are always "`owned`" +by a single `<>`. 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 <> may have multiple listener +TIP: A given `<>` may have multiple listener objects, multiple <> 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 -<> function. +`<>` 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 cd7f80da1..7ea926c85 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 -<> object, associated with socket _s_, +`<>` 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 <> family of +the `<>` family of functions. Once it is fully configured, the listener may be started using the -<> function. +`<>` function. TIP: If no specific configuration is required, consider using the -simpler <> function instead. +simpler `<>` function instead. == RETURN VALUES diff --git a/docs/man/nng_listener_getopt.3.adoc b/docs/man/nng_listener_getopt.3.adoc index 3fe79868b..14cc6a067 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 <> +This function is used to retrieve an `<>` 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 <> +This string is created from the source using `<>` and consequently must be freed by the caller using -<> when it is no longer needed. +`<>` 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 44404e142..6c3537b0d 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 -<> or -<> functions. +`<>` or +`<>` functions. listeners that are allocated on the stack or statically should be initialized with the macro -<> to ensure that +`<>` 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 d24a4f061..99b74124c 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 <>. +type `<>`. 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 -(<>) +(`<>`) 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 5938e7840..4b3f90831 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 <> object, +Each new connection results in an `<>` 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 3b26bcf04..46aa11da4 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 <> API is a good way to reduce the likelihood of data copies and improve application performance. -Messages are allocated using the <> -function, and are deallocated using the <> +Messages are allocated using the `<>` +function, and are deallocated using the `<>` 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 12701b0f2..f2de29a29 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 -<>, -<>, -any of the <>, -<>, -<>, -or <> variants. +`<>`, +`<>`, +any of the `<>`, +`<>`, +`<>`, +or `<>` variants. == RETURN VALUES diff --git a/docs/man/nng_msg_get_pipe.3.adoc b/docs/man/nng_msg_get_pipe.3.adoc index 4a38c9ff1..e12a956c1 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 <> object +The `nng_msg_get_pipe()` returns the `<>` 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 <> function +The `<>` 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 053ea8497..b4679b0cf 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 -<> option.) +`<>` 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 59c2a2da1..b1308fff0 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 -<> to reduce the message size +`<>` 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 <> +needs to grow due to this function or `<>` 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 54aacd37b..8ea4bdd67 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 <>. +owner releases it with `<>`. 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 281a3f1e1..996908d3c 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 <>. +was previously acquired via `<>`. 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 9db3d660d..4850730d3 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 (<> objects) use the functions -<> -and <> to set and retrieve option values. +Sockets (`<>` objects) use the functions +`<>` +and `<>` to set and retrieve option values. -Dialers (<> objects) use the functions -<> and -<> to set and retrieve option +Dialers (`<>` objects) use the functions +`<>` and +`<>` to set and retrieve option values. -Listeners (<> objects) use the functions -<> -and <> to set and +Listeners (`<>` objects) use the functions +`<>` +and `<>` to set and retrieve option values. -Pipes (<> objects) can only retrieve option values using -the <> function. +Pipes (`<>` objects) can only retrieve option values using +the `<>` 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 <>) with polling functions, +type `<>`) 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 <>. +objects instead. See `<>`. [[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 <>) with polling functions, +type `<>`) 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 <>. +objects instead. See `<>`. [[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 -<>). +`<>`). 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 f03a4a5f4..3d070d00c 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 <> functions create _pair_ socket. +The `<>` 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 <>) or raw mode sockets -(see <>) where +_devices_ (see `<>`) or raw mode sockets +(see `<>`) where messages may be discarded. Applications that require reliable delivery semantics should consider using <> 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 <>. +used with `<>`. 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 -<> to use for the outgoing message with -the <> function. +`<>` to use for the outgoing message with +the `<>` function. Most often the value of the outgoing pipe will be obtained from an incoming -message using the <> function, +message using the `<>` 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. -<>:: +`<>`:: (`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 -<> option to guard against +`<>` 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 a7423884b..a777c0d03 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 (<> objects) -and listeners (<> objects), which can be +Pipe objects are created by dialers (`<>` objects) +and listeners (`<>` objects), which can be thought of as "`owning`" the pipe. Pipe objects may be destroyed by the -<> function. +`<>` 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 2128caec2..5e8cb8512 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 -<> option. +`<>` 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 66216a735..64cad9a37 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 -<> or -<> +`<>` or +`<>`. 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 -(<>) in milliseconds, which are stored in +(`<>`) 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 <> +This function is used to retrieve an `<>` into _sap_. ==== `nng_pipe_getopt_string()` This function is used to retrieve a string into _strp_. -This string is created from the source using <> +This string is created from the source using `<>` and consequently must be freed by the caller using -<> when it is no longer needed. +`<>` 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 b327dac2c..19eed4f6b 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 -<> 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 -<> to ensure that -they cannot be confused with a valid pipe before they are opened. +`<>` 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 e45201b79..6aec8c9e0 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 <> functions create a publisher socket. +The `<>` 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 c57515c5a..59607e7e9 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 <> functions create a puller socket. +The `<>` 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 e2ab50ab7..800c0bd6a 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 <> call creates a pusher socket. +The `<>` 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 47ce4cbe7..5ab180f06 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 <>), fill it with +(as if by `<>`), 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 -<> or reusing the message for sending (with the same -size) in a call to <>. +`<>` or reusing the message for sending (with the same +size) in a call to `<>`. 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 7e30996c4..774577bf0 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 <> using the When a message is successfully received by the socket, it is stored in the _aio_ by an internal call equivalent to -<>, then the completion +`<>`, then the completion callback on the _aio_ is executed. -In this case, <> will +In this case, `<>` 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 <> will be non-zero. +but `<>` 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 <> socket the data is broadcast, so that any peers who have a suitable subscription will be able to receive it using -<> or a similar function.) +`<>` or a similar function.) Furthermore, some protocols may not support receiving (such as <>) or may require other conditions. (For example, <> sockets cannot normally receive data, which diff --git a/docs/man/nng_recvmsg.3.adoc b/docs/man/nng_recvmsg.3.adoc index c2276511b..abe7c7230 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 <> function. +offer more functionality than the simpler `<>` 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 789b515d6..962056be8 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 <> functions create a replier socket. +The `<>` 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 <> for concurrent -use cases using <>. +use cases using `<>`. 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 221023c41..282c1db5a 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 -<>), +`<>`), and it will generally attempt to spread work requests to different peer repliers. -TIP: This property, when combined with <> +TIP: This property, when combined with `<>` 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 <> functions create a requester socket. +The `<>` 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 <> for concurrent -use cases using <>. +use cases using `<>`. + 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 (`<>`) + 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 -<>), the forwarding node prepends a +`<>`), 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 b2060d8eb..b03fa75f7 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 <> functions create a +The `<>` 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 <>) +Raw mode sockets (set with `<>`) ignore all these restrictions. === Context Operations This protocol supports the creation of <> for concurrent -use cases using <>. +use cases using `<>`. 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 22e09a80b..7a1ed0fbb 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 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 <> socket the data is broadcast, so that any peers who have a suitable subscription will be able to receive it using -<> or a similar function.) +`<>` or a similar function.) Furthermore, some protocols may not support sending data (such as <>) or may require other conditions. (For example, <> 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 <>, or was - obtained from a call to <> with + The _data_ was allocated using `<>`, or was + obtained from a call to `<>` 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 - <> when it is no longer needed. + `<>` 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 bb1100158..47f9df147 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 <> using the <> _s_ asynchronously. The message to send must have previously been set on the _aio_ -using the <> function. +using the `<>` 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 <> +then the _aio_ will be completed, and `<>` 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 <> +then the _aio_ callback will be executed and +`<>` will return a non-zero error status. In this case, the callback has a responsibity to retrieve the message from -the _aio_ with <> and dispose of -it appropriately. +the _aio_ with +`<>` and dispose of it appropriately. (This may include retrying the send operation on the same or a different -socket, or deallocating the message with <>.) +socket, or deallocating the message with `<>`.) 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 <> socket the data is broadcast, so that any peers who have a suitable subscription will be able to receive it using -<> or a similar function.) +`<>` or a similar function.) Furthermore, some protocols may not support sending (such as <>) or may require other conditions. (For example, <> sockets cannot normally send data, which diff --git a/docs/man/nng_sendmsg.3.adoc b/docs/man/nng_sendmsg.3.adoc index e6d653b34..dffb042f1 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 <> function. +offer more functionality than the simpler `<>` 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 <> socket the data is broadcast, so that any peers who have a suitable subscription will be able to receive it using -<> or a similar function.) +`<>` or a similar function.) Furthermore, some protocols may not support sending (such as <>) or may require other conditions. (For example, <> sockets cannot normally send data, which diff --git a/docs/man/nng_setopt.3.adoc b/docs/man/nng_setopt.3.adoc index 91e542252..d54b7f270 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 <>. +type `<>`. 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 -(<>) +(`<>`) 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 280d0422c..c243d6bc2 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 -<>, and it is shorter +`<>`, 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 3d7b4fc2b..595f31169 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 <> -than of <>. +instances of `<>` +than of `<>`. The naming confusion is unfortunate. **** diff --git a/docs/man/nng_sockaddr_in.5.adoc b/docs/man/nng_sockaddr_in.5.adoc index 94fa18be5..5dcc02c60 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 <> +An `nng_sockaddr_in` is the flavor of `<>` 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, <>, is used +A different structure, `<>`, 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 95e6ec8cc..6ac809ba7 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 <> +An `nng_sockaddr_in6` is the flavor of `<>` 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, <>, is used +A different structure, `<>`, 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 b65c3abed..c7901c63a 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 <> +An `nng_sockaddr_inproc` is the flavor of `<>` used to represent addresses associated with intra-process communication using the <> transport. diff --git a/docs/man/nng_sockaddr_ipc.5.adoc b/docs/man/nng_sockaddr_ipc.5.adoc index 3003d51ee..3fac561b9 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 <> +An `nng_sockaddr_ipc` is the flavor of `<>` used to represent addresses associated with IPC communication using the <> transport. diff --git a/docs/man/nng_sockaddr_zt.5.adoc b/docs/man/nng_sockaddr_zt.5.adoc index 0ff362764..e601e9745 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 <> +An `nng_sockaddr_zt` is the flavor of `<>` used to represent ZeroTier addresses, including the (((port number, ZeroTier)))port number used by the <> transport. diff --git a/docs/man/nng_socket.5.adoc b/docs/man/nng_socket.5.adoc index 2d8d72564..35a6a3c6c 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 (<>) -and/or (<>), and multiple -pipes (<>), and +A given socket can have multiple dialers (`<>`) +and/or listeners (`<>`), and multiple +pipes (`<>`), 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 -<>. +`<>`. When the socket is no longer needed, it can be closed with -<>. +`<>`. [[NNG_SOCKET_INITIALIZER]] === Initialization diff --git a/docs/man/nng_socket_id.3.adoc b/docs/man/nng_socket_id.3.adoc index b5acc98b3..e9379a6b1 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 <> function. +constructor, such as the `<>` function. Sockets that are allocated on the stack or statically should be initialized with the macro -<> to ensure that +`<>` 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 23e23a439..6efacc373 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 <> +This is logically equiavlent to using `<>` 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 -<>, or may be deallocated using the -<> using the length of the returned string plus +`<>`, or may be deallocated using the +`<>` 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 2e6569a8c..9b91306fd 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 <> with +This is equivalent to using `<>` 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 <> or -<>. +by `<>` or +`<>`. 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 -<> is modified to be shorter, then +`<>` is modified to be shorter, then it is incorrect to call this function. -(The <> function can be used instead in that +(The `<>` 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 18606f2bc..904f844ee 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 <> functions create a subscriber socket. +The `<>` 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 7a8d20737..699367489 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 <> +The `<>` 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 <> for concurrent -use cases using <>. +use cases using `<>`. 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 <> + This read/write option is an `<>` 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 -<>), the forwarding node prepends a +`<>`), 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 1d925b79b..aa90364e6 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 <> structure, +When using an `<>` structure, the actual structure is either of type -<> (for IPv4) or -<> (for IPv6). +`<>` (for IPv4) or +`<>` (for IPv6). === Transport Options diff --git a/docs/man/nng_thread_create.3supp.adoc b/docs/man/nng_thread_create.3supp.adoc index 359dabab2..b458cf96b 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 -<> +`<>` 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 <> structures. +an asynchronous model using `<>` structures. TIP: Threads can be synchronized using <> and diff --git a/docs/man/nng_tls.7.adoc b/docs/man/nng_tls.7.adoc index c783f739d..249159b7e 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 -<>. +`<>`. === Availability @@ -100,10 +100,10 @@ The entire URI must be less than `NNG_MAXADDRLEN` bytes long. === Socket Address -When using an <> structure, +When using an `<>` structure, the actual structure is either of type -<> (for IPv4) or -<> (for IPv6). +`<>` (for IPv4) or +`<>` (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 <> for more +See `<>` 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 <> for more +See `<>` 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 <> for +See `<>` for more details. ((`NNG_OPT_TLS_VERIFIED`)):: diff --git a/docs/man/nng_ws.7.adoc b/docs/man/nng_ws.7.adoc index d3b68b993..bc0d9d512 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 <>. +register the transport by calling `<>`. 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 <> function. +the `<>` function. === URI Format @@ -82,10 +82,10 @@ permitted, with IPv4 addresses mapped to IPv6 addresses.) === Socket Address -When using an <> structure, +When using an `<>` structure, the actual structure is either of type -<> (for IPv4) or -<> (for IPv6). +`<>` (for IPv4) or +`<>` (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 <> for more +See `<>` 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 <> for more +See `<>` 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 <> for more +See `<>` for more details. `NNG_OPT_TLS_VERIFIED`:: diff --git a/docs/man/nng_zerotier.7.adoc b/docs/man/nng_zerotier.7.adoc index c26f1f50f..6325bbb3e 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 -<>. +`<>`. 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 -<> function. +`<>` function. === Socket Address -When using an <> structure, +When using an `<>` structure, the actual structure is of type -<>. +`<>`. === 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 <> (msec), + This is an `<>` (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 <> (msec). + is still alive. This is an `<>` (msec). [[NNG_OPT_ZT_PING_TRIES]] ((`NNG_OPT_ZT_PING_TRIES`))::