From d4b0c0d34aef41236c5ac2f9e8b4b0ae8a6d0a8c Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Thu, 5 Jul 2018 12:51:47 -0700 Subject: man page updates for tip --- man/tip/index.html | 12 + man/tip/libnng.3.html | 12 + man/tip/nng_close.3.html | 18 + man/tip/nng_http_req_copy_data.3http.html | 2 +- man/tip/nng_http_req_set_data.3http.html | 2 +- man/tip/nng_http_res_copy_data.3http.html | 2 +- man/tip/nng_http_res_set_data.3http.html | 2 +- man/tip/nng_http_server_res_error.3http.html | 609 ++++++++++++++++++++ man/tip/nng_http_server_set_error_file.3http.html | 652 ++++++++++++++++++++++ man/tip/nng_http_server_set_error_page.3http.html | 625 +++++++++++++++++++++ man/tip/nng_ipc.7.html | 30 +- man/tip/nng_recv.3.html | 46 +- man/tip/nng_recvmsg.3.html | 14 +- man/tip/nng_send.3.html | 10 +- man/tip/nng_sendmsg.3.html | 10 +- man/tip/nng_tls_config_alloc.3tls.html | 2 +- man/tip/nng_tls_config_auth_mode.3tls.html | 2 +- man/tip/nng_tls_config_ca_chain.3tls.html | 2 +- man/tip/nng_tls_config_ca_file.3tls.html | 2 +- man/tip/nng_tls_config_cert_key_file.3tls.html | 2 +- man/tip/nng_tls_config_free.3tls.html | 2 +- man/tip/nng_tls_config_own_cert.3tls.html | 2 +- man/tip/nng_tls_config_server_name.3tls.html | 2 +- man/tip/nng_zerotier.7.html | 9 +- 24 files changed, 2024 insertions(+), 47 deletions(-) create mode 100644 man/tip/nng_http_server_res_error.3http.html create mode 100644 man/tip/nng_http_server_set_error_file.3http.html create mode 100644 man/tip/nng_http_server_set_error_page.3http.html (limited to 'man') diff --git a/man/tip/index.html b/man/tip/index.html index 5faa5639..0d29a10b 100644 --- a/man/tip/index.html +++ b/man/tip/index.html @@ -1290,6 +1290,18 @@ Protocols sockets.

release HTTP server instance

+

nng_http_server_res_error(3http)

+

use HTTP server error page

+ + +

nng_http_server_set_error_file(3http)

+

set custom HTTP error file

+ + +

nng_http_server_set_error_page(3http)

+

set custom HTTP error page

+ +

nng_http_server_set_tls(3http)

set HTTP server TLS configuration

diff --git a/man/tip/libnng.3.html b/man/tip/libnng.3.html index 99be7012..c8be729e 100644 --- a/man/tip/libnng.3.html +++ b/man/tip/libnng.3.html @@ -1516,10 +1516,22 @@ and connections.

release HTTP server instance

+

nng_http_server_set_error_file()

+

set custom HTTP error file

+ + +

nng_http_server_set_error_page()

+

set custom HTTP error page

+ +

nng_http_server_set_tls()

set HTTP server TLS configuration

+

nng_http_server_res_error()

+

use HTTP server error page

+ +

nng_http_server_start()

start HTTP server

diff --git a/man/tip/nng_close.3.html b/man/tip/nng_close.3.html index 90d166f1..3670e299 100644 --- a/man/tip/nng_close.3.html +++ b/man/tip/nng_close.3.html @@ -547,6 +547,24 @@ in NNG_ECLOSED. Threads waiting for operations on the socket when this call is executed may also return with an NNG_ECLOSED result.

+
+ + + + + +
+ + +Closing the socket while data is in transmission will likely lead to loss +of that data. +There is no automatic linger or flush to ensure that the socket send buffers +have completely transmitted. +It is recommended to wait a brief period after calling +nng_send() or similar functions, before calling this +function. +
+
diff --git a/man/tip/nng_http_req_copy_data.3http.html b/man/tip/nng_http_req_copy_data.3http.html index 41acf6c9..43b44ae1 100644 --- a/man/tip/nng_http_req_copy_data.3http.html +++ b/man/tip/nng_http_req_copy_data.3http.html @@ -543,7 +543,7 @@ 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 nni_http_conn_write_req().

+is sent using nng_http_conn_write_req().

This also updates the relevant Content-Length header of req.

