curl/curl.h: replace recursive macros with C++-friendly method to enforce 3 args

[vszakats]

Certain uses may still trigger a C compiler warning
-Wdisabled-macro-expansion after this, e.g. when the call is wrapped
in the CURL_IGNORE_DEPRECATION() macro as seen in docs/examples.

Suggested-by: Kai Pastor
Ref: #20682 (comment)

Follow-up to ee9b000 #20686
Follow-up to daa6b27 #20597

---

With warnings temporarily re-enabled unrelated CI failures expected
due to recursive macros in 3rd-party headers.

[vszakats]

It works to avoid recursive warnings in libcurl code, e.g. doh.c.
No word yet on the C++ CI job because arm runners seem to be
down.

And there is this particular case, where the call is wrapper in
CURL_IGNORE_DEPRECATION(), where the warning remains:

docs/examples/multi-formadd.c:94:9: error: disabled expansion of recursive macro [clang-diagnostic-disabled-macro-expansion,-warnings-as-errors]
   94 |         curl_easy_setopt(curl, CURLOPT_HTTPPOST, formpost);
      |         ^
/Users/runner/work/curl/curl/include/curl/curl.h:3335:3: note: expanded from macro 'curl_easy_setopt'
 3335 |   curl_easy_setopt curl_exactly_three_arguments(handle, opt, param)
      |   ^
301 warnings generated.

https://github.com/curl/curl/actions/runs/22349795920/job/64673656914?pr=20709

same with the bare compiler (w/o clang-tidy):

docs/examples/postit2-formadd.c:96:7: error: disabled expansion of recursive macro [-Werror,-Wdisabled-macro-expansion]
   96 |       curl_easy_setopt(curl, CURLOPT_HTTPPOST, formpost);
      |       ^
include/curl/curl.h:3335:3: note: expanded from macro 'curl_easy_setopt'
 3335 |   curl_easy_setopt curl_exactly_three_arguments(handle, opt, param)
      |   ^
1 error generated.

In itself a niche case, but I find it interesting.

[vszakats]

@aisle-analyzer augment review

[aisle-research-bot]

🔒 Aisle Security Analysis

✅ We scanned this PR and did not find any security vulnerabilities.

_{Aisle supplements but does not replace security review.}

---

Analyzed PR: #20709 at commit ee0ec12

[augmentcode]

🤖 Augment PR Summary

Summary: Reworks the public curl_easy_setopt/curl_easy_getinfo/curl_share_setopt/curl_multi_setopt 3-argument enforcement macros to avoid self-recursive macro expansion that can trip C++/clang warnings.
Why: Improves compatibility with C++ and reduces occurrences of -Wdisabled-macro-expansion stemming from the previous recursive-macro approach.

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

[augmentcode]

Review completed. No suggestions at this time.

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

[Copilot]

Pull request overview

This PR replaces recursive macros with a C++-friendly two-stage macro solution for enforcing exactly three arguments to curl functions (curl_easy_setopt, curl_easy_getinfo, curl_share_setopt, curl_multi_setopt). The previous recursive macro approach broke C++ code that used the :: namespace qualifier (e.g., ::curl_easy_setopt(...)) and an alternative non-recursive approach using parentheses (curl_easy_setopt) also broke this C++ pattern. The new two-stage solution uses a helper macro curl_exactly_three_arguments that expands to parenthesized arguments, avoiding both the recursive macro warnings and the C++ compatibility issues.

Changes:

• Introduced curl_exactly_three_arguments helper macro and updated four function macros to use the two-stage expansion pattern
• Updated comments in build configuration files to reflect that recursive macro warnings from curl/curl.h now only occur in rare combinations rather than always

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
include/curl/curl.h	Replaced recursive macros with two-stage solution using curl_exactly_three_arguments helper macro for four functions
m4/curl-compilers.m4	Updated comment to indicate -Wdisabled-macro-expansion warning is now primarily from standard headers, only rarely from curl/curl.h
CMake/PickyWarnings.cmake	Updated comment to match the m4 file change regarding warning source

---

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