docs/libcurl: improve easy setopt examples

[bagder]

• always assign the curl_easy_perform() return code (and declare the necessary 'result' variable for it)

• always call curl_easy_cleanup() on the created easy handles

[Copilot]

Pull request overview

This PR updates libcurl option documentation examples to be more consistent and safer by capturing curl_easy_perform() return codes and ensuring easy handles are cleaned up, plus a few content/wording improvements in specific option docs.

Changes:

• Update many option EXAMPLE snippets to assign the curl_easy_perform() return value to a CURLcode variable.
• Add curl_easy_cleanup() calls to examples that previously omitted cleanup of created easy handles.
• Refine select documentation text (notably CURLOPT_USE_SSL) and adjust a few HSTS-related examples.

Reviewed changes

Copilot reviewed 122 out of 122 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
docs/libcurl/opts/CURLOPT_VERBOSE.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_USE_SSL.md	Example updated for result/cleanup; adds explanatory text for SSL levels.
docs/libcurl/opts/CURLOPT_USERAGENT.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_URL.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_UPLOAD_FLAGS.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_UPLOAD.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_UPKEEP_INTERVAL_MS.md	Assign curl_easy_perform() result in example (cleanup already present later).
docs/libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_TIMEVALUE_LARGE.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_TIMEVALUE.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_TIMEOUT_MS.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_TIMEOUT.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_TIMECONDITION.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_TFTP_NO_OPTIONS.md	Store curl_easy_perform() return code in example.
docs/libcurl/opts/CURLOPT_TCP_NODELAY.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_TCP_KEEPINTVL.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_TCP_KEEPIDLE.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_TCP_KEEPCNT.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_TCP_KEEPALIVE.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_SUPPRESS_CONNECT_HEADERS.md	Store curl_easy_perform() return code in example (cleanup already present).
docs/libcurl/opts/CURLOPT_STDERR.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_SSL_VERIFYPEER.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_SSL_FALSESTART.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_SSLVERSION.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_SSH_KEYFUNCTION.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_SSH_KEYDATA.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_SSH_HOSTKEYFUNCTION.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_SSH_HOSTKEYDATA.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_SSH_COMPRESSION.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_SOCKS5_AUTH.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_RESUME_FROM_LARGE.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_RESUME_FROM.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_RESOLVER_START_FUNCTION.md	Store curl_easy_perform() return code in example.
docs/libcurl/opts/CURLOPT_RESOLVER_START_DATA.md	Store curl_easy_perform() return code in example.
docs/libcurl/opts/CURLOPT_RESOLVE.md	Store curl_easy_perform() return code in example.
docs/libcurl/opts/CURLOPT_REQUEST_TARGET.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_REFERER.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS_STR.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_READDATA.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_RANGE.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_PUT.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYPEER.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYHOST.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_PROXY_PINNEDPUBLICKEY.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_PROXYHEADER.md	Store curl_easy_perform() return code and cleanup handle in example.
docs/libcurl/opts/CURLOPT_PROXY.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_PROTOCOLS_STR.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_PROTOCOLS.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_PROGRESSDATA.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_PRIVATE.md	Store curl_easy_perform() return code and cleanup handle in example.
docs/libcurl/opts/CURLOPT_PRE_PROXY.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_PREREQFUNCTION.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_PREREQDATA.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_POSTREDIR.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_POSTFIELDSIZE_LARGE.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_POSTFIELDS.md	Store curl_easy_perform() return code(s) and cleanup handle(s) in examples.
docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_PATH_AS_IS.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_NOPROXY.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_NOPROGRESS.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_NOBODY.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_MIME_OPTIONS.md	Store curl_easy_perform() return code in example.
docs/libcurl/opts/CURLOPT_MIMEPOST.md	Store curl_easy_perform() return code and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_MAXREDIRS.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_MAXLIFETIME_CONN.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_MAXAGE_CONN.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_INTERLEAVEDATA.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_INFILESIZE_LARGE.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_INFILESIZE.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_IGNORE_CONTENT_LENGTH.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_HTTPPOST.md	Store curl_easy_perform() return code in example.
docs/libcurl/opts/CURLOPT_HTTPHEADER.md	Store curl_easy_perform() return code and cleanup handle in example.
docs/libcurl/opts/CURLOPT_HTTPGET.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_HTTP200ALIASES.md	Store curl_easy_perform() return code and cleanup handle in example.
docs/libcurl/opts/CURLOPT_HSTS_CTRL.md	Store curl_easy_perform() return code; expand example setup/cleanup.
docs/libcurl/opts/CURLOPT_HSTSWRITEDATA.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_HSTSREADDATA.md	Add an HSTS read callback example; store perform result and cleanup.
docs/libcurl/opts/CURLOPT_HSTS.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_HEADERFUNCTION.md	Store curl_easy_perform() return code and cleanup handle in example.
docs/libcurl/opts/CURLOPT_HEADERDATA.md	Store curl_easy_perform() return code and cleanup handle in example.
docs/libcurl/opts/CURLOPT_HEADER.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.md	Store curl_easy_perform() return code in example.
docs/libcurl/opts/CURLOPT_FRESH_CONNECT.md	Store curl_easy_perform() return code in example.
docs/libcurl/opts/CURLOPT_FORBID_REUSE.md	Store return codes for multiple curl_easy_perform() calls in example.
docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_FNMATCH_FUNCTION.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_FNMATCH_DATA.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_EXPECT_100_TIMEOUT_MS.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_ECH.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_DOH_URL.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYSTATUS.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYPEER.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYHOST.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_DNS_SHUFFLE_ADDRESSES.md	Store curl_easy_perform() return code in example.
docs/libcurl/opts/CURLOPT_DISALLOW_USERNAME_IN_URL.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_COPYPOSTFIELDS.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_COOKIELIST.md	Store curl_easy_perform() return code in example.
docs/libcurl/opts/CURLOPT_COOKIE.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_CONNECT_TO.md	Store curl_easy_perform() return code in example.
docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md	Wrap example in if(curl); store perform result and cleanup handle.
docs/libcurl/opts/CURLOPT_CLOSESOCKETDATA.md	Wrap example in if(curl); store perform result and cleanup handle.
docs/libcurl/opts/CURLOPT_CA_CACHE_TIMEOUT.md	Rename/standardize result variable and store perform return codes.
docs/libcurl/opts/CURLOPT_CAINFO.md	Store curl_easy_perform() return code in example.
docs/libcurl/opts/CURLOPT_AWS_SIGV4.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_APPEND.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_ALTSVC_CTRL.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_ALTSVC.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_ACCEPT_ENCODING.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.md	Assign curl_easy_perform() result and cleanup easy handle in example.
docs/libcurl/opts/CURLOPT_ABSTRACT_UNIX_SOCKET.md	Assign curl_easy_perform() result and cleanup easy handle in example.