diff --git a/man/tip/nng_http_req_set_data.3http.html b/man/tip/nng_http_req_set_data.3http.html index dbd495b7..d03fea22 100644 --- a/man/tip/nng_http_req_set_data.3http.html +++ b/man/tip/nng_http_req_set_data.3http.html @@ -540,7 +540,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b

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 nni_http_conn_write_req().

+is sent using nng_http_conn_write_req().

This also updates the relevant Content-Length header of req.

diff --git a/man/tip/nng_http_res_copy_data.3http.html b/man/tip/nng_http_res_copy_data.3http.html index 6cb1cb0a..c971d88f 100644 --- a/man/tip/nng_http_res_copy_data.3http.html +++ b/man/tip/nng_http_res_copy_data.3http.html @@ -543,7 +543,7 @@ 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 nni_http_conn_write_res().

+is sent using nng_http_conn_write_res().

This also updates the relevant Content-Length header of res.

diff --git a/man/tip/nng_http_res_set_data.3http.html b/man/tip/nng_http_res_set_data.3http.html index 5199126e..daec09c2 100644 --- a/man/tip/nng_http_res_set_data.3http.html +++ b/man/tip/nng_http_res_set_data.3http.html @@ -540,7 +540,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b

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 nni_http_conn_write_res().

+is sent using nng_http_conn_write_res().

This also updates the relevant Content-Length header of res.

diff --git a/man/tip/nng_http_server_res_error.3http.html b/man/tip/nng_http_server_res_error.3http.html new file mode 100644 index 00000000..1541ee1f --- /dev/null +++ b/man/tip/nng_http_server_res_error.3http.html @@ -0,0 +1,609 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_http_server_res_error(3http) + + + + + + + +
+
+

SYNOPSIS

+
+
+
+
#include <nng/nng.h>
+#include <nng/supplemental/http/http.h>
+
+int nng_http_server_set_error_file(nng_http_server *server,
+        nng_http_res *response);
+
+
+
+
+
+

DESCRIPTION

+
+
+

The nng_http_server_res_error() sets the body of response +to server's error page, which may have been customized using the +nng_http_server_error_file() +or +nng_http_server_error_page() +functions.

+
+
+

The status code of the response should have already been set, either +implicitly by allocating it with +nng_http_res_alloc_error(), +or by calling +nng_http_res_set_status().

+
+
+

Any content body previously set for response will be overridden by +this function.

+
+
+
+
+

RETURN VALUES

+
+
+

This function returns 0 on success, and non-zero otherwise.

+
+
+
+
+

ERRORS

+
+
+ + + + + + + + + +
+NNG_ENOMEM + +

Insufficient free memory exists.

+
+NNG_ENOTSUP + +

HTTP not supported.

+
+
+
+
+ +
+ + diff --git a/man/tip/nng_http_server_set_error_file.3http.html b/man/tip/nng_http_server_set_error_file.3http.html new file mode 100644 index 00000000..a195ab49 --- /dev/null +++ b/man/tip/nng_http_server_set_error_file.3http.html @@ -0,0 +1,652 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_http_server_set_error_file(3http) + + + + + + + +
+
+

SYNOPSIS

+
+
+
+
#include <nng/nng.h>
+#include <nng/supplemental/http/http.h>
+
+int nng_http_server_set_error_file(nng_http_server *server,
+        uint16_t code, const char *path);
+
+
+
+
+
+

DESCRIPTION

+
+
+

The nng_http_server_set_error_file() sets an error page to be used +for HTTP status code on the server instance server. +The body content of the HTTP responses will contain the file contents of +the file located at path, which should be an HTML file.

+
+
+

The custom HTML content will be used when the server is returning an +internally generated error response, or is returning an error response +that was allocated with the +nng_http_res_alloc_error() +function. +This HTML content will also be used if the application calls the +nng_http_server_res_error(). +The last custom error page set for code by either this function or +nng_http_server_error_page() +will be used.

+
+
+ + + + + +
+ + +Error responses that have their body content changed after allocation, +or that are written directly by the application, will not use the body +content supplied here. +
+
+
+ + + + + +
+ + +The file contents of path are read when this function is called. +Therefore, if the file contents are changed, then this function should +be called again to update the error page. +
+
+
+
+
+

RETURN VALUES

+
+
+

This function returns 0 on success, and non-zero otherwise.

+
+
+
+
+

ERRORS

+
+
+ + + + + + + + + + + + + + + + + +
+NNG_ENOENT + +

The file named by path does not exist.

+
+NNG_EPERM + +

No permission to read the file named by path.

+
+NNG_ENOMEM + +

Insufficient free memory exists.

+
+NNG_ENOTSUP + +

HTTP not supported.

