CURLOPT_PRE_PROXY(3)

Hey bestie!! 💖 You’ve landed on CURLOPT_PRE_PROXY(3) from the Library Functions Manual — the page all about the pre-proxy host to use. Grab a strawberry drink, because we’re getting into SOCKS-before-the-proxy territory. 🍓✨

💖 NAME 💖

• CURLOPT_PRE_PROXY — pre-proxy host to use. That’s the whole name, no cap. 🫶

---

✨ SYNOPSIS ✨

Okay so first, include the curl header, then call curl_easy_setopt with this exact signature:

#include <curl/curl.h>

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PRE_PROXY, char *preproxy);

---

🌸 DESCRIPTION 🌸

Set the preproxy to use for the upcoming request. 💅 The parameter should be a char * to a null-terminated string holding the hostname or dotted numerical IP address. If you’re giving a numerical IPv6 address, it must be written within [brackets] — like, that part is not optional, bestie. 🫶

To specify the port number in this string, append :[port] to the end of the host name. The proxy’s port number may optionally be specified with the separate option CURLOPT_PROXYPORT(3). If you don’t specify it, libcurl defaults to using port 1080 for proxies. 🎀

A pre proxy is a SOCKS proxy that curl connects to before it connects to the HTTP(S) proxy specified in the CURLOPT_PROXY(3) option. The pre proxy can only be a SOCKS proxy — that’s the vibe check it has to pass. ✨

The pre proxy string should be prefixed with [scheme]:// to specify which kind of socks is used. Use socks4://, socks4a://, socks5:// or socks5h:// to request the specific SOCKS version to be used. The last one, socks5h://, enables socks5 and asks the proxy to do the resolving — also known as CURLPROXY_SOCKS5_HOSTNAME type. Otherwise SOCKS4 is used as default. 👑

Setting the pre proxy string to "" (an empty string) explicitly disables the use of a pre proxy. 💜

⚠️ When you set a hostname to use, do not assume that there is any particular single port number used widely for proxies. Specify it. For real, don’t make it guess. 😭

The application does not have to keep the string around after setting this option. Set it and let it go, bestie. 🦋

Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. 🔥

---

🎀 DEFAULT 🎀

NULL — yep, that’s the default, and it’s giving “no pre proxy unless you ask.” 💅

---

🦋 PROTOCOLS 🦋

This functionality affects all supported protocols. All of them. No cap. 🌈

---

⭐ EXAMPLE ⭐

Here’s the example, with the calls and strings exactly as they should be:

int main(void)
{
  CURL *curl = curl_easy_init();
  if(curl) {
    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/file.txt");
    curl_easy_setopt(curl, CURLOPT_PRE_PROXY, "socks4://socks-proxy:1080");
    curl_easy_setopt(curl, CURLOPT_PROXY, "http://proxy:80");
    curl_easy_perform(curl);
  }
}

---

🧚 AVAILABILITY 🧚

Added in curl 7.52.0. It’s been iconic since then. 👑

---

💜 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 — if that happens, see libcurl-errors(3). 😭

---

🌈 SEE ALSO 🌈

• CURLOPT_HTTPPROXYTUNNEL(3)
• CURLOPT_PROXY(3)

---

Signed off by libcurl · date 2026-10-12 · CURLOPT_PRE_PROXY(3), out! 💅🎀✨