curlmultisocket(3) libcurl Manual curlmultisocket(3)

NAME
       curlmultisocket - reads/writes available data

SYNOPSIS
       #include 

       CURLMcode curlmultisocketaction(CURLM * multihandle,
                                          curlsockett sockfd, int evbitmask,
                                          int *runninghandles);

       CURLMcode curlmultisocket(CURLM * multihandle, curlsockett sockfd,
                                   int *runninghandles);

       CURLMcode curlmultisocketall(CURLM *multihandle,
                                       int *runninghandles);

DESCRIPTION
       Alternative  versions of curlmultiperform(3) that allows the applica-
       tion 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  curlmultisocketaction(3)  with  the  ssoocckkffdd
       argument set to the socket with the action. When the events on a socket
       are known, they can be passed as an events bitmask eevvbbiittmmaasskk by  first
       setting  eevvbbiittmmaasskk to 0, and then adding using bitwise OR (|) any com-
       bination of events to be choosen from CURLCSELECTIN, CURLCSELECTOUT
       or  CURLCSELECTERR.  When  the events on a socket are unknown, pass 0
       instead, and libcurl will test the descriptor internally.

       At return, the int rruunnnniinngghhaannddlleess 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
       curlmultisocketaction(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 curlmultiinforead(3)
       to figure out which easy handle that completed.

       The curlmultisocket 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 CURLMOPTSOCKETFUNC-
       TION  option  to  curlmultisetopt(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 ccuurrllmmuullttiissoocckkeettaallll((33)). This
       is typically done as the first function call before the application has
       any knowledge about what sockets libcurl uses.

       Applications  should  call ccuurrllmmuullttiittiimmeeoouutt((33)) to figure out how long
       to wait for socket actions - at most - before doing the timeout action:
       call  the ccuurrllmmuullttiissoocckkeett((33)) function with the ssoocckkffdd argument set to
       CURLSOCKETTIMEOUT.

       Usage of curlmultisocket(3) is depricated, whereas  the  function  is
       equivalent to curlmultisocketaction(3), when eevvbbiittmmaasskk is set to 0.


CCAALLLLBBAACCKK DDEETTAAIILLSS
       The socket ccaallllbbaacckk function uses a prototype like this

         int curlsocketcallback(CURL *easy,      /* easy handle */
                                  curlsockett 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:

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

              CURLPOLLIN (1)
                     register, interested in read readiness

              CURLPOLLOUT (2)
                     register, interested in write readiness

              CURLPOLLINOUT (3)
                     register, interested in both read and write readiness

              CURLPOLLREMOVE (4)
                     deregister

       The  socketp argument is a private pointer you have previously set with
       curlmultiassign(3) to be associated with the s socket. If no  pointer
       has  been  set, socketp will be NULL. This argument is of course a ser-
       vice 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
       curlmultisetopt(3) and the CURLMOPTSOCKETDATA option.

RREETTUURRNN VVAALLUUEE
       CURLMcode type, general libcurl multi interface error code.

       If you receive CURLMCALLMULTIPERFORM, this basically means that  you
       should  call curlmultiperform 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 "satisfied".

       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.

TTYYPPIICCAALL UUSSAAGGEE
       1. Create a multi handle

       2. Set the socket callback with CURLMOPTSOCKETFUNCTION

       3. Add easy handles

       4. Call curlmultisocketall() first once

       5. Setup a "collection" of sockets to supervise when your socket  call-
       back is called.

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

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

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

       9. Go back to step 6.

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

       curlmultisocket(3)  is  deprecated,  use  curlmultisocketaction(3)
       instead!

SEE ALSO
       ccuurrllmmuullttiicclleeaannuupp(3),     ccuurrllmmuullttiiiinniitt(3),     ccuurrllmmuullttiiffddsseett(3),
       ccuurrllmmuullttiiiinnffoorreeaadd(3)



libcurl 7.16.0                    9 Jul 2006              curlmultisocket(3)