fixes #246 Need nngcat man page

1 files changed, 246 insertions, 0 deletions

diff --git a/docs/man/nngcat.adoc b/docs/man/nngcat.adoc
new file mode 100644
index 00000000..7c7acef6
--- /dev/null
+++ b/docs/man/nngcat.adoc
@@ -0,0 +1,246 @@
+= nngcat(1)
+//
+// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2018 Capitar IT Group BV <info@capitar.com>
+//
+// This document is supplied under the terms of the MIT License, a
+// copy of which should be located in the distribution where this
+// file was obtained (LICENSE.txt).  A copy of the license may also be
+// found online at https://opensource.org/licenses/MIT.
+//
+
+== NAME
+
+nngcat - command line access to Scalabity Protocols
+
+== SYNOPSIS
+
+*nngcat* --help
+
+*nngcat* [_OPTION_]... 
+
+== DESCRIPTION
+
+The _nngcat_ utility provides command line access to the Scalability
+Protocols, making it possible to write shell scripts that interact
+with other peers in a Scalability Protocols topology, by both sending and
+receiving messages.
+
+== OPTIONS
+
+The following options may be supplied for _OPTION_.
+
+TIP: The _nngcat_ utility accepts shortened versions of these options, as long
+as the supplied option is unambiguous.  For example `--comp` can be used in lieu
+of `--compat`, but `--re` may not be used for anything because it could mean
+any of `--req`, `--rep`, or `--respondent`.
+
+Options that take values may be separated from their value either by an
+equa
+
+=== Generic
+*-h, --help*::
+  Get usage help.
+*-v, --verbose*::
+  Select verbose operation.
+*-q, --silent*::
+  Select silent operation.
+*--compat*::
+  Compatible mode.  This cause _nngcat_ to behave more like the legacy
+  _nanocat_ application.  In this mode connections are made asynchronously,
+  and the *--pair* option selects version 0 of the <<nng_pair#,PAIR>> protocol
+  instead of version 1.
+*--subscribe*=_TOPIC_::
+  Subscribe to _TOPIC_.  This option can only be used with the
+  <<nng_sub#,SUBv0>> protocol.  The _TOPIC_ is checked against the first bytes
+  of messages received, and messages are discarded if they do not match.
+  This may be specified multiple times to subscribe to multiple topics.  If
+  not specified at all, then a default subscription to everything is assumed.
+
+=== Protocol Selection
+NOTE: At least one protocol must be selected.
+
+*--bus, --bus0*::
+  Select the <<nng_bus#,BUSv0>> protocol.  This protocol can send
+  and receive messages to and from other <<nng_bus#,BUSv0>> peers.
+
+*--req, --req0*::
+  Select the <<nng_req#,REQv0>> protocol.  This protocol sends
+  messages to <<nng_rep#,REPv0>> peers and receives replies from them.
+
+*--rep, --rep0*::
+  Select the <<nng_rep#,REPv0>> protocol.  This protocol receives
+  messages from <<nng_req#,REQv0>> peers and can send replies to them.
+
+*--pub, --pub0*::
+  Select the <<nng_pub#,PUBv0>> protocol.  This protocol sends
+  messages to <<nng_sub#,SUBv0>> peers.
+
+*--sub, --sub0*::
+  Select the <<nng_sub#,SUBv0>> protocol.  This protocol receives
+  messages from <<nng_pub#,PUBv0>> peers, and filters them based on
+  subscriptions set with *--subscribe*.
+  
+*--push, --push0*::
+  Select the <<nng_push#,PUSHv0>> protocol.  This protocol sends
+  messages to <<nng_pull#,PULLv0>> peers. A given message is normally
+  only delivered to a single peer.
+
+*--pull, --pull0*::
+  Select the <<nng_pull#,PULLv0>> protocol.  This protocol receives
+  messages from <<nng_push#,PUSHv0>> peers.
+
+*--pair0*::
+  Select the <<nng_pair#,PAIRv0>> protocol.  This protocol can send and
+  receive messages with one connected <<nng_pair#,PAIRv0>> peer.
+
+*--pair1*::
+  Select the <<nng_pair#,PAIRv1>> protocol.  This protocol can send and
+  receive messages with one connected <<nng_pair#,PAIRv1>> peer. It 
+  is not supported in *--compat* mode.  (Polyamorous mode is not supported 
+  in _nngcat_, although peers may be using polyamorous mode.)
+
+*--pair*::
+  Acts as an alias for *--pair1*, unless *--compat* mode is selected, in
+  which case it acts as an alias for *--pair0*.
+
+*--surveyor, --surveyor0*::
+  Select the <<nng_surveyor#,SURVEYORv0>> protocol.  This protocol sends
+  a survey request to <<nng_respondent#,RESPONDENTv0>> peers, and then
+  receives replies from them.
+
+*--respondent, --respondent0*::
+  Select the <<nng_respondent#,RESPONDENTv0>> protocol.  This protocol receives
+  survey requests from <<nng_survey#,SURVEYORv0>> peers, and can send a reply
+  to them.
+
+=== Peer Selection
+NOTE: At least one peer address must be selected.
+
+TIP: While legacy _nanocat_ only supported one peer, _nng_ can support
+more than one peer on a given connection.
+
+*--connect, --dial*=_URL_::
+  Connect to the peer at the address specified by _URL_.
+
+*--bind, --listen*=_URL_::
+  Bind to, and accept connections from peers, at the address specified by _URL_.
+
+*-x, --connect-ipc*=_PATH_::
+  Connect to the IPC path specified by _PATH_.  This is the same as 
+  *--connect*=ipc://_PATH_.
+
+*-X, --bind-ipc*=_PATH_::
+  Bind to the IPC path specified by _PATH_.  This is the same as 
+  *--bind*=ipc://_PATH_.
+
+*-l, --connect-local*=_PORT_::
+  Connect to `localhost` at the TCP port specified by _PORT_.  This is the same
+  as *--connect*=tcp://127.0.0.1:__PORT__.
+
+*-L, --bind-local*=_PORT_::
+  Bind to the TCP port specified by _PORT_.  This is the same as 
+  *--bind*=tcp://127.0.0.1:__PORT__.
+
+=== Receive Options
+
+Data messages received can be formatted in different ways.  These
+options can only be specified when using a protocol that receives messages.
+
+*--format*=_FORMAT_::
+  Format data as indicated.  The _FORMAT_ can be any of: +
+  `no`:::
+    No output at all.
+  `raw`:::
+    Raw output, every byte received is sent to standard output.
+  `ascii`:::
+    ASCII safe, printable ASCII is emitted verbatim, with other bytes
+    substituted with `.` (period).
+  `quoted`:::
+    Messages are printed as quoted strings, using C language conventions.
+  `hex`:::
+    Messages are printed as quoted strings, with every byte appearing as
+    an escaped hexadecimal value, such as `\x2E`.
+  `msgpack`:::
+    Messages are emitted as https://msgpack.org[MessagePack] "bin format"
+    (byte arrays).
+
+*-A, --ascii*::
+  The same as specifying *--format*=`ascii`.
+
+*-Q, --quoted*::
+  The same as specifying *--format*=`quoted`.
+
+*--hex*::
+  The same as specifying *--format*=`hex`.
+
+*--msgpack*::
+  The same as specifying *--format*=`msgpack`.
+
+*--raw*::
+  The same as specifying *--format*=`raw`.
+
+*--receive-timeout*=_SEC_::
+  Give up receiving messages after _SEC_ seconds pass without any received
+  messages.
+
+=== Transmit Options
+
+Protocols that support sending data can use these options to select
+the data. 
+
+*-D, --data*=_DATA_::
+  Use _DATA_ for the body of outgoing messages.
+
+*-F, --file*=_FILE_::
+  Use _FILE_ for the body of outgoing messages.
+
+*-i, --interval*=_SEC_::
+  For protocols that send unsolicited data (as opposed to those that
+  send data only in response to received messages), this will resend the
+  outgoing message at repeating intervals of _SEC_ seconds.
+
+*-d, --delay*=_SEC_::
+  Wait _SEC_ seconds before sending the first outgoing message.  This is
+  useful to let connections establish before sending data, thereby avoiding
+  message loss.
+
+*--send-timeout*=_SEC_::
+  Give up trying to send a message after _SEC_ seconds.
+
+== EXAMPLES
+
+.Echo service using request/reply.
+[source,sh]
+----
+$ addr="tcp://127.0.0.1:4567"
+$ nngcat --rep --listen=${addr} --data="42" --quoted &
+$ nngcat --req --dial=${addr} --data="what is the answer?" --quoted
+"what is the answer?"
+"42"
+----
+
+.Send a chime every hour (3600 seconds).
+[source,sh]
+----
+$ addr=ipc:///grandpa_clock
+$ nngcat --pub --listen=${addr} --data "cuckoo" --interval 3600 &
+$ nngcat --sub --dial=${addr} --quoted &
+"cuckoo"
+----
+
+== SEE ALSO
+
+<<libnng#,libnng(3)>>,
+<<nng#,nng(3)>>,
+<<nng_bus#,nng_bus(7)>>,
+<<nng_pair#,nng_pair(7)>>,
+<<nng_pub#,nng_pub(7)>>,
+<<nng_pull#,nng_pull(7)>>,
+<<nng_push#,nng_push(7)>>,
+<<nng_sub#,nng_sub(7)>>,
+<<nng_rep#,nng_rep(7)>>,
+<<nng_req#,nng_req(7)>>,
+<<nng_respondent#,nng_respondent(7)>>,
+<<nng_surveyor#,nng_surveyor(7)>>
+