curl_multi_socket(3)      libcurl Manual     curl_multi_socket(3)



NAME
       curl_multi_socket - reads/writes available data

SYNOPSIS
       #include 

       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
       Alternative versions of curl_multi_perform(3) that  allows
       the  application  to  pass  in  one  of  the file descrip-
       tors/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
       curl_multi_socket(3)  with  the sockfd argument set to the
       socket with the action.

       At return, the int running_handles 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
       curl_multi_socket(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  functions  inform  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 CURLMOPT_SOCKETFUNCTION option to
       curl_multi_setopt(3). They update the status with  changes
       since the previous time this function was called.

       To  force  libcurl  to (re-)check all its internal sockets
       and transfers instead of  just  a  single  one,  you  call
       curl_multi_socket_all(3).  This  is  typically done as the
       first function call before the application has any  knowl-
       edge about what sockets libcurl uses.

       Applications  should  call curl_multi_timeout(3) to figure
       out how long to wait for socket actions - at most - before
       doing  the  timeout  action: call the curl_multi_socket(3)
       function with the sockfd argument set to CURL_SOCKET_TIME-
       OUT.


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 han-
       dle 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  val-
       ues:

              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
                     readiness

              CURL_POLL_REMOVE (4)
                     deregister

       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 previ-
       ously set with curl_multi_setopt(3) and the CURLMOPT_SOCK-
       ETDATA option.

RETURN VALUE
       CURLMcode  type,  general  libcurl  multi  interface error
       code.

       If you receive  CURLM_CALL_MULTI_PERFORM,  this  basically
       means  that  you  should  call  curl_multi_perform  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 "sat-
       isfied".

       NOTE that this only returns errors etc regarding the whole
       multi  stack.  There might still have occurred problems on
       individual transfers even when this function returns OK.

TYPICAL USAGE
       1. Create a multi handle

       2. Set the socket callback with CURLMOPT_SOCKETFUNCTION

       3. Add easy handles

       4. Call curl_multi_socket_all() first once

       5. Setup a "collection" of sockets to supervise when  your
       socket callback is called.

       6. Use curl_multi_timeout() to figure out how long to wait
       for action

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

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

       9. Go back to step 6.

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

SEE ALSO
       curl_multi_cleanup(3),                 curl_multi_init(3),
       curl_multi_fdset(3), curl_multi_info_read(3)



libcurl 7.16.0              9 Jul 2006       curl_multi_socket(3)