+
+
+
+
+ +
+ + diff --git a/man/tip/nng_http_server_set_error_page.3http.html b/man/tip/nng_http_server_set_error_page.3http.html new file mode 100644 index 00000000..0fcce208 --- /dev/null +++ b/man/tip/nng_http_server_set_error_page.3http.html @@ -0,0 +1,625 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_http_server_set_error_page(3http) + + + + + + + +
+
+

SYNOPSIS

+
+
+
+
#include <nng/nng.h>
+#include <nng/supplemental/http/http.h>
+
+int nng_http_server_set_error_page(nng_http_server *server,
+        uint16_t code, const char *html);
+
+
+
+
+
+

DESCRIPTION

+
+
+

The nng_http_server_set_error_page() sets an error page to be used +for HTTP status code on the server instance server. +The body content of the HTTP responses will contain html.

+
+
+

The custom HTML content will be used when the server is returning an +internally generated error response, or is returning an error response +that was allocated with the +nng_http_res_alloc_error() +function. +This HTML content will also be used if the application calls the +nng_http_server_res_error(). +The last custom error page set for code by either this function or +nng_http_server_error_file() +will be used.

+
+
+ + + + + +
+ + +Error responses that have their body content changed after allocation, +or that are written directly by the application, will not use the body +content supplied here. +
+
+
+

The supplied HTML content is copied by this function, and may be reused +after this function returns.

+
+
+
+
+

RETURN VALUES

+
+
+

This function returns 0 on success, and non-zero otherwise.

+
+
+
+
+

ERRORS

+
+
+ + + + + + + + + +
+NNG_ENOMEM + +

Insufficient free memory exists.

+
+NNG_ENOTSUP + +

HTTP not supported.

+
+
+
+
+ +
+ + diff --git a/man/tip/nng_ipc.7.html b/man/tip/nng_ipc.7.html index fe582579..bf3c991d 100644 --- a/man/tip/nng_ipc.7.html +++ b/man/tip/nng_ipc.7.html @@ -559,9 +559,8 @@ no extra steps to use it should be necessary.

URI Format

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

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

@@ -571,9 +570,10 @@ should be created.

On Windows, all names are prefixed by \\.\pipe\ and do not -occupy the normal file system. -On POSIX platforms, the path is taken literally, -and is relative to the root directory. +reside in the normal file system. +On POSIX platforms, the path is taken literally, and is relative to +the current directory, unless it begins with /, in which case it is +relative to the root directory.
@@ -585,11 +585,12 @@ and is relative to the root directory. -If compatibility with legacy nanomsg applications is required, -then pathnames must not be longer than 122 bytes, including the final -NUL byte. -This is because legacy versions of nanomsg cannot express URLs -longer than 128 bytes, including the ipc:// prefix. +When using relative paths on POSIX systems, the address used and returned +in properties like NNG_OPT_LOCADDR and NNG_OPT_URL will also be relative. +Consequently, they will only be interpreted the same by processes that have +the same working directory. +To ensure maximum portability and safety, absolute paths are recommended +whenever possible. @@ -601,8 +602,11 @@ longer than 128 bytes, including the ipc:// prefix. -Legacy nanomsg supported relative IPC path names; modern nng does not. -Therefore, always use an absolute path name if interoperability is required. +If compatibility with legacy nanomsg applications is required, +then pathnames must not be longer than 122 bytes, including the final +NUL byte. +This is because legacy versions of nanomsg cannot express URLs +longer than 128 bytes, including the ipc:// prefix. diff --git a/man/tip/nng_recv.3.html b/man/tip/nng_recv.3.html index 487257cf..099eef9c 100644 --- a/man/tip/nng_recv.3.html +++ b/man/tip/nng_recv.3.html @@ -539,15 +539,19 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b

The nng_recv() receives a message.

-

If the special flag NNG_FLAG_ALLOC is not specified, then the caller must -set data to a buffer to receive the message body content, and must store -the size of that buffer at the location pointed to by sizep. -When the function returns, if it is successful, the size at sizep will be -updated with the actual message body length copied into data.

+

The flags is a bit mask that may contain any of the following values:

-
-

If the special flag NNG_FLAG_ALLOC is present, then a “zero-copy” -mode is used. +

+
+
NNG_FLAG_NONBLOCK
+
+

The function returns immediately, even if no message is available. +Without this flag, the function will wait until a message is received +by the socket s, or any configured timer expires.

+
+
NNG_FLAG_ALLOC
+
+

