.\" generated by cd2nroff 0.1 from CURLMOPT_NOTIFYFUNCTION.md
.TH CURLMOPT_NOTIFYFUNCTION 3 "2025-11-13" libcurl
.SH NAME
CURLMOPT_NOTIFYFUNCTION \- callback receiving notifications
.SH SYNOPSIS
.nf
#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);
.fi
.SH DESCRIPTION
Pass a pointer to your callback function, which should match the prototype
shown above.

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 to observe such changes to
act on them.

Notifications are collected and dispatched to the application\(aqs 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 \fIcurl_multi_perform(3)\fP,
\fIcurl_multi_socket(3)\fP, \fIcurl_multi_socket_action(3)\fP, \fIcurl_multi_socket_all(3)\fP
and \fIcurl_multi_cleanup(3)\fP it may call all other methods on the
multi and easy handles. This includes adding and removing easy
handles to/from the multi handle.

This callback may get invoked at any time when interacting with libcurl.
This may even happen after all transfers are done and \fImay also\fP
happen \fIduring\fP a call to \fIcurl_multi_cleanup(3)\fP when cached connections
are shut down.
.SH CALLBACK ARGUMENTS
\fImulti\fP identifies the multi handle that triggered the notification.

\fBnotification\fP is the type of notification, e.g. what happened. The
following types are available right now. In the future, new ones might be
added.
.IP CURLMNOTIFY_INFO_READ
When enabled via \fIcurl_multi_notify_enable(3)\fP, this informs the application
that there are new messages to be processed via \fIcurl_multi_info_read(3)\fP.

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 message,
emptying the stack, so a subsequent addition triggers the notification
again.

The \fIeasy\fP handle passed is an internal handle.
.IP CURLMNOTIFY_EASY_DONE
When enabled via \fIcurl_multi_notify_enable(3)\fP, this notification is triggered
when an easy handle has finished. This happens both for successful and failed
transfers.

The \fIeasy\fP handle passed is the transfer that is done. This \fImay\fP be
an internal handle when DoH or other features are used.

\fIeasy\fP identifies the transfer involved. This may be one of the
application\(aqs own easy handle or an internal handle.

\fBnotifyp\fP is set with \fICURLMOPT_NOTIFYDATA(3)\fP.
.SH DEFAULT
NULL (no callback)
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
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);
}
.fi
.SH AVAILABILITY
Added in curl 8.17.0
.SH RETURN VALUE
Returns CURLM_OK.
.SH SEE ALSO
.BR CURLMOPT_NOTIFYDATA (3),
.BR curl_multi_notify_disable (3),
.BR curl_multi_notify_enable (3),
.BR curl_multi_socket_action (3)