- Robert Iakobashvil added curl_multi_socket_action() to libcurl, which is a

                                  Changelog

Daniel S (16 April 2007)

- Robert Iakobashvil added curl_multi_socket_action() to libcurl, which is a

  function that deprecates the curl_multi_socket() function. Using the new

  function the application tell libcurl what action that was found in the

  socket that it passes in. This gives a significant performance boost as it

  allows libcurl to avoid a call to poll()/select() for every call to

  curl_multi_socket*().

Daniel S (14 April 2007)

- Jay Austin added "DH PARAMETERS" to the stunnel.pem certificate for the test

  suite to make stunnel run better in some (most?) environments.

This release includes the following changes:

 o 

 o Added curl_multi_socket_action()

 o Deprecated curl_multi_socket()

This release includes the following bugfixes:

This release would not have looked like this without help, code, reports and

advice from friends like these:

 Song Ma, Dan Fandrich, Yang Tse, Jay Austin

 Song Ma, Dan Fandrich, Yang Tse, Jay Austin, Robert Iakobashvil

        Thanks! (and sorry if I forgot to mention someone)

.SH NAME

curl_multi_socket \- reads/writes available data

.SH SYNOPSIS

.nf

#include <curl/curl.h>

CURLMcode curl_multi_socket_action(CURLM * multi_handle, 

                                   curl_socket_t sockfd, int ev_bitmask,

                                   int *running_handles);

CURLMcode curl_multi_socket(CURLM * multi_handle, curl_socket_t sockfd,

                            int *running_handles);

CURLMcode curl_multi_socket_all(CURLM *multi_handle,

                                int *running_handles);

.fi

.SH DESCRIPTION

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.

application to pass in the file descriptor/socket that has been detected to

have \&"action" on it 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_action(3)\fP with the \fBsockfd\fP argument set to the

socket with the action. When the events on a socket are known, they can be

passed as an events bitmask \fBev_bitmask\fP by first setting \fBev_bitmask\fP

to 0, and then adding using bitwise OR (|) any combination of events to be

choosen from CURL_CSELECT_IN, CURL_CSELECT_OUT or CURL_CSELECT_ERR. When the

events on a socket are unknown, pass 0 instead, and libcurl will test the

descriptor internally.

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.

\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 curl_multi_socket functions inform the application about updates in the

socket (file descriptor) status by doing none, one or multiple calls to the

the \fBcurl_multi_socket(3)\fP function with the \fBsockfd\fP argument set to

CURL_SOCKET_TIMEOUT.

Usage of \fIcurl_multi_socket(3)\fP is depricated, whereas the function is

equivalent to \fIcurl_multi_socket_action(3)\fP, when \fBev_bitmask\fP is set 

to 0.

.SH "CALLBACK DETAILS"

The socket \fBcallback\fP function uses a prototype like this

7. Wait for action on any of libcurl's sockets

8, When action happens, call curl_multi_socket() for the socket(s) that got

8, When action happens, call curl_multi_socket_action() for the socket(s) that got

action.

9. Go back to step 6.

.SH AVAILABILITY

This function was added in libcurl 7.15.4, although not deemed stable yet.

This function was added in libcurl 7.15.4, although deemed stablesince 7.16.0.

\fIcurl_multi_socket(3)\fP is deprecated, use

\fIcurl_multi_socket_action(3)\fP instead!

.SH "SEE ALSO"

.BR curl_multi_cleanup "(3), " curl_multi_init "(3), "

.BR curl_multi_fdset "(3), " curl_multi_info_read "(3)"

 *                            | (__| |_| |  _ <| |___

 *                             \___|\___/|_| \_\_____|

 *

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

 * Copyright (C) 1998 - 2007, 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

#define CURL_SOCKET_TIMEOUT CURL_SOCKET_BAD

#define CURL_CSELECT_IN   0x01

#define CURL_CSELECT_OUT  0x02

#define CURL_CSELECT_ERR  0x04

typedef int (*curl_socket_callback)(CURL *easy,      /* easy handle */

                                    curl_socket_t s, /* socket */

                                    int what,        /* see above */

CURL_EXTERN CURLMcode curl_multi_socket(CURLM *multi_handle, curl_socket_t s,

                                        int *running_handles);

CURL_EXTERN CURLMcode curl_multi_socket_action(CURLM *multi_handle,

                                               curl_socket_t s,

                                               int ev_bitmask,

                                               int *running_handles);

CURL_EXTERN CURLMcode curl_multi_socket_all(CURLM *multi_handle,

                                            int *running_handles);

#ifndef CURL_ALLOW_OLD_MULTI_SOCKET

/* This macro below was added in 7.16.3 to push users who recompile to use

   the new curl_multi_socket_action() instead of the old curl_multi_socket()

*/

#define curl_multi_socket(x,y,z) curl_multi_socket_action(x,y,0,z)

#endif

/*

 * Name:    curl_multi_timeout()

 *

    /* timeout, no connect today */

    return WAITCONN_TIMEOUT;

  if(rc & CSELECT_ERR)

  if(rc & CURL_CSELECT_ERR)

    /* error condition caught */

    return WAITCONN_FDSET_ERROR;