From fa18d6fb76253c4800b5ef2e052a8a39e210e59d Mon Sep 17 00:00:00 2001
From: Daniel Stenberg <daniel@haxx.se>
Date: Mon, 2 Jan 2006 22:58:56 +0000
Subject: [PATCH] I removed the timeout argument from the socket callback and
 did some other cleanups of this man page. The lengthy description has now
 also been removed from curl/multi.h since it immediately got tedious to
 maintain the info on two places when I did major updates...

---
 docs/libcurl/curl_multi_socket.3 | 40 ++++++++++++++++++++------------
 1 file changed, 25 insertions(+), 15 deletions(-)

diff --git a/docs/libcurl/curl_multi_socket.3 b/docs/libcurl/curl_multi_socket.3
index 8c42a8db1..fb118eb65 100644
--- a/docs/libcurl/curl_multi_socket.3
+++ b/docs/libcurl/curl_multi_socket.3
@@ -2,7 +2,7 @@
 .\"
 .TH curl_multi_socket 3 "21 Dec 2005" "libcurl 7.16.0" "libcurl Manual"
 .SH NAME
-curl_multi_socket - reads/writes available data
+curl_multi_socket \- reads/writes available data
 .SH SYNOPSIS
 #include <curl/curl.h>
 
@@ -32,23 +32,31 @@ status with changes since the previous time this function was used. If
 \fBcallback\fP is NULL, no callback will be called. A status change may also
 be a new timeout only, having the same IN/OUT status as before.
 
-If a previous wait for socket action(s) timed out, you should call this
-function with the socket argument set to CURL_SOCKET_TIMEOUT. If you want to
-force libcurl to (re-)check all its internal sockets, and call the callback
-with status for all sockets no matter what the previous state is, you call
-curl_multi_socket_all() instead.
+If you want 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 instead.
 
-curl_multi_perform() is the equivalent of calling
-curl_multi_socket_all(handle, NULL, NULL);
+An application should call \fBcurl_multi_timeout(3)\fP to figure out how long
+it should wait for socket actions \- at most \- before doing the timeout
+action: call the \fBcurl_multi_socket(3)\fP function with the \fBsockfd\fP
+argument set to CURL_SOCKET_TIMEOUT and the \fBeasy\fP argument set to
+CURL_EASY_TIMEOUT.
 
-Regarding the timeout argument in the callback: it is the timeout (in
-milliseconds) for waiting on action on this socket (and the given time period
-starts when the callback is called) until you should call curl_multi_socket()
-with the timeout stuff mentioned above. If "actions" happens on the socket
-before the timeout happens, remember that the timout timer keeps ticking until
-told otherwise.
+\fBcurl_multi_perform(3)\fP is the exact equivalent of calling
+\fBcurl_multi_socket_all\fP(handle, NULL, NULL);
 
-The "what" argument has one of five values:
+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" pointer */
+
+.fi
+The callback MUST return 0.
+
+The \fIaction\fP (third) argument to the callback has one of five values:
 .RS
 .IP "CURL_POLL_NONE (0)"
 register, not interested in readiness (yet)
@@ -77,6 +85,8 @@ function returns OK.
 Call curl_multi_socket_all() first. Setup a "collection" of sockets to
 supervise, then when action happens call curl_multi_socket() for the easy
 handle that got the action.
+.SH AVAILABILITY
+This function was added in libcurl 7.16.0
 .SH "SEE ALSO"
 .BR curl_multi_cleanup "(3), " curl_multi_init "(3), "
 .BR curl_multi_fdset "(3), " curl_multi_info_read "(3)"