GNURLMOPT_...ETFUNCTION(3)

📦 version 7.72.0, in nixos 26.05, nixpkgs unstable

✨ NAME ✨

hey bestie!! 💖 you're on the GNURLMOPT_...ETFUNCTION(3) page, from the curl_multi_setopt options manual, and this one is all about:

  • CURLMOPT_SOCKETFUNCTION — callback informed about what to wait for ✨

🛠️ SYNOPSIS 🛠️

here's the shape of it, no cap:

#include <gnurl/curl.h>

int socket_callback(CURL *easy,      /* easy handle */
                    curl_socket_t s, /* socket */
                    int what,        /* describes the socket */
                    void *userp,     /* private callback pointer */
                    void *socketp);  /* private socket pointer */

CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_SOCKETFUNCTION, socket_callback);

💅 DESCRIPTION 💅

okay so here's the tea: you pass a pointer to your callback function, and it should match the prototype shown above. 🫶

when the curl_multi_socket_action(3) function is called, it informs the application about updates in the socket (file descriptor) status by doing none, one, or multiple calls to the socket_callback. the callback function gets status updates with changes since the previous time the callback was called. if the given callback pointer is set to NULL, no callback will be called. periodt. 💖

🎀 CALLBACK ARGUMENTS 🎀

let's break down the little gang of args, bestie:

  • easy — identifies the specific transfer for which this update is related.
  • s — the specific socket this function invocation concerns. if the what argument is not CURL_POLL_REMOVE, then it holds information about what activity on this socket the application is supposed to monitor. subsequent calls to this callback might update the what bits for a socket that is already monitored.
  • userp — set with CURLMOPT_SOCKETDATA(3).
  • socketp — set with curl_multi_assign(3) or will be NULL.

the what parameter informs the callback on the status of the given socket. it can hold one of these values:

  • CURL_POLL_IN — wait for incoming data. for the socket to become readable. 👀
  • CURL_POLL_OUT — wait for outgoing data. for the socket to become writable. 🚀
  • CURL_POLL_INOUT — wait for incoming and outgoing data. for the socket to become readable or writable. 💫
  • CURL_POLL_REMOVE — the specified socket/file descriptor is no longer used by libcurl. bye boo 👋

🌸 DEFAULT 🌸

NULL (no callback) — literally no callback energy. 🫶

🌈 PROTOCOLS 🌈

All — every protocol, bestie. 💜

🔥 EXAMPLE 🔥

here's a whole little example, copied exactly because code is sacred:

static int sock_cb(CURL *e, curl_socket_t s, int what, void *cbp, void *sockp)
{
  GlobalInfo *g = (GlobalInfo*) cbp;
  SockInfo *fdp = (SockInfo*) sockp;

  if(what == CURL_POLL_REMOVE) {
    remsock(fdp);
  }
  else {
    if(!fdp) {
      addsock(s, e, what, g);
    }
    else {
      setsock(fdp, s, e, what, g);
    }
  }
  return 0;
}

main()
{
  GlobalInfo setup;
  /* ... use socket callback and custom pointer */
  curl_multi_setopt(multi, CURLMOPT_SOCKETFUNCTION, sock_cb);
  curl_multi_setopt(multi, CURLMOPT_SOCKETDATA, &setup);
}

👑 AVAILABILITY 👑

added in 7.15.4 — ancient but iconic. ✨

✅ RETURN VALUE ✅

returns CURLM_OK. slay. 💅

🦋 SEE ALSO 🦋

go read these next, bestie:

this page is giving libcurl 7.39.0 energy, dated 3 Nov 2016. bye bestie, go make that callback cute. 💖✨

📦 where this page comes from