If this flag is present, then a “zero-copy” mode is used. 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. @@ -555,10 +559,18 @@ The function will then allocate a message buffer (as if by nng_alloc()), fill it with the message body, and store it at the address referenced by data, and update the size referenced by sizep. -When this flag is present, the caller assumes -responsibility for disposing of the received buffer either by the function -nng_free() or reusing the message for sending (with the same -size) in a call to nng_send().

+The caller is responsible for disposing of the received buffer either by +the nng_free() function or passing the message (also +with the NNG_FLAG_ALLOC flag) in a call to nng_send().

+
+
+
+
+

If the special flag NNG_FLAG_ALLOC (see above) is not specified, then the +caller must set data to a buffer to receive the message body content, +and must store the size of that buffer at the location pointed to by sizep. +When the function returns, if it is successful, the size at sizep will be +updated with the actual message body length copied into data.

@@ -612,7 +624,7 @@ a response using the same flag. NNG_EAGAIN @@ -663,6 +675,14 @@ a response using the same flag.

The socket s cannot receive data in this state.

+ + + +
-

The socket s cannot accept data for sending.

+

The operation would block, but NNG_FLAG_NONBLOCK was specified.

+NNG_ETIMEDOUT + +

The operation timed out.

+
diff --git a/man/tip/nng_recvmsg.3.html b/man/tip/nng_recvmsg.3.html index 47b1278f..d953ca01 100644 --- a/man/tip/nng_recvmsg.3.html +++ b/man/tip/nng_recvmsg.3.html @@ -560,8 +560,8 @@ offer more functionality than the simpler nng_re
NNG_FLAG_NONBLOCK

The function returns immediately, even if no message is available. -Without this flag, the function will wait until a message is received -by the socket s, or any configured timer expires.

+Without this flag, the function will wait until a message is received +by the socket s, or any configured timer expires.

@@ -603,7 +603,7 @@ Furthermore, some protocols may not support receiving data at all, such as NNG_EAGAIN -

The socket s cannot accept data for sending.

+

The operation would block, but NNG_FLAG_NONBLOCK was specified.

@@ -646,6 +646,14 @@ Furthermore, some protocols may not support receiving data at all, such as

The socket s cannot receive data in this state.

+ + +NNG_ETIMEDOUT + + +

The operation timed out.

+ + diff --git a/man/tip/nng_send.3.html b/man/tip/nng_send.3.html index 1b1bafee..035f4283 100644 --- a/man/tip/nng_send.3.html +++ b/man/tip/nng_send.3.html @@ -651,7 +651,7 @@ or trans-dimensional mutation of the program’s author. NNG_EAGAIN -

The socket s cannot accept data for sending.

+

The operation would block, but NNG_FLAG_NONBLOCK was specified.

@@ -702,6 +702,14 @@ or trans-dimensional mutation of the program’s author.

The socket s cannot send data in this state.

+ + +NNG_ETIMEDOUT + + +

The operation timed out.

+ + diff --git a/man/tip/nng_sendmsg.3.html b/man/tip/nng_sendmsg.3.html index d9c57e00..39817fa9 100644 --- a/man/tip/nng_sendmsg.3.html +++ b/man/tip/nng_sendmsg.3.html @@ -635,7 +635,7 @@ such as with
pub sockets, which are best-e NNG_EAGAIN -

The socket s cannot accept data for sending.

+

The operation would block, but NNG_FLAG_NONBLOCK was specified.

@@ -686,6 +686,14 @@ such as with pub sockets, which are best-e

The socket s cannot send data in this state.

+ + +NNG_ETIMEDOUT + + +

The operation timed out.

+ + diff --git a/man/tip/nng_tls_config_alloc.3tls.html b/man/tip/nng_tls_config_alloc.3tls.html index 397465f9..9a2cf0f3 100644 --- a/man/tip/nng_tls_config_alloc.3tls.html +++ b/man/tip/nng_tls_config_alloc.3tls.html @@ -533,7 +533,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b NNG_TLS_MODE_SERVER } nng_tls_mode; -int nng_tls_config_alloc(nni_tls_config **cfgp, nng_tls_mode mode);
+int nng_tls_config_alloc(nng_tls_config **cfgp, nng_tls_mode mode); diff --git a/man/tip/nng_tls_config_auth_mode.3tls.html b/man/tip/nng_tls_config_auth_mode.3tls.html index f7244049..87bc24af 100644 --- a/man/tip/nng_tls_config_auth_mode.3tls.html +++ b/man/tip/nng_tls_config_auth_mode.3tls.html @@ -534,7 +534,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b NNG_TLS_AUTH_MODE_REQUIRED } nng_tls_auth_mode; -int nng_tls_config_auth_mode(nni_tls_config *cfg, nng_tls_auth_mode mode); +int nng_tls_config_auth_mode(nng_tls_config *cfg, nng_tls_auth_mode mode); diff --git a/man/tip/nng_tls_config_ca_chain.3tls.html b/man/tip/nng_tls_config_ca_chain.3tls.html index 6fbfb530..37e00d40 100644 --- a/man/tip/nng_tls_config_ca_chain.3tls.html +++ b/man/tip/nng_tls_config_ca_chain.3tls.html @@ -528,7 +528,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
#include <nng/nng.h>
 #include <nng/supplemental/tls/tls.h>
 
