]> git.ipfire.org Git - thirdparty/curl.git/commitdiff
docs: mention the as-is concept generically
authorDaniel Stenberg <daniel@haxx.se>
Sun, 6 Jul 2025 10:33:51 +0000 (12:33 +0200)
committerDaniel Stenberg <daniel@haxx.se>
Wed, 9 Jul 2025 13:32:46 +0000 (15:32 +0200)
for curl command line options and for curl_easy_setopt

Closes #17829

docs/cmdline-opts/_OPTIONS.md
docs/libcurl/curl_easy_setopt.md

index c4493647a8a9f4561007f6a7ad0c1f0c576a398a..f1067377c8ddcbdd653c80e149fac853c329f855 100644 (file)
@@ -28,6 +28,9 @@ The first argument that is exactly two dashes (`--`), marks the end of
 options; any argument after the end of options is interpreted as a URL
 argument even if it starts with a dash.
 
+curl does little to no verification of the contents of command line arguments.
+Passing in "creative octets" like newlines might trigger unexpected results.
+
 The following options are global: `%GLOBALS`.
 
 # ALL OPTIONS
index 4af2be82f954bb6385fda3a2112a984000d92438..ccca56de6b24f8657bcf4a42a19ecd011c26d28c 100644 (file)
@@ -41,28 +41,36 @@ 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).
+The *handle* argument is the return code from a curl_easy_init(3) or
+curl_easy_duphandle(3) call.
+
+Options set with this function call are sticky. They remain set 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).
+
+The order in which the options are set does not matter.
+
+# STRINGS
 
 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
+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.
+libcurl does little to no verification of the contents of provided strings.
+Passing in "creative octets" like newlines where they are not expected might
+trigger unexpected results.
 
 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.
-
 # OPTIONS
 
 ## CURLOPT_ABSTRACT_UNIX_SOCKET