pubasync(3)

🎀 NAME 🎀

okay bestie, sit down, grab ur boba 🧋 because pubasync is literally the Asynchronous publication example — that's the whole job description, no cap. It's a full little C program from the Library Functions Manual that shows u how to publish a message with the Paho MQTT C client and then wait for the delivery token to come home 🕊️✨

the vibe is: create a client, hook up callbacks, connect, publish, then spin in a loop until the message u sent is confirmed delivered. main character energy fr fr 👑

       #include <stdio.h>
       #include <stdlib.h>
       #include <string.h>
       #include "MQTTClient.h"

       #if !defined(_WIN32)
       #include <unistd.h>
       #else
       #include <windows.h>
       #endif

       #define ADDRESS     "tcp://test.mosquitto.org:1883"
       #define CLIENTID    "ExampleClientPub"
       #define TOPIC       "MQTT Examples"
       #define PAYLOAD     "Hello World!"
       #define QOS         1
       #define TIMEOUT     10000L

       MQTTClient_deliveryToken deliveredtoken;

       void delivered(void *context, MQTTClient_deliveryToken dt)
       {
           printf("Message with token value %d delivery confirmed\n", dt);
           deliveredtoken = dt;
       }

       int msgarrvd(void *context, char *topicName, int topicLen, MQTTClient_message *message)
       {
           printf("Message arrived\n");
           printf("     topic: %s\n", topicName);
           printf("   message: %.*s\n", message->payloadlen, (char*)message->payload);
           MQTTClient_freeMessage(&message);
           MQTTClient_free(topicName);
           return 1;
       }

       void connlost(void *context, char *cause)
       {
           printf("\nConnection lost\n");
           printf("     cause: %s\n", cause);
       }

       int main(int argc, char* argv[])
       {
           MQTTClient client;
           MQTTClient_connectOptions conn_opts = MQTTClient_connectOptions_initializer;
           MQTTClient_message pubmsg = MQTTClient_message_initializer;
           MQTTClient_deliveryToken token;
           int rc;

           if ((rc = MQTTClient_create(&client, ADDRESS, CLIENTID,
               MQTTCLIENT_PERSISTENCE_NONE, NULL)) != MQTTCLIENT_SUCCESS)
           {
               printf("Failed to create client, return code %d\n", rc);
               rc = EXIT_FAILURE;
               goto exit;
           }

           if ((rc = MQTTClient_setCallbacks(client, NULL, connlost, msgarrvd, delivered)) != MQTTCLIENT_SUCCESS)
           {
               printf("Failed to set callbacks, return code %d\n", rc);
               rc = EXIT_FAILURE;
               goto destroy_exit;
           }

           conn_opts.keepAliveInterval = 20;
           conn_opts.cleansession = 1;
           if ((rc = MQTTClient_connect(client, &conn_opts)) != MQTTCLIENT_SUCCESS)
           {
               printf("Failed to connect, return code %d\n", rc);
               rc = EXIT_FAILURE;
               goto destroy_exit;
           }

           pubmsg.payload = PAYLOAD;
           pubmsg.payloadlen = (int)strlen(PAYLOAD);
           pubmsg.qos = QOS;
           pubmsg.retained = 0;
           deliveredtoken = 0;
           if ((rc = MQTTClient_publishMessage(client, TOPIC, &pubmsg, &token)) != MQTTCLIENT_SUCCESS)
           {
               printf("Failed to publish message, return code %d\n", rc);
               rc = EXIT_FAILURE;
           }
           else
           {
               printf("Waiting for publication of %s\n"
                   "on topic %s for client with ClientID: %s\n",
                   PAYLOAD, TOPIC, CLIENTID);
               while (deliveredtoken != token)
               {
                               #if defined(_WIN32)
                                       Sleep(100);
                               #else
                                       usleep(10000L);
                               #endif
               }
           }

           if ((rc = MQTTClient_disconnect(client, 10000)) != MQTTCLIENT_SUCCESS)
           {
               printf("Failed to disconnect, return code %d\n", rc);
               rc = EXIT_FAILURE;
           }

       destroy_exit:
           MQTTClient_destroy(&client);

       exit:
           return rc;
       }

---

🌸 the grand tour, step by step 🌸

the includes, the platform check, and the glow-up macros

