subasync(3)

✨ NAME ✨

subasync — Asynchronous subscription example 🦋

okay so bestie, sit down, hydrate, because this page is subasync(3) — it lives in the Library Functions Manual (section 3, we're fancy like that 💅). But real talk: this is not a function you call. It's a whole entire example program, a working MQTT client that subscribes to a topic asynchronously, and it's giving main character energy from the first #include to the last return. No cap. 💖

---

🎀 the whole program, in all its glory 🎀

First it pulls in the headers — <stdio.h>, <stdlib.h>, <string.h>, and the icon itself, "MQTTClient.h" — then it declares its constants with #define: the broker ADDRESS is "tcp://test.mosquitto.org:1883", the CLIENTID is "ExampleClientSub", the TOPIC is "MQTT Examples", the PAYLOAD is "Hello World!", QOS is 1, and TIMEOUT is 10000L. Then there's a volatile MQTTClient_deliveryToken deliveredtoken; sitting at file scope like it owns the place. 👑

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

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

volatile 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;
    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;
    }

    printf("Subscribing to topic %s\nfor client %s using QoS%d\n\n"
           "Press Q<Enter> to quit\n\n", TOPIC, CLIENTID, QOS);
    if ((rc = MQTTClient_subscribe(client, TOPIC, QOS)) != MQTTCLIENT_SUCCESS)
    {
        printf("Failed to subscribe, return code %d\n", rc);
        rc = EXIT_FAILURE;
    }
    else
    {
        int ch;
        do
        {
                ch = getchar();
        } while (ch!='Q' && ch != 'q');

        if ((rc = MQTTClient_unsubscribe(client, TOPIC)) != MQTTCLIENT_SUCCESS)
        {
                printf("Failed to unsubscribe, return code %d\n", rc);
                rc = EXIT_FAILURE;
        }
    }

    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 cast of characters (iykyk) 🧚

• delivered — the callback that fires when a delivery is confirmed. It prints Message with token value %d delivery confirmed with dt, then stashes dt into deliveredtoken. Signature: void delivered(void *context, MQTTClient_deliveryToken dt). ✨
• msgarrvd — the moment a message shows up, this one announces Message arrived, prints the topic and the message (using message->payloadlen and (char*)message->payload), then frees the message with MQTTClient_freeMessage(&message) and the topic name with MQTTClient_free(topicName), and returns 1. Signature: int msgarrvd(void *context, char *topicName, int topicLen, MQTTClient_message *message). 🎀
• connlost</> — dramatic but necessary: it prints Connection lost and the cause. Signature: void connlost(void *context, char *cause). 😭
• main — int main(int argc, char* argv[]), the whole plot. It makes a MQTTClient client; and a MQTTClient_connectOptions conn_opts initialized to MQTTClient_connectOptions_initializer, plus an int rc; to hold return codes. 🌈

---

🫶 what main actually does, step by step 🫶

1. Calls MQTTClient_create(&client, ADDRESS, CLIENTID, MQTTCLIENT_PERSISTENCE_NONE, NULL). If it doesn't equal MQTTCLIENT_SUCCESS, it prints Failed to create client, return code %d, sets rc = EXIT_FAILURE, and jumps to exit. 💀
2. Calls MQTTClient_setCallbacks(client, NULL, connlost, msgarrvd, delivered). On failure: prints Failed to set callbacks, return code %d, sets rc = EXIT_FAILURE, jumps to destroy_exit.
3. Sets conn_opts.keepAliveInterval = 20; and conn_opts.cleansession = 1;, then calls MQTTClient_connect(client, &conn_opts). On failure: prints Failed to connect, return code %d, sets rc = EXIT_FAILURE, jumps to destroy_exit.
4. Prints Subscribing to topic %s\nfor client %s using QoS%d\n\n and Press Q<Enter> to quit\n\n with TOPIC, CLIENTID, QOS, then calls MQTTClient_subscribe(client, TOPIC, QOS). If that fails it prints Failed to subscribe, return code %d and sets rc = EXIT_FAILURE.
5. Otherwise it loops on getchar() — do { ch = getchar(); } while (ch!='Q' && ch != 'q'); — so you can bounce whenever you're done. Then it calls MQTTClient_unsubscribe(client, TOPIC), and if that's not MQTTCLIENT_SUCCESS it prints Failed to unsubscribe, return code %d and sets rc = EXIT_FAILURE. 👋
6. Calls MQTTClient_disconnect(client, 10000), printing Failed to disconnect, return code %d and setting rc = EXIT_FAILURE if it doesn't return MQTTCLIENT_SUCCESS.
7. The destroy_exit: label runs MQTTClient_destroy(&client);, the exit: label runs return rc;, and that's the whole story, periodt. 💅

bestie reminder: this page is the example, so the real magic lives in the MQTTClient functions it calls — this is your blueprint, not the engine. 🔥

---

and that's the tea 🍓 this gem ships with the Paho MQTT C Client Library, dated Tue Jun 2 2026 00:00:00 — go be asynchronous, you absolute icon 👑💜