DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

curl_multi_socket_all(3)




curl_multi_socket(3)     libcurl Manual      curl_multi_socket(3)


NAME

     curl_multi_socket - reads/writes available data


SYNOPSIS

     #include <curl/curl.h>
     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);


DESCRIPTION

     These  functions   are   deprecated.   Do   not   use!   See
     curl_multi_socket_action(3) instead!

     At return, the integer running_handles points to  will  con-
     tain  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
     curl_multi_socket_action(3) 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
     curl_multi_info_read(3) to figure out which easy handle that
     completed.

     The curl_multi_socket_action(3) functions inform the  appli-
     cation  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
     curl_multi_setopt(3). They update the  status  with  changes
     since the previous time the callback was called.

     Get the timeout time by setting  the  CURLMOPT_TIMERFUNCTION
     option with curl_multi_setopt(3). Your application will then
     get called with information on how long to wait  for  socket
     actions  at  most  before doing the timeout action: call the
     curl_multi_socket_action(3) function with the  sockfd  argu-
     ment  set  to  CURL_SOCKET_TIMEOUT.  You  can  also  use the
     curl_multi_timeout(3) 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.

     Usage of curl_multi_socket(3)  is  deprecated,  whereas  the
     function  is  equivalent to curl_multi_socket_action(3) with
     ev_bitmask set to 0.

     Force libcurl to (re-)check all  its  internal  sockets  and
     transfers   instead   of   just  a  single  one  by  calling
     curl_multi_socket_all(3). Note that there should not be  any
     reason to use this function!

libcurl 7.58.0   Last change: December 15, 2016                 1

curl_multi_socket(3)     libcurl Manual      curl_multi_socket(3)


CALLBACK DETAILS

     The socket callback function uses a prototype like this

       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 */

     The callback MUST return 0.

     The easy 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 s argument is the actual socket  value  as  you  use  it
     within your system.

     The action argument to the callback has one of five values:

          CURL_POLL_NONE (0)
               register, not interested in readiness (yet)

          CURL_POLL_IN (1)
               register, interested in read readiness

          CURL_POLL_OUT (2)
               register, interested in write readiness

          CURL_POLL_INOUT (3)
               register, interested in both read and write readi-
               ness

          CURL_POLL_REMOVE (4)
               unregister

     The socketp argument is a private pointer  you  have  previ-
     ously  set  with  curl_multi_assign(3) to be associated with
     the s 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 userp argument is a private pointer you have  previously
     set  with  curl_multi_setopt(3)  and the CURLMOPT_SOCKETDATA
     option.


RETURN VALUE

     CURLMcode type, general libcurl multi interface error code.

     Legacy: If you receive CURLM_CALL_MULTI_PERFORM, this  basi-
     cally means that you should call curl_multi_socket(3) again,

libcurl 7.58.0   Last change: December 15, 2016                 2

curl_multi_socket(3)     libcurl Manual      curl_multi_socket(3)

     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".

     In    modern    libcurls,    CURLM_CALL_MULTI_PERFORM     or
     CURLM_CALL_MULTI_SOCKET should not be returned and no appli-
     cation needs to care about them.

     NOTE that the return code is  for  the  whole  multi  stack.
     Problems  still  might have occurred on individual transfers
     even when one of these functions return OK.


TYPICAL USAGE

     1. Create a multi handle

     2. Set the socket callback with CURLMOPT_SOCKETFUNCTION

     3. Set the timeout callback with CURLMOPT_TIMERFUNCTION,  to
     get  to  know  what  timeout  value  to use when waiting for
     socket activities.

     4. Add easy handles with curl_multi_add_handle()

     5. Provide some means  to  manage  the  sockets  libcurl  is
     using,  so you can check them for activity. This can be done
     through your application code, or  by  way  of  an  external
     library such as libevent or glib.

     6. Wait for activity on any of libcurl's  sockets,  use  the
     timeout value your callback has been told

     7,      When      activity      is      detected,       call
     curl_multi_socket_action()   for   the  socket(s)  that  got
     action. If no activity is detected and the timeout  expires,
     call curl_multi_socket_action(3) with CURL_SOCKET_TIMEOUT

     8. Go back to step 6.


AVAILABILITY

     This function was added in libcurl  7.15.4,  and  is  deemed
     stable since 7.16.0.

     curl_multi_socket(3)        is        deprecated,        use
     curl_multi_socket_action(3) instead!


SEE ALSO

     curl_multi_cleanup(3),                   curl_multi_init(3),
     curl_multi_fdset(3),       curl_multi_info_read(3),      the
     hiperfifo.c example

libcurl 7.58.0   Last change: December 15, 2016                 3


Man(1) output converted with man2html