Putting an Explicit Proxy on a libcurl Easy Handle

libcurl attaches proxy configuration to the easy handle performing the transfer. Set the intermediary’s address on that handle, while leaving CURLOPT_URL as the destination URL.

The following fragment assumes libcurl has been initialized and handle is a valid easy handle:

char error[CURL_ERROR_SIZE] = {0};
CURLcode result;

result = curl_easy_setopt(handle, CURLOPT_ERRORBUFFER, error);
if (result == CURLE_OK)
    result = curl_easy_setopt(handle, CURLOPT_URL,
                              "https://example.com/");
if (result == CURLE_OK)
    result = curl_easy_setopt(handle, CURLOPT_PROXY,
                              "http://proxy.example:8080");
if (result == CURLE_OK)
    result = curl_easy_perform(handle);

if (result != CURLE_OK)
    fprintf(stderr, "%s\n", error[0] ? error
                                  : curl_easy_strerror(result));

Keep the error buffer alive while the handle refers to it. Before leaving its scope, clean up the handle or replace or clear its CURLOPT_ERRORBUFFER pointer. The proxy hostname is a placeholder; an unauthenticated candidate from the HTTP proxy list can supply the address for this public-site test. Use its actual scheme and port, and check whether it permits the HTTPS tunnel.

An HTTPS destination can use an HTTP proxy. libcurl handles the tunnel for that HTTPS transfer. The http:// in the proxy option describes the connection to the intermediary. Change it to https:// only for a proxy endpoint that actually accepts TLS and a libcurl build that supports it.

Make the effective route deliberate

An explicit proxy option overrides the corresponding proxy environment setting. Bypass is a separate decision: an inherited no_proxy can still exclude the destination. If this handle must use the selected proxy for every destination it is given, configure CURLOPT_NOPROXY as an empty string as part of that policy.

Conversely, setting CURLOPT_PROXY to an empty string explicitly disables proxy use. Setting it to NULL removes the explicit assignment and permits environment-based behavior again. Those two values serve different purposes.

A target-specific header such as Content-Type: text/xml does not select the proxy. Add it only when the actual request body and destination API need that media type.

Read the HTTP result as well

A successful curl_easy_perform does not mean the website returned a successful HTTP status. Read CURLINFO_RESPONSE_CODE and apply the application’s status handling. The proxy’s CONNECT reply has its own value, CURLINFO_HTTP_CONNECTCODE; a tunnel rejection precedes any website response.

CURLOPT_FAILONERROR can treat many HTTP errors as failures, but its documentation calls out authentication exceptions. Keep a proxy’s 407 challenge separate from the destination’s status.