aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorDaniel Stenberg <daniel@haxx.se>2019-06-10 11:47:17 +0200
committerDaniel Stenberg <daniel@haxx.se>2019-06-10 13:07:32 +0200
commitf0b7b106ff409f0128dc7bb0f435b37891f297fd (patch)
tree24f2ae3e247e0a1a5be94933b247ba71af31d1d3 /docs
parent4da5794d81521d7fe363479255a891bb56a19f60 (diff)
CURLMOPT_SOCKETFUNCTION.3: clarified
Moved away the callback explanation from curl_multi_socket_action.3 and expanded it somewhat. Closes #4006
Diffstat (limited to 'docs')
-rw-r--r--docs/libcurl/curl_multi_socket_action.376
-rw-r--r--docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.326
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: