CURLMOPT_SOCKETFUNCTION.3: clarified

Moved away the callback explanation from curl_multi_socket_action.3 and
expanded it somewhat.

Closes #4006

2 files changed, 26 insertions, 76 deletions

diff --git a/docs/libcurl/curl_multi_socket_action.3 b/docs/libcurl/curl_multi_socket_action.3
index 8d7731f84..27647f1bf 100644
--- a/docs/libcurl/curl_multi_socket_action.3
+++ b/docs/libcurl/curl_multi_socket_action.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -43,15 +43,14 @@ libcurl will test the descriptor internally. It is also permissible to pass
 CURL_SOCKET_TIMEOUT to the \fBsockfd\fP parameter in order to initiate the
 whole process or when a timeout occurs.
 
-At return, \fBrunning_handles\fP points to the number
-of running easy handles within the multi handle. When this number reaches
-zero, all transfers are complete/done. When you call
-\fIcurl_multi_socket_action(3)\fP on a specific socket and the counter
-decreases by one, it DOES NOT necessarily mean that this exact socket/transfer
-is the one that completed. Use \fIcurl_multi_info_read(3)\fP to figure out
-which easy handle that completed.
+At return, \fBrunning_handles\fP points to the number of running easy handles
+within the multi handle. When this number reaches zero, all transfers are
+complete/done. When you call \fIcurl_multi_socket_action(3)\fP on a specific
+socket and the counter decreases by one, it DOES NOT necessarily mean that
+this exact socket/transfer is the one that completed. Use
+\fIcurl_multi_info_read(3)\fP to figure out which easy handle that completed.
 
-The \fIcurl_multi_socket_action(3)\fP functions inform the application about
+The \fIcurl_multi_socket_action(3)\fP function informs the application about
 updates in the socket (file descriptor) status by doing none, one, or multiple
 calls to the socket callback function set with the
 \fICURLMOPT_SOCKETFUNCTION(3)\fP option to \fIcurl_multi_setopt(3)\fP. They
@@ -66,65 +65,6 @@ timeout action: call the \fIcurl_multi_socket_action(3)\fP function with the
 \fIcurl_multi_timeout(3)\fP function to poll the value at any given time, but
 for an event-based system using the callback is far better than relying on
 polling the timeout value.
-.SH "CALLBACK DETAILS"
-
-The socket \fBcallback\fP function uses a prototype like this
-.nf
-
-  int curl_socket_callback(CURL *easy,      /* easy handle */
-                           curl_socket_t s, /* socket */
-                           int action,      /* see values below */
-                           void *userp,    /* private callback pointer */
-                           void *socketp); /* private socket pointer,
-                                              \fBNULL\fP if not
-                                              previously assigned with
-                                              \fIcurl_multi_assign(3)\fP */
-
-.fi
-The callback MUST return 0.
-
-The \fIeasy\fP argument is a pointer to the easy handle that deals with this
-particular socket. Note that a single handle may work with several sockets
-simultaneously.
-
-The \fIs\fP argument is the actual socket value as you use it within your
-system.
-
-The \fIaction\fP argument to the callback has one of five values:
-.RS
-.IP "CURL_POLL_NONE (0)"
-register, not interested in readiness (yet)
-.IP "CURL_POLL_IN (1)"
-register, interested in read readiness
-.IP "CURL_POLL_OUT (2)"
-register, interested in write readiness
-.IP "CURL_POLL_INOUT (3)"
-register, interested in both read and write readiness
-.IP "CURL_POLL_REMOVE (4)"
-unregister
-.RE
-
-The \fIsocketp\fP argument is a private pointer you have previously set with
-\fIcurl_multi_assign(3)\fP to be associated with the \fIs\fP socket. If no
-pointer has been set, socketp will be NULL. This argument is of course a
-service to applications that want to keep certain data or structs that are
-strictly associated to the given socket.
-
-The \fIuserp\fP argument is a private pointer you have previously set with
-\fIcurl_multi_setopt(3)\fP and the \fICURLMOPT_SOCKETDATA(3)\fP option.
-.SH "RETURN VALUE"
-CURLMcode type, general libcurl multi interface error code.
-
-Before version 7.20.0: If you receive \fICURLM_CALL_MULTI_PERFORM\fP, this
-basically means that you should call \fIcurl_multi_socket_action(3)\fP again
-before you wait for more actions on libcurl's sockets. You don't have to do it
-immediately, but the return code means that libcurl may have more data
-available to return or that there may be more data to send off before it is
-"satisfied".
-
-The return code from this function is for the whole multi stack.  Problems
-still might have occurred on individual transfers even when one of these
-functions return OK.
 .SH "TYPICAL USAGE"
 1. Create a multi handle
 
diff --git a/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.3 b/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.3
index e55ff5e0b..dc0ccd836 100644
--- a/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.3
+++ b/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -38,14 +38,24 @@ CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_SOCKETFUNCTION, socket_callb
 Pass a pointer to your callback function, which should match the prototype
 shown above.
 
-When the \fIcurl_multi_socket_action(3)\fP function runs, it informs the
+When the \fIcurl_multi_socket_action(3)\fP function is called, it informs the
 application about updates in the socket (file descriptor) status by doing
-none, one, or multiple calls to the \fBsocket_callback\fP. The callback gets
-status updates with changes since the previous time the callback was called.
-If the given callback pointer is NULL, no callback will be called. Set the
-callback's \fBuserp\fP argument with \fICURLMOPT_SOCKETDATA(3)\fP.  See
-\fIcurl_multi_socket_action(3)\fP for more details on how the callback is used
-and should work.
+none, one, or multiple calls to the \fBsocket_callback\fP. The callback
+function gets status updates with changes since the previous time the callback
+was called. If the given callback pointer is set to NULL, no callback will be
+called.
+.SH "CALLBACK ARGUMENTS"
+\fIeasy\fP identifies the specific transfer for which this update is related.
+
+\fIs\fP is the specific socket this function invocation concerns. If the
+\fBwhat\fP argument is not CURL_POLL_REMOVE then it holds information about
+what activity on this socket the application is supposed to
+monitor. Subsequent calls to this callback might update the \fBwhat\fP bits
+for a socket that is alredy monitored.
+
+\fBuserp\fP is set with \fICURLMOPT_SOCKETDATA(3)\fP.
+
+\fBsocketp\fP is set with \fIcurl_multi_assign(3)\fP or will be NULL.
 
 The \fBwhat\fP parameter informs the callback on the status of the given
 socket. It can hold one of these values: