PAHO_C_PUB(1L)

🌸 NAME 🌸

paho_c_pub — send (publish) data to an MQTT server 💌

okay so real talk, bestie: we are in the PAHO_C_PUB(1L) manual page, and this whole thing is about yeeting messages at an MQTT server. that's it. that's the vibe. let's get into it ✨

---

🎀 SYNOPSIS 🎀

paho_c_pub [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|--retained] [-n|--null-message] [-m|--message
message] [-f|--filename filename] [--delimiter delimiter] [--maxdatalen
maxdatalen]
[--message-expiry expiry-interval] [--user-property name value]
[--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 bestie: a few of the things floating around in that synopsis — -i|--clientid, -u|--username, -P|--password, -k|--keepalive, --delimiter, --maxdatalen and --verbose — are listed right there in the SYNOPSIS but don't get their own lil write-up in the OPTIONS section below. i'm not gonna make stuff up about them, so just know they exist and they're valid to pass. iykyk 🫶

---

💅 DESCRIPTION 💅

so paho_c_pub sends data to an MQTT server, and it does it using the Eclipse Paho C client asynchronous library, aka MQTTAsync. iconic name, no notes.

MQTT is a protocol that runs over TCP/IP, and the whole point of it is letting programs chat with each other super easily through a server. messages get published to topics, and then they get delivered to literally anyone who subscribed to those topics. it's giving group chat but for processes. 💬

and the matching subscriber program, paho_c_sub, is the one that receives the MQTT messages. they're a duo. soulmates, even. 🫶

the default mode of operation is that it reads input from stdin and sends a separate message for each line it reads. but there are options that switch the whole mode up so you can send:

• a one-off message of 0 length — that's -n
• a given string — that's -m
• the contents of a file — that's -f

pick your fighter. 💖

---

✨ OPTIONS ✨

• -t, --topic — the MQTT topic you're publishing the data to. that's where it goes. that's the destination. 📍
• -c, --connection — the MQTT URI to connect to. it's a combo of transport prefix, host, port, and — for websockets — topic. to connect using TCP you use the tcp prefix, like: tcp://localhost:1883. an example using SSL/TLS: ssl://localhost:1883. an example for 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. along with the --port option, this is an older alternative to using --connection. vintage but valid. 👑
• -p, --port — the TCP/IP port number of the MQTT server to connect to. along with the --host option, also an 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). and lowkey important: if MQTT version 5 is used, then some additional options become valid, like --message-expiry and --user-property. 🔥
• --quiet — do not print error messages. silence. shhh. 🤫
• --trace — print library internal trace. valid levels are min, max, error and protocol. for when you need to see everything going on inside. 🧚
• -r, --retained — publish messages with the MQTT retained flag set. 📌
• -n, --null-message — publish a 0-length message. a message that is literally nothing. it's giving minimalism. 💀
• -m, --message — publish a one off message with the payload supplied. 🍓
• -f, --filename — publish a one off message with the contents of the file whose name is given. 📁
• --message-expiry — [MQTT version 5 only] sets the expiry interval property of messages, in seconds. ⏳
• --user-property — [MQTT version 5 only] sets a user property of sent messages. it takes a pair of strings, name and value. 🏷️
• --will-topic — sets the MQTT will message topic to publish to. here's the dramatic part: if the application ends without sending an MQTT disconnect, the will message gets published to this topic. it's your final words. 😭
• --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, watch out: --insecure turns off the check that the server certificate common name matches the hostname. it's literally named insecure. do with that information what you will. 💀

---

okay that's the whole page, you ate it, periodt 👑💖

this lil manual page lives over at http://eclipse.org/paho, and the version we're reading is from 31 July 2018 (v1.3.0). thanks for coming to my ted talk, now go publish something iconic 🦋✨💅