lib: add CURL_WRITEFUNC_ERROR to signal write callback error

Prior to this change if the user wanted to signal an error from their
write callbacks they would have to use logic to return a value different
from the number of bytes (nmemb) passed to the callback. Also, the
inclination of some users has been to just return 0 to signal error,
which is incorrect as that may be the number of bytes passed to the
callback.

To remedy this the user can now return CURL_WRITEFUNC_ERROR instead.

Ref: https://github.com/curl/curl/issues/9873

Closes https://github.com/curl/curl/pull/9874

docs/libcurl/opts/CURLOPT_HEADERFUNCTION.3

@@ -51,10 +51,12 @@ the header line is null-terminated!
 The pointer named \fIuserdata\fP is the one you set with the
 \fICURLOPT_HEADERDATA(3)\fP option.
 
-This callback function must return the number of bytes actually taken care of.
-If that amount differs from the amount passed in to your function, it will signal
-an error to the library. This will cause the transfer to get aborted and the
-libcurl function in progress will return \fICURLE_WRITE_ERROR\fP.
+Your callback should return the number of bytes actually taken care of. If
+that amount differs from the amount passed to your callback function, it will
+signal an error condition to the library. This will cause the transfer to get
+aborted and the libcurl function used will return \fICURLE_WRITE_ERROR\fP.
+
+You can also abort the transfer by returning CURL_WRITEFUNC_ERROR. (7.87.0)
 
 A complete HTTP header that is passed to this function can be up to
 \fICURL_MAX_HTTP_HEADER\fP (100K) bytes and includes the final line terminator.

docs/libcurl/opts/CURLOPT_INTERLEAVEFUNCTION.3

@@ -59,6 +59,13 @@ process any pending RTP data before marking the request as finished.
 
 The \fICURLOPT_INTERLEAVEDATA(3)\fP is passed in the \fIuserdata\fP argument in
 the callback.
+
+Your callback should return the number of bytes actually taken care of. If
+that amount differs from the amount passed to your callback function, it will
+signal an error condition to the library. This will cause the transfer to get
+aborted and the libcurl function used will return \fICURLE_WRITE_ERROR\fP.
+
+You can also abort the transfer by returning CURL_WRITEFUNC_ERROR. (7.87.0)
 .SH DEFAULT
 NULL, the interleave data is then passed to the regular write function:
 \fICURLOPT_WRITEFUNCTION(3)\fP.

docs/libcurl/opts/CURLOPT_WRITEFUNCTION.3

@@ -63,6 +63,8 @@ that amount differs from the amount passed to your callback function, it will
 signal an error condition to the library. This will cause the transfer to get
 aborted and the libcurl function used will return \fICURLE_WRITE_ERROR\fP.
 
+You can also abort the transfer by returning CURL_WRITEFUNC_ERROR. (7.87.0)
+
 If your callback function returns CURL_WRITEFUNC_PAUSE it will cause this
 transfer to become paused.  See \fIcurl_easy_pause(3)\fP for further details.
 

docs/libcurl/symbols-in-versions

@@ -187,6 +187,7 @@ CURL_WAIT_POLLIN                7.28.0
 CURL_WAIT_POLLOUT               7.28.0
 CURL_WAIT_POLLPRI               7.28.0
 CURL_WIN32                      7.69.0
+CURL_WRITEFUNC_ERROR            7.87.0
 CURL_WRITEFUNC_PAUSE            7.18.0
 CURL_ZERO_TERMINATED            7.56.0
 CURLALTSVC_H1                   7.64.1