Comments suppressed due to low confidence (1)

docs/libcurl/opts/CURLOPT_UPLOAD.md:72

• src is opened with fopen() but the example does not check if it succeeded before passing it to CURLOPT_READDATA / using it in read_cb, and it is never closed. Add an if(src) guard (with appropriate error handling) and fclose(src) after the transfer.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[bagder]

augment review

[augmentcode]

🤖 Augment PR Summary

Summary: This PR updates many libcurl option docs to make the embedded easy-interface examples safer and more consistent.

Changes:

• Capture the return value of curl_easy_perform() into a declared CURLcode variable across numerous examples.
• Add missing curl_easy_cleanup() calls so created easy handles are always cleaned up.
• Wrap a few examples in if(curl) guards where they previously assumed curl_easy_init() succeeded.
• Improve some HSTS-related examples by adding a URL and wiring up a read callback where applicable.
• Adjust a couple of examples to properly open/close FILE handles around transfers.
• Expand CURLOPT_USE_SSL documentation with additional notes about insecure modes and protocol-specific behavior.

Technical Notes: The changes are documentation-only but aim to ensure the snippets model correct resource lifetime (perform → cleanup) and make it easier for users to check transfer outcomes via the stored CURLcode.

_{🤖 Was this summary useful? React with 👍 or 👎}

[augmentcode]

Review completed. 2 suggestions posted.

Comment augment review to trigger a new review at any time.