CURLOPT_PROTOCOLS(3)

📦
version 8.18.0 · 24 versions
, in fedora 44

💅 CURLOPT_PROTOCOLS(3) — the "allowed protocols" one

okay so bestie, you found the CURLOPT_PROTOCOLS(3) page — it lives in the Library Functions Manual, and honestly? it's giving ✨legacy✨. buckle up, we're getting into it 🎀

✨ SYNOPSIS ✨

#include <curl/curl.h>

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROTOCOLS, long bitmask);

🌸 DESCRIPTION 🌸

okay first thing's first, and I need you to hear me on this: this option is deprecated. like, officially. we strongly recommend you use CURLOPT_PROTOCOLS_STR(3) instead, because this one literally cannot control all the available protocols. that's the whole reason, no cap.

so what does it do? you pass a long that holds a bitmask of protocol bits. if you use it, that bitmask caps what protocols libcurl is allowed to use in the transfer. the vibe: your libcurl might be built to support a whole buffet of protocols, but you can still restrict specific transfers to only a subset of them. lowkey iconic, very much "you get a protocol, you don't, you get a protocol."

by default libcurl accepts all protocols it supports, which is CURLPROTO_ALL. also peep CURLOPT_REDIR_PROTOCOLS(3) while you're here 👀

these are the available protocol defines, and yes I'm listing every single one because I would never do you dirty like that:

CURLPROTO_DICT
CURLPROTO_FILE
CURLPROTO_FTP
CURLPROTO_FTPS
CURLPROTO_GOPHER
CURLPROTO_HTTP
CURLPROTO_HTTPS
CURLPROTO_IMAP
CURLPROTO_IMAPS
CURLPROTO_LDAP
CURLPROTO_LDAPS
CURLPROTO_POP3
CURLPROTO_POP3S
CURLPROTO_RTMP
CURLPROTO_RTMPE
CURLPROTO_RTMPS
CURLPROTO_RTMPT
CURLPROTO_RTMPTE
CURLPROTO_RTMPTS
CURLPROTO_RTSP
CURLPROTO_SCP
CURLPROTO_SFTP
CURLPROTO_SMB
CURLPROTO_SMBS
CURLPROTO_SMTP
CURLPROTO_SMTPS
CURLPROTO_TELNET
CURLPROTO_TFTP

🦋 DEFAULT 🦋

All protocols built-in. that's it, that's the default. everything's invited to the party 🎉

🌈 PROTOCOLS 🌈

this functionality affects all supported protocols. not some. all. periodt.

🍓 EXAMPLE 🍓

ok so here's the actual code, copy it exactly bestie, don't freestyle:

int main(int argc, char **argv)
{
  CURL *curl = curl_easy_init();
  if(curl) {
    /* pass in the URL from an external source */
    curl_easy_setopt(curl, CURLOPT_URL, argv[1]);

    /* only allow HTTP, TFTP and SFTP */
    curl_easy_setopt(curl, CURLOPT_PROTOCOLS,
                     CURLPROTO_HTTP | CURLPROTO_TFTP | CURLPROTO_SFTP);

    /* Perform the request */
    curl_easy_perform(curl);
  }
}

the way this slays: you're passing the URL in from outside and locking the allowed protocols down to just CURLPROTO_HTTP, CURLPROTO_TFTP and CURLPROTO_SFTP. main character security energy 🔥

🧚 HISTORY 🧚

so CURLPROTO_* macros became long types in 8.16.0. before that version, you needed a long cast when passing them to curl_easy_setopt(3). iykyk, ancient lore 💀

💀 DEPRECATED 💀

deprecated since 7.85.0. she's still here, but she's on her way out 🙈

💜 AVAILABILITY 💜

added in curl 7.19.4. old money, honestly 👑

⭐ RETURN VALUE ⭐

curl_easy_setopt(3) returns a CURLcode indicating success or error.

  • CURLE_OK (0) means everything was OK — slay 💖
  • non-zero means an error occurred — not slay 😭

either way, go check libcurl-errors(3) if you want the full tea.

🫶 SEE ALSO 🫶

and that's the page, bestie ✨ this lil slice of libcurl lore was brought to you by libcurl, dated 2026-10-12, and honestly? she ate. now go use CURLOPT_PROTOCOLS_STR(3) like I told you 💅🦋

📦 where this page comes from