• #include <stdio.h>, #include <stdlib.h>, #include <string.h> and #include "MQTTClient.h" come in first, in that order 💖
• then a little OS vibe check: #if !defined(_WIN32) pulls in #include <unistd.h>, and the #else branch pulls in #include <windows.h>, closed off with #endif 🪟
• ADDRESS is defined as "tcp://test.mosquitto.org:1883"
• CLIENTID is defined as "ExampleClientPub"
• TOPIC is defined as "MQTT Examples"
• PAYLOAD is defined as "Hello World!"
• QOS is defined as 1
• TIMEOUT is defined as 10000L

the global bestie

• MQTTClient_deliveryToken deliveredtoken; sits at file scope, being the shared little flag the callbacks and main both look at 👑

delivered() — signature void delivered(void *context, MQTTClient_deliveryToken dt)

• prints "Message with token value %d delivery confirmed\n" with dt filled in
• then sets deliveredtoken = dt;

msgarrvd() — signature int msgarrvd(void *context, char *topicName, int topicLen, MQTTClient_message *message)

• prints "Message arrived\n"
• prints " topic: %s\n" with topicName
• prints " message: %.*s\n" using message->payloadlen and (char*)message->payload
• then cleans up with MQTTClient_freeMessage(&message); and MQTTClient_free(topicName);
• and return 1; 🌈

connlost() — signature void connlost(void *context, char *cause)

• prints "\nConnection lost\n"
• prints " cause: %s\n" with cause 😭

main() — signature int main(int argc, char* argv[])

locals, in order: MQTTClient client;, MQTTClient_connectOptions conn_opts = MQTTClient_connectOptions_initializer;, MQTTClient_message pubmsg = MQTTClient_message_initializer;, MQTTClient_deliveryToken token;, int rc;

then the actual plot:

1. MQTTClient_create(&client, ADDRESS, CLIENTID, MQTTCLIENT_PERSISTENCE_NONE, NULL) — if the return code isn't MQTTCLIENT_SUCCESS, it prints "Failed to create client, return code %d\n" with rc, sets rc = EXIT_FAILURE;, and does goto exit;
2. MQTTClient_setCallbacks(client, NULL, connlost, msgarrvd, delivered) — if that isn't MQTTCLIENT_SUCCESS, it prints "Failed to set callbacks, return code %d\n" with rc, sets rc = EXIT_FAILURE;, and does goto destroy_exit;
3. conn_opts.keepAliveInterval = 20; and conn_opts.cleansession = 1;, then MQTTClient_connect(client, &conn_opts) — if that isn't MQTTCLIENT_SUCCESS, it prints "Failed to connect, return code %d\n" with rc, sets rc = EXIT_FAILURE;, and does goto destroy_exit;
4. then it stuffs the message: pubmsg.payload = PAYLOAD;, pubmsg.payloadlen = (int)strlen(PAYLOAD);, pubmsg.qos = QOS;, pubmsg.retained = 0;, deliveredtoken = 0;
   • then MQTTClient_publishMessage(client, TOPIC, &pubmsg, &token) — if that's not MQTTCLIENT_SUCCESS, it prints "Failed to publish message, return code %d\n" with rc and sets rc = EXIT_FAILURE;
   • the else branch is the cute part: it prints "Waiting for publication of %s\n" and "on topic %s for client with ClientID: %s\n" passing PAYLOAD, TOPIC, CLIENTID, and then waits — while (deliveredtoken != token) loops forever until the delivered token catches up to the token we got back, and inside that loop it does Sleep(100); under #if defined(_WIN32) and usleep(10000L); under the #else 🦋
5. then MQTTClient_disconnect(client, 10000) — if that isn't MQTTCLIENT_SUCCESS, it prints "Failed to disconnect, return code %d\n" with rc and sets rc = EXIT_FAILURE;
6. destroy_exit: label → MQTTClient_destroy(&client);
7. exit: label → return rc;

bestie listen — that while (deliveredtoken != token) loop has no timeout and no exit, so it will just keep spinning until the token arrives. that's the "asynchronous publication" bit doing its thing. don't say I didn't warn u 💀

---

and that's the whole page, periodt 💅 this lil beauty comes to u from the Paho MQTT C Client Library, dated Tue Jun 2 2026 00:00:00 — stan a classic, mwah 🫶💖✨