multi docs: extended the multi_socket API description

.\" *                            | (__| |_| |  _ <| |___

.\" *                             \___|\___/|_| \_\_____|

.\" *

.\" * Copyright (C) 1998 - 2010, Daniel Stenberg, <daniel@haxx.se>, et al.

.\" * Copyright (C) 1998 - 2011, 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

transfer, you must first remove it from the multi stack and then re-add it

again (possibly after having altered some options at your own choice).

.SH "MULTI_SOCKET"

Since 7.16.0, the \fIcurl_multi_socket_action(3)\fP function offers a way for

applications to not only avoid being forced to use select(), but it also

offers a much more high-performance API that will make a significant

difference for applications using large numbers of simultaneous connections.

\fIcurl_multi_socket_action(3)\fP is then used

instead of \fIcurl_multi_perform(3)\fP.

\fIcurl_multi_socket_action(3)\fP function offers a way for applications to

not only avoid being forced to use select(), but it also offers a much more

high-performance API that will make a significant difference for applications

using large numbers of simultaneous connections.

\fIcurl_multi_socket_action(3)\fP is then used instead of

\fIcurl_multi_perform(3)\fP.

When using this API, you add easy handles to the multi handle just as with the

normal multi interface. Then you also set two callbacks with the

CURLMOPT_SOCKETFUNCTION and CURLMOPT_TIMERFUNCTION options to

\fIcurl_multi_setopt(3)\fP.

The API is then designed to inform your application about which sockets

libcurl is currently using and for what activities (read and/or write) on

those sockets your application is expected to wait for.

Your application must then make sure to receive all sockets informed about in

the CURLMOPT_SOCKETFUNCTION callback and make sure it reacts on the given

activity on them. When a socket has the given activity, you call

\fIcurl_multi_socket_action(3)\fP specifying which socket and action there

are.

The CURLMOPT_TIMERFUNCTION callback is called to set a timeout. When that

timeout expires, your application should call the

\fIcurl_multi_socket_action(3)\fP function saying it was due to a timeout.

.SH "BLOCKING"

A few areas in the code are still using blocking code, even when used from the

multi interface. While we certainly want and intend for these to get fixed in