CURLMOPT_NOTIFYFUNCTION(3)

💖 CURLMOPT_NOTIFYFUNCTION(3) 💖

okay bestie, welcome to the Library Functions Manual entry for CURLMOPT_NOTIFYFUNCTION(3) — the callback that receives notifications. it's giving “libcurl but make it chatty,” and honestly? iconic. 🎀

✨ NAME ✨

CURLMOPT_NOTIFYFUNCTION — callback receiving notifications 🦋

🌸 SYNOPSIS 🌸

#include <curl/curl.h>

void notify_callback(CURLM *multi,     /* multi handle */
                     unsigned int notification, /* notification type */
                     CURL *easy,       /* easy handle */
                     void *notifyp);   /* private notify pointer */

CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_NOTIFYFUNCTION, notify_callback);

💅 DESCRIPTION 💅

Pass a pointer to your callback function, and make sure it matches the prototype up there, bestie. ✨

When the multi handle processes transfers, changes can be observed by receiving notifications about them. This can eliminate the need to constantly interrogate the multi handle just to notice those changes so you can act on them. lowkey a huge vibe upgrade. 🔥

Notifications are collected and dispatched to the application's callback function at an appropriate time. 🫶

The notify callback is different from other callbacks in that it can use more libcurl API functions. Apart from curl_multi_perform(3), curl_multi_socket(3), curl_multi_socket_action(3), curl_multi_socket_all(3) and curl_multi_cleanup(3), it may call all other methods on the multi and easy handles. This includes adding and removing easy handles to/from the multi handle. so yes, it's kind of the main character callback 😌👑

Internal handles are owned by libcurl, and the public API rejects them: the easy interface functions fail with CURLE_BAD_FUNCTION_ARGUMENT, and curl_multi_add_handle(3) and curl_multi_remove_handle(3) return CURLM_BAD_EASY_HANDLE. no cap, don't try it. 💀

This callback may get invoked at any time when interacting with libcurl. This may even happen after all transfers are done, and may also happen during a call to curl_multi_cleanup(3) when cached connections are shut down. like, it really said “i go where i want.” 😭

🎀 CALLBACK ARGUMENTS 🎀

• multi — identifies the multi handle that triggered the notification. 💖
• notification — the type of notification, e.g. what happened. The following types are available right now. In the future, new ones might be added. 👀

🌈 CURLMNOTIFY_INFO_READ

When enabled via curl_multi_notify_enable(3), this informs the application that there are new messages to be processed via curl_multi_info_read(3). 📬

This notification happens whenever a message is added to an empty message stack in the multi handle, and not for subsequent additions. The notification callback is then expected to read all available messages, emptying the stack, so a subsequent addition triggers the notification again. yes, you gotta clear the stack, bestie — that's the whole assignment. 🧚

The easy handle passed is an internal handle. 🙈

💜 CURLMNOTIFY_EASY_DONE

When enabled via curl_multi_notify_enable(3), this notification is triggered when an easy handle has finished. This happens both for successful and failed transfers. 🎉

The easy handle passed is the transfer that is done. This may be an internal handle when DoH or other features are used. ⭐

• easy — identifies the transfer involved. This may be one of the application's own easy handles or an internal handle. 🦋
• notifyp — is set with CURLMOPT_NOTIFYDATA(3). 🫶

⭐ DEFAULT ⭐

NULL (no callback)

🌸 PROTOCOLS 🌸

This functionality affects all supported protocols. all of them. every single one. periodt. 💅

🔥 EXAMPLE 🔥

struct priv {
  void *ours;
};

static void notify_cb(CURLM *multi, unsigned int notification,
                      CURL *easy, void *notifyp)
{
  struct priv *p = notifyp;
  printf("my ptr: %p\n", p->ours);
  /* ... */
}

int main(void)
{
  struct priv setup;
  CURLM *multi = curl_multi_init();
  /* ... use socket callback and custom pointer */
  curl_multi_setopt(multi, CURLMOPT_NOTIFYFUNCTION, notify_cb);
  curl_multi_setopt(multi, CURLMOPT_NOTIFYDATA, &setup);
  curl_multi_notify_enable(multi, CURLMNOTIFY_INFO_READ);
}

🦋 AVAILABILITY 🦋

Added in curl 8.17.0 ✨

👑 RETURN VALUE 👑

Returns CURLM_OK. that's it, that's the answer, slay. 💖

🌈 SEE ALSO 🌈

CURLMOPT_NOTIFYDATA(3), curl_multi_notify_disable(3), curl_multi_notify_enable(3), curl_multi_socket_action(3)

---

and that's the page, bestie 🫶 source/version: libcurl, dated 2026-10-25, and this iconic little manual page is CURLMOPT_NOTIFYFUNCTION(3) from the Library Functions Manual. mwah 💋✨