PAHO_CS_SUB(1L)

💅 PAHO_CS_SUB — the manual page, but make it cute

okay so bestie, welcome to paho_cs_sub, straight out of manual section 1L ✨ it's a whole command, it's a whole vibe, and by the end of this page you're gonna understand it fr fr. no skimming, we're going line by line because everything here matters 🫶

---

🎀 NAME 🎀

paho_cs_sub — receive (subscribe to) data from an MQTT server. that's it, that's the job 💖

---

✨ SYNOPSIS ✨

paho_cs_sub [topic] [-t|--topic topic] [-c|--connection connection]
[-h|--host hostname] [-p|--port portnumber] [-i|--clientid clientid]
[-u|--username username] [-P|--password password] [-k|--keepalive
keepalive-timeout] [-V|--MQTT-version 31|311|5]
[-q|--qos 0|1|2] [-R|--no-retained] [--delimiter delimiter] [--no-
delimiter]
[--quiet] [--verbose] [--trace min|max|error|protocol]
[--will-topic will-topic] [--will-payload will-payload] [--will-retain]
[--will-qos 0|1|2]
[--cafile cafile] [--capath capath] [--cert certfile] [--key keyfile]
[--keypass password] [--ciphers cipher-string] [--insecure]

heads up: -i/--clientid, -u/--username, -P/--password, -k/--keepalive and --verbose show up right there in the synopsis, so they're real options you can pass — they just don't get their own little paragraph down in OPTIONS. iykyk 😌

---

🌈 DESCRIPTION 🌈

so paho_cs_sub receives data from an MQTT server, and it does it using the Eclipse Paho C client synchronous library (MQTTClient) — iconic combo, no cap 🧚

and what even is MQTT? okay so: MQTT is a protocol that runs over TCP/IP, and it lets programs talk to each other super easily through a server 🌸 messages get published to topics, and then they get delivered to literally anyone subscribed to those topics. it's giving group chat but for programs, honestly.

and the matching publisher program — the one that sends instead of receives — is paho_cs_pub. bestie duo, periodt 💖

the default mode of operation? every message gets output to stdout, terminated by the delimiter. simple. slay.

---

👑 OPTIONS 👑

• -t, --topic — the MQTT topic to publish the data to 💅
• -c, --connection — the MQTT URI to connect to: it's a combo of transport prefix, host, port, and for websockets, the topic. want TCP? use the tcp prefix, like tcp://localhost:1883 ✨ SSL/TLS example: ssl://localhost:1883. websockets, insecure: ws://localhost:1883/topic, and secure: wss://localhost:80/topic 🌈
• -h, --host — the TCP/IP host name of the MQTT server to connect to. together with the --port option, it's the older alternative to using --connection 🦋
• -p, --port — the TCP/IP port number of the MQTT server to connect to. together with the --host option, it's the older alternative to using --connection 🦋
• -q, --qos — the MQTT QoS on which to publish the message. the alternatives are 0, 1 or 2 ⭐
• -V, --MQTTversion — the version of the MQTT protocol to use. valid options are 31 (or mqttv31), 311 (mqttv311) and 5 (or mqttv5) 🔥
• --quiet — do not print error messages 🤫
• --trace — print library internal trace. valid levels are min, max, error and protocol 🔍
• -R, --no-retained — do not print messages which have the MQTT retained flag set 🙈
• --delimiter — the delimiter string to append to each message when printing. defaults to newline 🎀
• --no-delimiter — do not add a delimiter to each message when printing 🚫
• --will-topic — sets the MQTT will message topic to publish to. if the application ends without sending an MQTT disconnect, the will message gets published to this topic 💀
• --will-payload — only used if will-topic is set. sets the MQTT will message to be published 📨
• --will-qos — only used if will-topic is set. sets the MQTT QoS at which the will message is published. the alternatives are 0, 1 or 2 ⭐
• --will-retain — only used if will-topic is set. sets the MQTT retained flag on the will message 📌
• --cafile — only used with a TLS connection. the name of a file for the OpenSSL trust store 🔐
• --capath — only used with a TLS connection. the name of a directory holding OpenSSL trusted certificates 🔐
• --cert — only used with a TLS connection. the name of a file for the TLS keystore containing a client certificate to be presented 🪪
• --key — only used with a TLS connection. the name of a file containing the client private key 🗝️
• --keypass — only used with a TLS connection. the password for the client private key file, if needed 🔑
• --ciphers — only used with a TLS connection. a list of cipher suites that the client will present to the server during the TLS handshake 🧚
• --insecure — only used with a TLS connection. don't check that the server certificate common name matches the hostname 😭

---

⚠️ bestie, quick vibe check: every single one of the TLS options (--cafile, --capath, --cert, --key, --keypass, --ciphers, --insecure) is only used with a TLS connection, and --will-payload, --will-qos and --will-retain are only used if will-topic is set. don't be out here setting them and wondering why nothing happened 🙈

---

and that's the whole page, bestie. you ate it. 💅

this beauty lives over at http://eclipse.org/paho, and this version is dated 31 July 2018 (v1.3.0) — so yeah, it's an elder icon and we respect it 👑 thanks for coming to my ted talk, mwah 🫶💖