-int nng_tls_config_ca_cert(nni_tls_config *cfg, const char *chain,
+int nng_tls_config_ca_cert(nng_tls_config *cfg, const char *chain,
     const char *crl);
diff --git a/man/tip/nng_tls_config_ca_file.3tls.html b/man/tip/nng_tls_config_ca_file.3tls.html index ec00a725..e4182e5b 100644 --- a/man/tip/nng_tls_config_ca_file.3tls.html +++ b/man/tip/nng_tls_config_ca_file.3tls.html @@ -528,7 +528,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
#include <nng/nng.h>
 #include <nng/supplemental/tls/tls.h>
 
-int nng_tls_config_ca_file(nni_tls_config *cfg, const char *path);
+int nng_tls_config_ca_file(nng_tls_config *cfg, const char *path); diff --git a/man/tip/nng_tls_config_cert_key_file.3tls.html b/man/tip/nng_tls_config_cert_key_file.3tls.html index dd08454a..2f8c9640 100644 --- a/man/tip/nng_tls_config_cert_key_file.3tls.html +++ b/man/tip/nng_tls_config_cert_key_file.3tls.html @@ -528,7 +528,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
#include <nng/nng.h>
 #include <nng/supplemental/tls/tls.h>
 
-int nng_tls_config_cert_key_file(nni_tls_config *cfg, const char *path,
+int nng_tls_config_cert_key_file(nng_tls_config *cfg, const char *path,
     const char *pass);
diff --git a/man/tip/nng_tls_config_free.3tls.html b/man/tip/nng_tls_config_free.3tls.html index 477a8a83..7708f0fb 100644 --- a/man/tip/nng_tls_config_free.3tls.html +++ b/man/tip/nng_tls_config_free.3tls.html @@ -528,7 +528,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
#include <nng/nng.h>
 #include <nng/supplemental/tls/tls.h>
 
-void nng_tls_config_free(nni_tls_config *cfg);
+void nng_tls_config_free(nng_tls_config *cfg); diff --git a/man/tip/nng_tls_config_own_cert.3tls.html b/man/tip/nng_tls_config_own_cert.3tls.html index 1fe4cc79..d5209a02 100644 --- a/man/tip/nng_tls_config_own_cert.3tls.html +++ b/man/tip/nng_tls_config_own_cert.3tls.html @@ -528,7 +528,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
#include <nng/nng.h>
 #include <nng/supplemental/tls/tls.h>
 
-int nng_tls_config_own_cert(nni_tls_config *cfg, const char *cert,
+int nng_tls_config_own_cert(nng_tls_config *cfg, const char *cert,
     const char *key, const char *pass);
diff --git a/man/tip/nng_tls_config_server_name.3tls.html b/man/tip/nng_tls_config_server_name.3tls.html index 8dc8ca8d..3002f135 100644 --- a/man/tip/nng_tls_config_server_name.3tls.html +++ b/man/tip/nng_tls_config_server_name.3tls.html @@ -528,7 +528,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
#include <nng/nng.h>
 #include <nng/supplemental/tls/tls.h>
 
-int nng_tls_config_server_name(nni_tls_config *cfg, const char *name);
+int nng_tls_config_server_name(nng_tls_config *cfg, const char *name); diff --git a/man/tip/nng_zerotier.7.html b/man/tip/nng_zerotier.7.html index c458c513..0a8dda54 100644 --- a/man/tip/nng_zerotier.7.html +++ b/man/tip/nng_zerotier.7.html @@ -555,10 +555,11 @@ using a Virtual Layer 2 packet facility.

-This transport is very experimental. To utilize it at -present, the library must be built with support, and the -ZeroTierOne dev branch must be included; this will require -linking against a suitable libzerotiercore static library. +This transport is experimental. +To utilize it at present, the library must be built with support, and linked +against a suitable libzerotiercore library. +Further information about building with this support are in the build +documentation included with the distribution. -- cgit v1.2.3-70-g09d2