updated docs with the new parameter

docs/libcurl/curl_multi_socket.3

@@ -6,26 +6,38 @@ curl_multi_socket \- reads/writes available data
 .SH SYNOPSIS
 #include <curl/curl.h>
 
-CURLMcode curl_multi_socket(CURLM * multi_handle, curl_socket_t sockfd);
+CURLMcode curl_multi_socket(CURLM * multi_handle, curl_socket_t sockfd,
+                            int *running_handles);
 
-CURLMcode curl_multi_socket_all(CURLM *multi_handle);
+CURLMcode curl_multi_socket_all(CURLM *multi_handle,
+                                int *running_handles);
 .SH DESCRIPTION
-Alternative versions of \fIcurl_multi_perform()\fP that allows the application
-to pass in one of the file descriptors/sockets that have been detected to have
-\&"action" on them and let libcurl perform. This allows libcurl to not have to
-scan through all possible file descriptors to check for action. When the
-application has detected action on a socket handled by libcurl, it should call
-\fIcurl_multi_perform()\fP with the \fBsockfd\fP argument set to the socket
-with the action.
-
-These functions inform the application about updates in the socket (file
-descriptor) status by doing none, one or multiple calls to the callback
-function set with the CURLMOPT_SOCKETFUNCTION option to
+Alternative versions of \fIcurl_multi_perform(3)\fP that allows the
+application to pass in one of the file descriptors/sockets that have been
+detected to have \&"action" on them and let libcurl perform. This allows
+libcurl to not have to scan through all possible file descriptors to check for
+action. When the application has detected action on a socket handled by
+libcurl, it should call \fIcurl_multi_socket(3)\fP with the \fBsockfd\fP
+argument set to the socket with the action.
+
+At return, the int \fBrunning_handles\fP points to will contain the number of
+still running easy handles within the multi handle. When this number reaches
+zero, all transfers are complete/done. Note that when you call
+\fIcurl_multi_socket(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 curl_multi_socket functions inform 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 CURLMOPT_SOCKETFUNCTION option to
 \fIcurl_multi_setopt(3)\fP. They update the status with changes since the
 previous time this function was called.
 
 To force libcurl to (re-)check all its internal sockets and transfers instead
-of just a single one, you call \fBcurl_multi_socket_all(3)\fP.
+of just a single one, you call \fBcurl_multi_socket_all(3)\fP. This is
+typically done as the first function call before the application has any
+knowledge about what sockets libcurl uses.
 
 Applications should call \fBcurl_multi_timeout(3)\fP to figure out how long to
 wait for socket actions \- at most \- before doing the timeout action: call