| curl_easy_setopt(3) | Introduction to Library Functions | curl_easy_setopt(3) |
curl_easy_setopt - set options for a curl easy handle
#include <curl/curl.h> CURLcode curl_easy_setopt(CURL *handle, CURLoption option, parameter);
curl_easy_setopt(3) is used to tell libcurl how to behave. By setting the appropriate options, the application can change libcurl's behavior. All options are set with an option followed by a parameter. That parameter can be a long, a function pointer, an object pointer or a curl_off_t, depending on what the specific option expects. Read this manual carefully as bad input values may cause libcurl to behave badly! You can only set one option in each function call. A typical application uses many curl_easy_setopt(3) calls in the setup phase.
Options set with this function call are valid for all forthcoming transfers performed using this handle. The options are not in any way reset between transfers, so if you want subsequent transfers with different options, you must change them between the transfers. You can optionally reset all options back to internal default with curl_easy_reset(3).
Strings passed to libcurl as 'char *' arguments, are copied by the library; the string storage associated to the pointer argument may be discarded or reused after curl_easy_setopt(3) returns. The only exception to this rule is really CURLOPT_POSTFIELDS(3), but the alternative that copies the string CURLOPT_COPYPOSTFIELDS(3) has some usage characteristics you need to read up on. This function does not accept input strings longer than CURL_MAX_INPUT_LENGTH (8 MB).
The order in which the options are set does not matter.
Before version 7.17.0, strings were not copied. Instead the user was forced keep them available until libcurl no longer needed them.
The handle is the return code from a curl_easy_init(3) or curl_easy_duphandle(3) call.
This functionality affects all supported protocols
int main(void)
{
CURL *curl = curl_easy_init();
if(curl) {
CURLcode res;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
res = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
}
Added in curl 7.1
CURLE_OK (zero) means that the option was set properly, non-zero means an error occurred as <curl/curl.h> defines. See the libcurl-errors(3) man page for the full list with descriptions.
Strings passed on to libcurl must be shorter than 8000000 bytes, otherwise curl_easy_setopt(3) returns CURLE_BAD_FUNCTION_ARGUMENT (added in 7.65.0).
CURLE_BAD_FUNCTION_ARGUMENT is returned when the argument to an option is invalid, like perhaps out of range.
If you try to set an option that libcurl does not know about, perhaps because the library is too old to support it or the option was removed in a recent version, this function returns CURLE_UNKNOWN_OPTION. If support for the option was disabled at compile-time, it returns CURLE_NOT_BUILT_IN.
curl_easy_cleanup(3), curl_easy_getinfo(3), curl_easy_init(3), curl_easy_option_by_id(3), curl_easy_option_by_name(3), curl_easy_option_next(3), curl_easy_reset(3), curl_multi_setopt(3)
| 2024-10-05 | libcurl |