Docs are not clear about zero-byte POST

[safinaskar]

I cannot understand from online docs at https://curl.haxx.se/libcurl/c/ how to do zero-byte POST. It seems docs should be fixed. Is the following code ok?

curl_global_init (CURL_GLOBAL_ALL);
CURL *curl_handle = curl_easy_init ();
curl_easy_setopt (curl_handle, CURLOPT_URL, "http://example.com");
curl_easy_setopt (curl_handle, CURLOPT_POSTFIELDSIZE, 0L);
CURLcode code = curl_easy_perform (curl_handle);

Or I should also set CURLOPT_POST or CURLOPT_POSTFIELDS?
Is the following code ok? Does it really perform zero-byte POST?

curl_global_init (CURL_GLOBAL_ALL);
CURL *curl_handle = curl_easy_init ();
curl_easy_setopt (curl_handle, CURLOPT_URL, "http://example.com");
curl_easy_setopt (curl_handle, CURLOPT_POSTFIELDS, NULL); // is this line ok???
curl_easy_setopt (curl_handle, CURLOPT_POSTFIELDSIZE, 0L);
CURLcode code = curl_easy_perform (curl_handle);

[bagder]

The CURLOPT_POSTFIELDS man page states:

If you want to do a zero-byte POST, you need to set CURLOPT_POSTFIELDSIZE(3) explicitly to zero, as simply setting CURLOPT_POSTFIELDS(3) to NULL or "" just effectively disables the sending of the specified string. libcurl will instead assume that you'll send the POST data using the read callback!

Isn't that good enough?

[jay]

Or I should also set CURLOPT_POST or CURLOPT_POSTFIELDS?

Yes that's what you should do.

@bagder I think maybe it's lost in translation. How about:

If CURLOPT_POSTFIELDS(3) is set to "" or NULL, and CURLOPT_POSTFIELDSIZE(3) is set to 0, then libcurl will do a zero-byte POST. If CURLOPT_POSTFIELDS(3) is set to "" or NULL, and CURLOPT_POSTFIELDSIZE(3) is not set to 0, then libcurl will get the POST data from the read callback.

[bagder]

@safinaskar, you think @jay's version makes it clearer?

[safinaskar]

Yes :)

[jay]

I tried indenting so it isn't so repetitive, how about this:

If CURLOPT_POSTFIELDS(3) is set to "" or NULL, and:
    CURLOPT_POSTFIELDSIZE(3) is set to 0, then libcurl will do a zero-byte POST.
    CURLOPT_POSTFIELDSIZE(3) is \fInot\fP set to 0, then libcurl will get the POST data from the read callback.

screenshot:

is that better or worse

[jay]

I looked at this again and it would be incorrect to say libcurl will get the POST data from the read callback when CURLOPT_POSTFIELDSIZE is not 0 (I was assuming it's the default, but not necessarily).

It is also incorrect to say it will get the POST data from the read callback when just CURLOPT_POSTFIELDS is set to an empty string, even though that's the way it's been documented since 5a6dcdc. I couldn't go all the way back to 7.17 but I went back to curl 7.21 and setting CURLOPT_POSTFIELDS to "" results in a zero byte POST.

So assuming somewhere between 7.17 and 7.21 there wasn't a behavior change, how about this:

diff --git a/docs/libcurl/opts/CURLOPT_POSTFIELDS.3 b/docs/libcurl/opts/CURLOPT_
index f9f9ead..17ec2d7 100644
--- a/docs/libcurl/opts/CURLOPT_POSTFIELDS.3
+++ b/docs/libcurl/opts/CURLOPT_POSTFIELDS.3
@@ -42,16 +42,15 @@ This POST is a normal application/x-www-form-urlencoded kind
 set that Content-Type by default when this option is used), which is commonly
 used by HTML forms. Change Content-Type with \fICURLOPT_HTTPHEADER(3)\fP.

-Using \fICURLOPT_POSTFIELDS(3)\fP implies \fICURLOPT_POST(3)\fP.
-
 You can use \fIcurl_easy_escape(3)\fP to url-encode your data, if necessary. It
 returns a pointer to an encoded string that can be passed as \fIpostdata\fP.

-If you want to do a zero-byte POST, you need to set
-\fICURLOPT_POSTFIELDSIZE(3)\fP explicitly to zero, as simply setting
-\fICURLOPT_POSTFIELDS(3)\fP to NULL or "" just effectively disables the
-sending of the specified string. libcurl will instead assume that you'll send
-the POST data using the read callback!
+Using \fICURLOPT_POSTFIELDS(3)\fP implies \fICURLOPT_POST(3)\fP.
+
+If \fICURLOPT_POSTFIELDS(3)\fP is explicitly set to NULL then libcurl will get
+the POST data from the read callback. If you want to send a zero-byte POST set
+\fICURLOPT_POSTFIELDS(3)\fP to an empty string, or set \fICURLOPT_POST(3)\fP to
+1 and \fICURLOPT_POSTFIELDSIZE(3)\fP to 0.

 Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header.
 You can disable this header with \fICURLOPT_HTTPHEADER(3)\fP as usual.

[bagder]

Very good digging and research! 👍

[jay]

Tested back to 7.17 and same thing, so this has landed in f77dfbc. Thanks