From 8b1c2f6d53758ef9a1345e053cab202ce6b35c5b Mon Sep 17 00:00:00 2001 From: Ian Craggs Date: Tue, 31 Jul 2018 20:24:28 +0100 Subject: [PATCH] Add man pages for utilities and Doxgyen config for API man page output #346 --- doc/DoxyfileV3AsyncAPI | 2 +- doc/DoxyfileV3AsyncAPI.in | 2 +- doc/DoxyfileV3ClientAPI | 2 +- doc/DoxyfileV3ClientAPI.in | 2 +- doc/man/man1/paho_c_pub.1 | 199 +++++++++++++++++++++++++++++++++++++ doc/man/man1/paho_c_sub.1 | 170 +++++++++++++++++++++++++++++++ doc/man/man1/paho_cs_pub.1 | 199 +++++++++++++++++++++++++++++++++++++ doc/man/man1/paho_cs_sub.1 | 170 +++++++++++++++++++++++++++++++ src/samples/paho_cs_sub.c | 2 +- src/samples/pubsub_opts.c | 11 +- 10 files changed, 749 insertions(+), 10 deletions(-) create mode 100644 doc/man/man1/paho_c_pub.1 create mode 100644 doc/man/man1/paho_c_sub.1 create mode 100644 doc/man/man1/paho_cs_pub.1 create mode 100644 doc/man/man1/paho_cs_sub.1 diff --git a/doc/DoxyfileV3AsyncAPI b/doc/DoxyfileV3AsyncAPI index 91aea104..88d7e4bb 100644 --- a/doc/DoxyfileV3AsyncAPI +++ b/doc/DoxyfileV3AsyncAPI @@ -1368,7 +1368,7 @@ RTF_EXTENSIONS_FILE = # If the GENERATE_MAN tag is set to YES (the default) Doxygen will # generate man pages -GENERATE_MAN = NO +GENERATE_MAN = YES # The MAN_OUTPUT tag is used to specify where the man pages will be put. # If a relative path is entered the value of OUTPUT_DIRECTORY will be diff --git a/doc/DoxyfileV3AsyncAPI.in b/doc/DoxyfileV3AsyncAPI.in index e2ed5aee..7e5bc581 100644 --- a/doc/DoxyfileV3AsyncAPI.in +++ b/doc/DoxyfileV3AsyncAPI.in @@ -1369,7 +1369,7 @@ RTF_EXTENSIONS_FILE = # If the GENERATE_MAN tag is set to YES (the default) Doxygen will # generate man pages -GENERATE_MAN = NO +GENERATE_MAN = YES # The MAN_OUTPUT tag is used to specify where the man pages will be put. # If a relative path is entered the value of OUTPUT_DIRECTORY will be diff --git a/doc/DoxyfileV3ClientAPI b/doc/DoxyfileV3ClientAPI index 70268565..a39690a8 100644 --- a/doc/DoxyfileV3ClientAPI +++ b/doc/DoxyfileV3ClientAPI @@ -1368,7 +1368,7 @@ RTF_EXTENSIONS_FILE = # If the GENERATE_MAN tag is set to YES (the default) Doxygen will # generate man pages -GENERATE_MAN = NO +GENERATE_MAN = YES # The MAN_OUTPUT tag is used to specify where the man pages will be put. # If a relative path is entered the value of OUTPUT_DIRECTORY will be diff --git a/doc/DoxyfileV3ClientAPI.in b/doc/DoxyfileV3ClientAPI.in index 482542fd..8c41dc93 100644 --- a/doc/DoxyfileV3ClientAPI.in +++ b/doc/DoxyfileV3ClientAPI.in @@ -1369,7 +1369,7 @@ RTF_EXTENSIONS_FILE = # If the GENERATE_MAN tag is set to YES (the default) Doxygen will # generate man pages -GENERATE_MAN = NO +GENERATE_MAN = YES # The MAN_OUTPUT tag is used to specify where the man pages will be put. # If a relative path is entered the value of OUTPUT_DIRECTORY will be diff --git a/doc/man/man1/paho_c_pub.1 b/doc/man/man1/paho_c_pub.1 new file mode 100644 index 00000000..60ec2df0 --- /dev/null +++ b/doc/man/man1/paho_c_pub.1 @@ -0,0 +1,199 @@ +.TH PAHO_C_PUB 1L "31 July 2018 (v1.3.0)" http://eclipse.org/paho + +.SH NAME +paho_c_pub \- send (publish) data to an MQTT server + +.SH SYNOPSIS +.B paho_c_pub +[\fItopic\fR] +[\fB\-t\fR|\fB\-\-topic\fR \fItopic\fR] +[\fB\-c\fR|\fB\-\-connection\fR \fIconnection\fR] +[\fB\-h\fR|\fB\-\-host\fR \fIhostname\fR] +[\fB\-p\fR|\fB\-\-port\fR \fIportnumber\fR] +[\fB\-i\fR|\fB\-\-clientid\fR \fIclientid\fR] +[\fB\-u\fR|\fB\-\-username\fR \fIusername\fR] +[\fB\-P\fR|\fB\-\-password\fR \fIpassword\fR] +[\fB\-k\fR|\fB\-\-keepalive\fR \fIkeepalive-timeout\fR] +[\fB\-V\fR|\fB\-\-MQTT-version\fR \fB31\fR|\fB311\fR|\fB5\fR] +.br +[\fB\-q\fR|\fB\-\-qos\fR \fB0\fR|\fB1\fR|\fB2\fR] +[\fB\-r\fR|\fB\-\-retained\fR] +[\fB\-n\fR|\fB\-\-null-message\fR] +[\fB\-m\fR|\fB\-\-message\fR \fImessage\fR] +[\fB\-f\fR|\fB\-\-filename\fR \fIfilename\fR] +[\fB\-\-delimiter\fR \fIdelimiter\fR] +[\fB\-\-maxdatalen\fR \fImaxdatalen\fR] +.br +[\fB\-\-message-expiry\fR \fIexpiry-interval\fR] +[\fB\-\-user-property\fR \fIname\fR \fIvalue\fR] +.br +[\fB\-\-quiet\fR] +[\fB\-\-verbose\fR] +[\fB\-\-trace\fR \fBmin\fR|\fBmax\fR|\fBerror\fR|\fBprotocol\fR] +.br +[\fB\-\-will-topic\fR \fIwill-topic\fR] +[\fB\-\-will-payload\fR \fIwill-payload\fR] +[\fB\-\-will-retain\fR] +[\fB\-\-will-qos\fR \fB0\fR|\fB1\fR|\fB2\fR] +.br +[\fB\-\-cafile\fR \fIcafile\fR] +[\fB\-\-capath\fR \fIcapath\fR] +[\fB\-\-cert\fR \fIcertfile\fR] +[\fB\-\-key\fR \fIkeyfile\fR] +[\fB\-\-keypass\fR \fIpassword\fR] +[\fB\-\-ciphers\fR \fIcipher-string\fR] +[\fB\-\-insecure\fR] + + +.SH DESCRIPTION +.B paho_c_pub +sends data to an MQTT server using the Eclipse Paho C client asynchronous library (MQTTAsync). +MQTT is a protocol, operating over TCP/IP, which allows programs to easily communicate +with each other through a server. Messages are published to topics and delivered to any subscribers to those topics. +The corresponding subscriber program \fBpaho_c_sub\fR allows the receipt of MQTT messages. +.PP +The default mode of operation is to read input from stdin, sending a separate message for each line read. Options exist +to change this mode to send a one-off message, of 0 length (\fB-n\fR), a given string (\fB-m\fR), or the contents of a file (\fB-f\fR). + +.SH "OPTIONS" +.TP +.PD 0 +.BI \-t +.TP +.PD +.B \-\-topic +The MQTT topic to publish the data to. +.TP +.PD 0 +.BI \-c +.TP +.PD +.B \-\-connection +The MQTT URI to connect to, a combination of transport prefix, host, port and for websockets, topic. +To connect using TCP use the tcp prefix, for example: \fBtcp://\fR\fIlocalhost\fR\fB:\fR\fI1883\fR. +An example using SSL/TLS: \fBssl://\fR\fIlocalhost\fR\fB:\fR\fI1883\fR. +An example for websockets, insecure: \fBws://\fR\fIlocalhost\fR\fB:\fR\fI1883\fR\fB/\fR\fItopic\fR, and +secure: \fBwss://\fR\fIlocalhost\fR\fB:\fR\fI80\fR\fB/\fR\fItopic\fR. +.TP +.PD 0 +.BI \-h +.TP +.PD +.B \-\-host +The TCP/IP host name of the MQTT server to connect to. Along with the \fB--port\fR option, an older alternative to using \fB--connection\fR. +.TP +.PD 0 +.BI \-p +.TP +.PD +.B \-\-port +The TCP/IP port number of the MQTT server to connect to. Along with the \fB--host\fR option, an older alternative to using \fB--connection\fR. +.TP +.PD 0 +.BI \-q +.TP +.PD +.B \-\-qos +The MQTT QoS on which to publish the message. The alternatives are \fB0\fR, \fB1\fR or \fB2\fR. +.TP +.PD 0 +.BI \-V +.TP +.PD +.B \-\-MQTTversion +The version of the MQTT protocol to use. Valid options are \fB31\fR (or \fBmqttv31\fR), \fB311\fR (\fBmqttv311\fR) and \fB5\fR (or \fBmqttv5\fR). +If MQTT version 5 is used, then some additional options are valid, such as \fB--message-expiry\fR and \fB--user-property\fR. +.TP +.PD +.B \-\-quiet +Do not print error messages. +.TP +.PD +.B \-\-trace +Print library internal trace. Valid levels are \fBmin\fR, \fBmax\fR, \fBerror\fR and \fprotocol\fR. +.TP +.PD 0 +.BI \-r +.TP +.PD +.B \-\-retained +Publish messages with the MQTT retained flag set. +.TP +.PD 0 +.BI \-n +.TP +.PD +.B \-\-null-message +Publish a 0-length message. +.TP +.PD 0 +.BI \-m +.TP +.PD +.B \-\-message +Publish a one off message with the payload supplied. +.TP +.PD 0 +.BI \-f +.TP +.PD +.B \-\-filename +Publish a one off message with the contents of the file whose name is given. +.TP +.PD +.B \-\-message-expiry +[MQTT version 5 only] Sets the expiry interval property of messages in seconds. +.TP +.PD +.B \-\-user-property +[MQTT version 5 only] Sets a user property of sent messages. A pair of strings, name and value. +.TP +.PD +.B \-\-will-topic +Sets the MQTT will message topic to publish to. If the application ends without sending an MQTT disconnect, the +will message will be published to this topic. +.TP +.PD +.B \-\-will-payload +Only used if \fBwill-topic\fR is set. Sets the MQTT will message to be published. +.TP +.PD +.B \-\-will-qos +Only used if \fBwill-topic\fR is set. Sets the MQTT QoS at which the will message is published. The alternatives are \fB0\fR, \fB1\fR or \fB2\fR. +.TP +.PD +.B \-\-will-retain +Only used if \fBwill-topic\fR is set. Sets the MQTT retained flag on the will message. +.TP +.PD +.B \-\-cafile +Only used with a TLS connection. The name of a file for the OpenSSL trust store. +.TP +.PD +.B \-\-capath +Only used with a TLS connection. The name of a directory holding OpenSSL trusted certificates. +.TP +.PD +.B \-\-cert +Only used with a TLS connection. The name of a file for the TLS keystore containing a client certificate to be presented. +.TP +.PD +.B \-\-key +Only used with a TLS connection. The name of a file containing the client private key. +.TP +.PD +.B \-\-keypass +Only used with a TLS connection. The password for the client private key file, if needed. +.TP +.PD +.B \-\-ciphers +Only used with a TLS connection. A list of cipher suites that the client will present to the server during the TLS handshake. +.TP +.PD +.B \-\-insecure +Only used with a TLS connection. Don't check that the server certificate common name matches the hostname. + + + + + diff --git a/doc/man/man1/paho_c_sub.1 b/doc/man/man1/paho_c_sub.1 new file mode 100644 index 00000000..0f69cefd --- /dev/null +++ b/doc/man/man1/paho_c_sub.1 @@ -0,0 +1,170 @@ +.TH PAHO_C_SUB 1L "31 July 2018 (v1.3.0)" http://eclipse.org/paho + +.SH NAME +paho_c_sub \- receive (subscribe to) data from an MQTT server + +.SH SYNOPSIS +.B paho_c_sub +[\fItopic\fR] +[\fB\-t\fR|\fB\-\-topic\fR \fItopic\fR] +[\fB\-c\fR|\fB\-\-connection\fR \fIconnection\fR] +[\fB\-h\fR|\fB\-\-host\fR \fIhostname\fR] +[\fB\-p\fR|\fB\-\-port\fR \fIportnumber\fR] +[\fB\-i\fR|\fB\-\-clientid\fR \fIclientid\fR] +[\fB\-u\fR|\fB\-\-username\fR \fIusername\fR] +[\fB\-P\fR|\fB\-\-password\fR \fIpassword\fR] +[\fB\-k\fR|\fB\-\-keepalive\fR \fIkeepalive-timeout\fR] +[\fB\-V\fR|\fB\-\-MQTT-version\fR \fB31\fR|\fB311\fR|\fB5\fR] +.br +[\fB\-q\fR|\fB\-\-qos\fR \fB0\fR|\fB1\fR|\fB2\fR] +[\fB\-R\fR|\fB\-\-no-retained\fR] +[\fB\-\-delimiter\fR \fIdelimiter\fR] +[\fB\-\-no-delimiter\fR] +.br +[\fB\-\-quiet\fR] +[\fB\-\-verbose\fR] +[\fB\-\-trace\fR \fBmin\fR|\fBmax\fR|\fBerror\fR|\fBprotocol\fR] +.br +[\fB\-\-will-topic\fR \fIwill-topic\fR] +[\fB\-\-will-payload\fR \fIwill-payload\fR] +[\fB\-\-will-retain\fR] +[\fB\-\-will-qos\fR \fB0\fR|\fB1\fR|\fB2\fR] +.br +[\fB\-\-cafile\fR \fIcafile\fR] +[\fB\-\-capath\fR \fIcapath\fR] +[\fB\-\-cert\fR \fIcertfile\fR] +[\fB\-\-key\fR \fIkeyfile\fR] +[\fB\-\-keypass\fR \fIpassword\fR] +[\fB\-\-ciphers\fR \fIcipher-string\fR] +[\fB\-\-insecure\fR] + + +.SH DESCRIPTION +.B paho_c_sub +receives data from an MQTT server using the Eclipse Paho C client asynchronous library (MQTTAsync). +MQTT is a protocol, operating over TCP/IP, which allows programs to easily communicate +with each other through a server. Messages are published to topics and delivered to any subscribers to those topics. +The corresponding publisher program \fBpaho_c_pub\fR allows MQTT messages to be sent. +.PP +The default mode of operation is to output each message to stdout terminated by the delimiter. + +.SH "OPTIONS" +.TP +.PD 0 +.BI \-t +.TP +.PD +.B \-\-topic +The MQTT topic to publish the data to. +.TP +.PD 0 +.BI \-c +.TP +.PD +.B \-\-connection +The MQTT URI to connect to, a combination of transport prefix, host, port and for websockets, topic. +To connect using TCP use the tcp prefix, for example: \fBtcp://\fR\fIlocalhost\fR\fB:\fR\fI1883\fR. +An example using SSL/TLS: \fBssl://\fR\fIlocalhost\fR\fB:\fR\fI1883\fR. +An example for websockets, insecure: \fBws://\fR\fIlocalhost\fR\fB:\fR\fI1883\fR\fB/\fR\fItopic\fR, and +secure: \fBwss://\fR\fIlocalhost\fR\fB:\fR\fI80\fR\fB/\fR\fItopic\fR. +.TP +.PD 0 +.BI \-h +.TP +.PD +.B \-\-host +The TCP/IP host name of the MQTT server to connect to. Along with the \fB--port\fR option, an older alternative to using \fB--connection\fR. +.TP +.PD 0 +.BI \-p +.TP +.PD +.B \-\-port +The TCP/IP port number of the MQTT server to connect to. Along with the \fB--host\fR option, an older alternative to using \fB--connection\fR. +.TP +.PD 0 +.BI \-q +.TP +.PD +.B \-\-qos +The MQTT QoS on which to publish the message. The alternatives are \fB0\fR, \fB1\fR or \fB2\fR. +.TP +.PD 0 +.BI \-V +.TP +.PD +.B \-\-MQTTversion +The version of the MQTT protocol to use. Valid options are \fB31\fR (or \fBmqttv31\fR), \fB311\fR (\fBmqttv311\fR) and \fB5\fR (or \fBmqttv5\fR). +.TP +.PD +.B \-\-quiet +Do not print error messages. +.TP +.PD +.B \-\-trace +Print library internal trace. Valid levels are \fBmin\fR, \fBmax\fR, \fBerror\fR and \fprotocol\fR. +.TP +.PD 0 +.BI \-R +.TP +.PD +.B \-\-no-retained +Do not print messages which have the MQTT retained flag set. +.TP +.PD +.B \-\-delimiter +The delimiter string to append to each message when printing. Defaults to newline. +.TP +.PD +.B \-\-no-delimiter +Do not add a delimiter to each message when printing. +.TP +.PD +.B \-\-will-topic +Sets the MQTT will message topic to publish to. If the application ends without sending an MQTT disconnect, the +will message will be published to this topic. +.TP +.PD +.B \-\-will-payload +Only used if \fBwill-topic\fR is set. Sets the MQTT will message to be published. +.TP +.PD +.B \-\-will-qos +Only used if \fBwill-topic\fR is set. Sets the MQTT QoS at which the will message is published. The alternatives are \fB0\fR, \fB1\fR or \fB2\fR. +.TP +.PD +.B \-\-will-retain +Only used if \fBwill-topic\fR is set. Sets the MQTT retained flag on the will message. +.TP +.PD +.B \-\-cafile +Only used with a TLS connection. The name of a file for the OpenSSL trust store. +.TP +.PD +.B \-\-capath +Only used with a TLS connection. The name of a directory holding OpenSSL trusted certificates. +.TP +.PD +.B \-\-cert +Only used with a TLS connection. The name of a file for the TLS keystore containing a client certificate to be presented. +.TP +.PD +.B \-\-key +Only used with a TLS connection. The name of a file containing the client private key. +.TP +.PD +.B \-\-keypass +Only used with a TLS connection. The password for the client private key file, if needed. +.TP +.PD +.B \-\-ciphers +Only used with a TLS connection. A list of cipher suites that the client will present to the server during the TLS handshake. +.TP +.PD +.B \-\-insecure +Only used with a TLS connection. Don't check that the server certificate common name matches the hostname. + + + + + diff --git a/doc/man/man1/paho_cs_pub.1 b/doc/man/man1/paho_cs_pub.1 new file mode 100644 index 00000000..4e8f4ad7 --- /dev/null +++ b/doc/man/man1/paho_cs_pub.1 @@ -0,0 +1,199 @@ +.TH PAHO_CS_PUB 1L "31 July 2018 (v1.3.0)" http://eclipse.org/paho + +.SH NAME +paho_cs_pub \- send (publish) data to an MQTT server + +.SH SYNOPSIS +.B paho_cs_pub +[\fItopic\fR] +[\fB\-t\fR|\fB\-\-topic\fR \fItopic\fR] +[\fB\-c\fR|\fB\-\-connection\fR \fIconnection\fR] +[\fB\-h\fR|\fB\-\-host\fR \fIhostname\fR] +[\fB\-p\fR|\fB\-\-port\fR \fIportnumber\fR] +[\fB\-i\fR|\fB\-\-clientid\fR \fIclientid\fR] +[\fB\-u\fR|\fB\-\-username\fR \fIusername\fR] +[\fB\-P\fR|\fB\-\-password\fR \fIpassword\fR] +[\fB\-k\fR|\fB\-\-keepalive\fR \fIkeepalive-timeout\fR] +[\fB\-V\fR|\fB\-\-MQTT-version\fR \fB31\fR|\fB311\fR|\fB5\fR] +.br +[\fB\-q\fR|\fB\-\-qos\fR \fB0\fR|\fB1\fR|\fB2\fR] +[\fB\-r\fR|\fB\-\-retained\fR] +[\fB\-n\fR|\fB\-\-null-message\fR] +[\fB\-m\fR|\fB\-\-message\fR \fImessage\fR] +[\fB\-f\fR|\fB\-\-filename\fR \fIfilename\fR] +[\fB\-\-delimiter\fR \fIdelimiter\fR] +[\fB\-\-maxdatalen\fR \fImaxdatalen\fR] +.br +[\fB\-\-message-expiry\fR \fIexpiry-interval\fR] +[\fB\-\-user-property\fR \fIname\fR \fIvalue\fR] +.br +[\fB\-\-quiet\fR] +[\fB\-\-verbose\fR] +[\fB\-\-trace\fR \fBmin\fR|\fBmax\fR|\fBerror\fR|\fBprotocol\fR] +.br +[\fB\-\-will-topic\fR \fIwill-topic\fR] +[\fB\-\-will-payload\fR \fIwill-payload\fR] +[\fB\-\-will-retain\fR] +[\fB\-\-will-qos\fR \fB0\fR|\fB1\fR|\fB2\fR] +.br +[\fB\-\-cafile\fR \fIcafile\fR] +[\fB\-\-capath\fR \fIcapath\fR] +[\fB\-\-cert\fR \fIcertfile\fR] +[\fB\-\-key\fR \fIkeyfile\fR] +[\fB\-\-keypass\fR \fIpassword\fR] +[\fB\-\-ciphers\fR \fIcipher-string\fR] +[\fB\-\-insecure\fR] + + +.SH DESCRIPTION +.B paho_cs_pub +sends data to an MQTT server using the Eclipse Paho C client synchronous library (MQTTClient). +MQTT is a protocol, operating over TCP/IP, which allows programs to easily communicate +with each other through a server. Messages are published to topics and delivered to any subscribers to those topics. +The corresponding subscriber program \fBpaho_cs_sub\fR allows the receipt of MQTT messages. +.PP +The default mode of operation is to read input from stdin, sending a separate message for each line read. Options exist +to change this mode to send a one-off message, of 0 length (\fB-n\fR), a given string (\fB-m\fR), or the contents of a file (\fB-f\fR). + +.SH "OPTIONS" +.TP +.PD 0 +.BI \-t +.TP +.PD +.B \-\-topic +The MQTT topic to publish the data to. +.TP +.PD 0 +.BI \-c +.TP +.PD +.B \-\-connection +The MQTT URI to connect to, a combination of transport prefix, host, port and for websockets, topic. +To connect using TCP use the tcp prefix, for example: \fBtcp://\fR\fIlocalhost\fR\fB:\fR\fI1883\fR. +An example using SSL/TLS: \fBssl://\fR\fIlocalhost\fR\fB:\fR\fI1883\fR. +An example for websockets, insecure: \fBws://\fR\fIlocalhost\fR\fB:\fR\fI1883\fR\fB/\fR\fItopic\fR, and +secure: \fBwss://\fR\fIlocalhost\fR\fB:\fR\fI80\fR\fB/\fR\fItopic\fR. +.TP +.PD 0 +.BI \-h +.TP +.PD +.B \-\-host +The TCP/IP host name of the MQTT server to connect to. Along with the \fB--port\fR option, an older alternative to using \fB--connection\fR. +.TP +.PD 0 +.BI \-p +.TP +.PD +.B \-\-port +The TCP/IP port number of the MQTT server to connect to. Along with the \fB--host\fR option, an older alternative to using \fB--connection\fR. +.TP +.PD 0 +.BI \-q +.TP +.PD +.B \-\-qos +The MQTT QoS on which to publish the message. The alternatives are \fB0\fR, \fB1\fR or \fB2\fR. +.TP +.PD 0 +.BI \-V +.TP +.PD +.B \-\-MQTTversion +The version of the MQTT protocol to use. Valid options are \fB31\fR (or \fBmqttv31\fR), \fB311\fR (\fBmqttv311\fR) and \fB5\fR (or \fBmqttv5\fR). +If MQTT version 5 is used, then some additional options are valid, such as \fB--message-expiry\fR and \fB--user-property\fR. +.TP +.PD +.B \-\-quiet +Do not print error messages. +.TP +.PD +.B \-\-trace +Print library internal trace. Valid levels are \fBmin\fR, \fBmax\fR, \fBerror\fR and \fprotocol\fR. +.TP +.PD 0 +.BI \-r +.TP +.PD +.B \-\-retained +Publish messages with the MQTT retained flag set. +.TP +.PD 0 +.BI \-n +.TP +.PD +.B \-\-null-message +Publish a 0-length message. +.TP +.PD 0 +.BI \-m +.TP +.PD +.B \-\-message +Publish a one off message with the payload supplied. +.TP +.PD 0 +.BI \-f +.TP +.PD +.B \-\-filename +Publish a one off message with the contents of the file whose name is given. +.TP +.PD +.B \-\-message-expiry +[MQTT version 5 only] Sets the expiry interval property of messages in seconds. +.TP +.PD +.B \-\-user-property +[MQTT version 5 only] Sets a user property of sent messages. A pair of strings, name and value. +.TP +.PD +.B \-\-will-topic +Sets the MQTT will message topic to publish to. If the application ends without sending an MQTT disconnect, the +will message will be published to this topic. +.TP +.PD +.B \-\-will-payload +Only used if \fBwill-topic\fR is set. Sets the MQTT will message to be published. +.TP +.PD +.B \-\-will-qos +Only used if \fBwill-topic\fR is set. Sets the MQTT QoS at which the will message is published. The alternatives are \fB0\fR, \fB1\fR or \fB2\fR. +.TP +.PD +.B \-\-will-retain +Only used if \fBwill-topic\fR is set. Sets the MQTT retained flag on the will message. +.TP +.PD +.B \-\-cafile +Only used with a TLS connection. The name of a file for the OpenSSL trust store. +.TP +.PD +.B \-\-capath +Only used with a TLS connection. The name of a directory holding OpenSSL trusted certificates. +.TP +.PD +.B \-\-cert +Only used with a TLS connection. The name of a file for the TLS keystore containing a client certificate to be presented. +.TP +.PD +.B \-\-key +Only used with a TLS connection. The name of a file containing the client private key. +.TP +.PD +.B \-\-keypass +Only used with a TLS connection. The password for the client private key file, if needed. +.TP +.PD +.B \-\-ciphers +Only used with a TLS connection. A list of cipher suites that the client will present to the server during the TLS handshake. +.TP +.PD +.B \-\-insecure +Only used with a TLS connection. Don't check that the server certificate common name matches the hostname. + + + + + diff --git a/doc/man/man1/paho_cs_sub.1 b/doc/man/man1/paho_cs_sub.1 new file mode 100644 index 00000000..7cd2004a --- /dev/null +++ b/doc/man/man1/paho_cs_sub.1 @@ -0,0 +1,170 @@ +.TH PAHO_CS_SUB 1L "31 July 2018 (v1.3.0)" http://eclipse.org/paho + +.SH NAME +paho_cs_sub \- receive (subscribe to) data from an MQTT server + +.SH SYNOPSIS +.B paho_cs_sub +[\fItopic\fR] +[\fB\-t\fR|\fB\-\-topic\fR \fItopic\fR] +[\fB\-c\fR|\fB\-\-connection\fR \fIconnection\fR] +[\fB\-h\fR|\fB\-\-host\fR \fIhostname\fR] +[\fB\-p\fR|\fB\-\-port\fR \fIportnumber\fR] +[\fB\-i\fR|\fB\-\-clientid\fR \fIclientid\fR] +[\fB\-u\fR|\fB\-\-username\fR \fIusername\fR] +[\fB\-P\fR|\fB\-\-password\fR \fIpassword\fR] +[\fB\-k\fR|\fB\-\-keepalive\fR \fIkeepalive-timeout\fR] +[\fB\-V\fR|\fB\-\-MQTT-version\fR \fB31\fR|\fB311\fR|\fB5\fR] +.br +[\fB\-q\fR|\fB\-\-qos\fR \fB0\fR|\fB1\fR|\fB2\fR] +[\fB\-R\fR|\fB\-\-no-retained\fR] +[\fB\-\-delimiter\fR \fIdelimiter\fR] +[\fB\-\-no-delimiter\fR] +.br +[\fB\-\-quiet\fR] +[\fB\-\-verbose\fR] +[\fB\-\-trace\fR \fBmin\fR|\fBmax\fR|\fBerror\fR|\fBprotocol\fR] +.br +[\fB\-\-will-topic\fR \fIwill-topic\fR] +[\fB\-\-will-payload\fR \fIwill-payload\fR] +[\fB\-\-will-retain\fR] +[\fB\-\-will-qos\fR \fB0\fR|\fB1\fR|\fB2\fR] +.br +[\fB\-\-cafile\fR \fIcafile\fR] +[\fB\-\-capath\fR \fIcapath\fR] +[\fB\-\-cert\fR \fIcertfile\fR] +[\fB\-\-key\fR \fIkeyfile\fR] +[\fB\-\-keypass\fR \fIpassword\fR] +[\fB\-\-ciphers\fR \fIcipher-string\fR] +[\fB\-\-insecure\fR] + + +.SH DESCRIPTION +.B paho_cs_sub +receives data from an MQTT server using the Eclipse Paho C client synchronous library (MQTTClient). +MQTT is a protocol, operating over TCP/IP, which allows programs to easily communicate +with each other through a server. Messages are published to topics and delivered to any subscribers to those topics. +The corresponding publisher program \fBpaho_cs_pub\fR allows MQTT messages to be sent. +.PP +The default mode of operation is to output each message to stdout terminated by the delimiter. + +.SH "OPTIONS" +.TP +.PD 0 +.BI \-t +.TP +.PD +.B \-\-topic +The MQTT topic to publish the data to. +.TP +.PD 0 +.BI \-c +.TP +.PD +.B \-\-connection +The MQTT URI to connect to, a combination of transport prefix, host, port and for websockets, topic. +To connect using TCP use the tcp prefix, for example: \fBtcp://\fR\fIlocalhost\fR\fB:\fR\fI1883\fR. +An example using SSL/TLS: \fBssl://\fR\fIlocalhost\fR\fB:\fR\fI1883\fR. +An example for websockets, insecure: \fBws://\fR\fIlocalhost\fR\fB:\fR\fI1883\fR\fB/\fR\fItopic\fR, and +secure: \fBwss://\fR\fIlocalhost\fR\fB:\fR\fI80\fR\fB/\fR\fItopic\fR. +.TP +.PD 0 +.BI \-h +.TP +.PD +.B \-\-host +The TCP/IP host name of the MQTT server to connect to. Along with the \fB--port\fR option, an older alternative to using \fB--connection\fR. +.TP +.PD 0 +.BI \-p +.TP +.PD +.B \-\-port +The TCP/IP port number of the MQTT server to connect to. Along with the \fB--host\fR option, an older alternative to using \fB--connection\fR. +.TP +.PD 0 +.BI \-q +.TP +.PD +.B \-\-qos +The MQTT QoS on which to publish the message. The alternatives are \fB0\fR, \fB1\fR or \fB2\fR. +.TP +.PD 0 +.BI \-V +.TP +.PD +.B \-\-MQTTversion +The version of the MQTT protocol to use. Valid options are \fB31\fR (or \fBmqttv31\fR), \fB311\fR (\fBmqttv311\fR) and \fB5\fR (or \fBmqttv5\fR). +.TP +.PD +.B \-\-quiet +Do not print error messages. +.TP +.PD +.B \-\-trace +Print library internal trace. Valid levels are \fBmin\fR, \fBmax\fR, \fBerror\fR and \fprotocol\fR. +.TP +.PD 0 +.BI \-R +.TP +.PD +.B \-\-no-retained +Do not print messages which have the MQTT retained flag set. +.TP +.PD +.B \-\-delimiter +The delimiter string to append to each message when printing. Defaults to newline. +.TP +.PD +.B \-\-no-delimiter +Do not add a delimiter to each message when printing. +.TP +.PD +.B \-\-will-topic +Sets the MQTT will message topic to publish to. If the application ends without sending an MQTT disconnect, the +will message will be published to this topic. +.TP +.PD +.B \-\-will-payload +Only used if \fBwill-topic\fR is set. Sets the MQTT will message to be published. +.TP +.PD +.B \-\-will-qos +Only used if \fBwill-topic\fR is set. Sets the MQTT QoS at which the will message is published. The alternatives are \fB0\fR, \fB1\fR or \fB2\fR. +.TP +.PD +.B \-\-will-retain +Only used if \fBwill-topic\fR is set. Sets the MQTT retained flag on the will message. +.TP +.PD +.B \-\-cafile +Only used with a TLS connection. The name of a file for the OpenSSL trust store. +.TP +.PD +.B \-\-capath +Only used with a TLS connection. The name of a directory holding OpenSSL trusted certificates. +.TP +.PD +.B \-\-cert +Only used with a TLS connection. The name of a file for the TLS keystore containing a client certificate to be presented. +.TP +.PD +.B \-\-key +Only used with a TLS connection. The name of a file containing the client private key. +.TP +.PD +.B \-\-keypass +Only used with a TLS connection. The password for the client private key file, if needed. +.TP +.PD +.B \-\-ciphers +Only used with a TLS connection. A list of cipher suites that the client will present to the server during the TLS handshake. +.TP +.PD +.B \-\-insecure +Only used with a TLS connection. Don't check that the server certificate common name matches the hostname. + + + + + diff --git a/src/samples/paho_cs_sub.c b/src/samples/paho_cs_sub.c index e54b34c5..a0e832a3 100644 --- a/src/samples/paho_cs_sub.c +++ b/src/samples/paho_cs_sub.c @@ -109,7 +109,7 @@ int myconnect(MQTTClient* client) } if (opts.verbose && rc == MQTTCLIENT_SUCCESS) - printf("Connected\n"); + fprintf(stderr, "Connected\n"); else if (rc != MQTTCLIENT_SUCCESS && !opts.quiet) fprintf(stderr, "Connect failed with rc %d\n", rc); diff --git a/src/samples/pubsub_opts.c b/src/samples/pubsub_opts.c index 3553b8a8..a629431f 100644 --- a/src/samples/pubsub_opts.c +++ b/src/samples/pubsub_opts.c @@ -63,11 +63,12 @@ void usage(struct pubsub_opts* opts, pubsub_opts_nameValue* name_values, const c " rather than host/port to connect with TLS and/or web sockets. No default.\n" " -h (--host) : host to connect to. Default is %s.\n" " -p (--port) : network port to connect to. Default is %s.\n" - " -q (--qos) : MQTT QoS to publish on (0, 1 or 2). Default is %d.\n" - " -V : MQTT version (31, 311, or 5). Default is 311.\n" + " -q (--qos) : MQTT QoS to %s with (0, 1 or 2). Default is %d.\n" + " -V (--MQTTversion) : MQTT version (31, 311, or 5). Default is 311.\n" " --quiet : do not print error messages.\n" " --trace : print internal trace (\"error\", \"min\", \"max\" or \"protocol\").\n", - opts->publisher ? "publish" : "subscribe", opts->host, opts->port, opts->qos); + opts->publisher ? "publish" : "subscribe", opts->host, opts->port, + opts->publisher ? "publish" : "subscribe", opts->qos); if (opts->publisher) { @@ -94,7 +95,7 @@ void usage(struct pubsub_opts* opts, pubsub_opts_nameValue* name_values, const c } else { - printf(" --nodelimiter : do not use a delimiter string between messages.\n"); + printf(" --no-delimiter : do not use a delimiter string between messages.\n"); printf(" -R (--no-retained) : do not print retained messages.\n"); } @@ -210,7 +211,7 @@ int getopts(int argc, char** argv, struct pubsub_opts* opts) else return 1; } - else if (strcmp(argv[count], "--nodelimiter") == 0) + else if (strcmp(argv[count], "--no-delimiter") == 0) opts->delimiter = NULL; else if (strcmp(argv[count], "--keepalive") == 0 || strcmp(argv[count], "-k") == 0) {