diff options
Diffstat (limited to 'docs/nng.adoc')
| -rw-r--r-- | docs/nng.adoc | 95 |
1 files changed, 42 insertions, 53 deletions
diff --git a/docs/nng.adoc b/docs/nng.adoc index 2da365de..62482d09 100644 --- a/docs/nng.adoc +++ b/docs/nng.adoc @@ -1,9 +1,7 @@ -nng(7) -====== += nng(7) :doctype: manpage :manmanual: nng :mansource: nng -:icons: font :copyright: Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> \ Copyright 2018 Capitar IT Group BV <info@capitar.com> \ This software is supplied under the terms of the MIT License, a \ @@ -11,17 +9,14 @@ nng(7) file was obtained (LICENSE.txt). A copy of the license may also \ be found online at https://opensource.org/licenses/MIT. -NAME ----- +== NAME nng - nanomsg next generation -SYNOPSIS --------- +== SYNOPSIS *cc* ['flags'] 'files' *-lnng* ['libraries'] -DESCRIPTION ------------ +== DESCRIPTION The _nng_ library provides a common messaging framework intended to solve common communication problems in distributed applications. @@ -53,40 +48,7 @@ application developer to use the new-style API. The _nng_ library is implemented in pure C; if you need bindings for other languages please check the http://nanomsg.org/[website]. -URLs -~~~~ - -The _nng_ library uses universal resource locators (URLs) -following the format specified in -https://tools.ietf.org/html/rfc3986[RFC 3986], -including some schemes that are unique -to SP. -The URLs used in _nng_ are canonicalized as follows, mostly in -accordance with -https://tools.ietf.org/html/rfc3986#section-6.2.2[RFC 3986 6.2.2]: - - 1. The URL is parsed into scheme, userinfo, host, port, path, query and - fragment components. (Not all of these members are necessarily present.) - 2. The scheme, hostname, and port if present, are converted to lower case. - 3. Percent-encoded values for - https://tools.ietf.org/html/rfc3986#section-2.3[unreserved characters] - converted to their unencoded forms. - 4. Additionally URL percent-encoded values for characters in the path - and with numeric values larger than 127 (i.e. not ASCII) are decoded. - 5. The resulting path is checked for invalid UTF-8 sequences, consisting - of surrogate pairs, illegal byte sequences, or overlong encodings. - If this check fails, then the entire URL is considered invalid. - 6. Path segments consisting of `.` and `..` are resolved as per - https://tools.ietf.org/html/rfc3986#section-6.2.2.3[RFC 3986 6.2.2.3]. - 7. Further, empty path segments are removed, meaning that duplicate - slash (`/`) separators are removed from the path. - -Note that steps 4, 5, and 7 are not specified by RFC 3986, but performing -them is believed to improve both the usability and security of _nng_ -applications, without violating RFC 3986 itself. - -Protocols -~~~~~~~~~ +== Protocols * <<nng_bus#,nng_bus(7)>> - Bus protocol * <<nng_pair#,nng_pair(7)>> - Pair protocol @@ -99,8 +61,7 @@ Protocols * <<nng_respondent#,nng_respondent(7)>> - Respondent side of survey protocol * <<nng_surveyor#,nng_surveyor(7)>> - Surveyor side of survey protocol -Transports -~~~~~~~~~~ +== Transports * <<nng_inproc#,nng_inproc(7)>> - Intra-process transport * <<nng_ipc#,nng_ipc(7)>> - Inter-process transport @@ -109,8 +70,7 @@ Transports * <<nng_ws#,nng_ws(7)>> - WebSocket transport * <<nng_zerotier#,nng_zerotier(7)>> - ZeroTier transport -Conceptual Overview -~~~~~~~~~~~~~~~~~~~ +== Conceptual Overview _nng_ presents a _socket_ view of networking. The sockets are constructed using protocol-specific functions, as a given socket implements precisely @@ -152,18 +112,47 @@ Most applications should not have to worry about endpoints or pipes at all; the socket abstraction should provide all the functionality needed other than in a few specific circumstances. -API -~~~ +=== URLs + +The _nng_ library uses universal resource locators (URLs) +following the format specified in +https://tools.ietf.org/html/rfc3986[RFC 3986], +including some schemes that are unique +to SP. +The URLs used in _nng_ are canonicalized as follows, mostly in +accordance with +https://tools.ietf.org/html/rfc3986#section-6.2.2[RFC 3986 6.2.2]: + + 1. The URL is parsed into scheme, userinfo, host, port, path, query and + fragment components. (Not all of these members are necessarily present.) + 2. The scheme, hostname, and port if present, are converted to lower case. + 3. Percent-encoded values for + https://tools.ietf.org/html/rfc3986#section-2.3[unreserved characters] + converted to their unencoded forms. + 4. Additionally URL percent-encoded values for characters in the path + and with numeric values larger than 127 (i.e. not ASCII) are decoded. + 5. The resulting path is checked for invalid UTF-8 sequences, consisting + of surrogate pairs, illegal byte sequences, or overlong encodings. + If this check fails, then the entire URL is considered invalid. + 6. Path segments consisting of `.` and `..` are resolved as per + https://tools.ietf.org/html/rfc3986#section-6.2.2.3[RFC 3986 6.2.2.3]. + 7. Further, empty path segments are removed, meaning that duplicate + slash (`/`) separators are removed from the path. + +Note that steps 4, 5, and 7 are not specified by RFC 3986, but performing +them is believed to improve both the usability and security of _nng_ +applications, without violating RFC 3986 itself. + +== API The library API is documented at <<libnng#,libnng(3)>>. -SEE ALSO --------- +== SEE ALSO + <<libnng#,libnng(3)>>, <<nng_compat#,nng_compat(3)>> -COPYRIGHT ---------- +== COPYRIGHT Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc] + Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] |