CURLOPT_HSTS_CTRL(3)

✨ CURLOPT_HSTS_CTRL ✨

okay bestie, welcome to the CURLOPT_HSTS_CTRL page of the libcurl manual — it's a Library Functions Manual entry and honestly? it's giving "small but mighty" 🎀

🌸 NAME 🌸

CURLOPT_HSTS_CTRL — the lil option that controls HSTS behavior 💅

---

🦋 SYNOPSIS 🦋

#include <curl/curl.h>

#define CURLHSTS_ENABLE       (1L << 0)
#define CURLHSTS_READONLYFILE (1L << 1)

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

like, you include the header, you get those two #defined bits, and you hand a long bitmask to curl_easy_setopt on your CURL *handle. that's the whole vibe ✨

---

💖 DESCRIPTION 💖

so HSTS stands for HTTP Strict Transport Security, and what it means is: an HTTPS server can literally tell the client "bestie do NOT contact me again over clear-text HTTP for a certain period into the future" — and the client respects it. no cap. 🙅‍♀️

libcurl then automatically redirects HTTP attempts to those hosts so they use HTTPS instead. how does it remember? by libcurl retaining this knowledge in an in-memory cache. iconic behavior fr fr 🧠✨

so what you do is: populate that long bitmask with the correct set of features, and that tells libcurl exactly how to handle HSTS for the transfers using this handle. that's it, that's the whole job 💅

---

🎀 BITS 🎀

• CURLHSTS_ENABLE — turns on the in-memory HSTS cache for this handle. slay, the cache is live 🫶
• CURLHSTS_READONLYFILE — makes the HSTS file (if specified) read-only, which means libcurl will not save the cache to the file when it closes the handle. it's giving "look but don't touch" 🙈

---

⭐ DEFAULT ⭐

0

(yes, zero. nothing enabled out of the box, you gotta opt in 💀)

---

🌈 PROTOCOLS 🌈

this functionality affects http only 🦋

---

🔥 EXAMPLE 🔥

int main(void)
{
  CURL *curl = curl_easy_init();
  if(curl) {
    curl_easy_setopt(curl, CURLOPT_HSTS_CTRL, CURLHSTS_ENABLE);
    curl_easy_perform(curl);
  }
}

look at that. init, set the bitmask to CURLHSTS_ENABLE, perform. main character energy tbh 👑

---

👑 AVAILABILITY 👑

Added in curl 7.74.0 — so if you're on something ancient, this is your sign to upgrade bestie 🧚

---

💜 RETURN VALUE 💜

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

CURLE_OK (0) means everything was OK. non-zero means an error occurred — see libcurl-errors(3) for the deets 😭

lowkey important: 0 = good vibes, anything else = go read libcurl-errors(3). periodt.

---

🍓 SEE ALSO 🍓

• CURLOPT_ALTSVC(3)
• CURLOPT_CONNECT_TO(3)
• CURLOPT_HSTS(3)
• CURLOPT_RESOLVE(3)

---

and that's the page!! 💖 brought to you by libcurl, dated 2026-10-12 — stay encrypted, stay iconic, and remember: HSTS is your friend 🦋✨