Annotation of embedaddon/curl/docs/libcurl/curl_multi_socket.3, revision 1.1
1.1 ! misho 1: .\" **************************************************************************
! 2: .\" * _ _ ____ _
! 3: .\" * Project ___| | | | _ \| |
! 4: .\" * / __| | | | |_) | |
! 5: .\" * | (__| |_| | _ <| |___
! 6: .\" * \___|\___/|_| \_\_____|
! 7: .\" *
! 8: .\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al.
! 9: .\" *
! 10: .\" * This software is licensed as described in the file COPYING, which
! 11: .\" * you should have received as part of this distribution. The terms
! 12: .\" * are also available at https://curl.haxx.se/docs/copyright.html.
! 13: .\" *
! 14: .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
! 15: .\" * copies of the Software, and permit persons to whom the Software is
! 16: .\" * furnished to do so, under the terms of the COPYING file.
! 17: .\" *
! 18: .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
! 19: .\" * KIND, either express or implied.
! 20: .\" *
! 21: .\" **************************************************************************
! 22: .TH curl_multi_socket 3 "June 30, 2018" "libcurl 7.70.0" "libcurl Manual"
! 23:
! 24: .SH NAME
! 25: curl_multi_socket \- reads/writes available data
! 26: .SH SYNOPSIS
! 27: .nf
! 28: #include <curl/curl.h>
! 29: CURLMcode curl_multi_socket(CURLM * multi_handle, curl_socket_t sockfd,
! 30: int *running_handles);
! 31:
! 32: CURLMcode curl_multi_socket_all(CURLM *multi_handle,
! 33: int *running_handles);
! 34: .fi
! 35: .SH DESCRIPTION
! 36: These functions are deprecated. Do not use! See
! 37: \fIcurl_multi_socket_action(3)\fP instead!
! 38:
! 39: At return, the integer \fBrunning_handles\fP points to will contain the number
! 40: of still running easy handles within the multi handle. When this number
! 41: reaches zero, all transfers are complete/done. Note that when you call
! 42: \fIcurl_multi_socket_action(3)\fP on a specific socket and the counter
! 43: decreases by one, it DOES NOT necessarily mean that this exact socket/transfer
! 44: is the one that completed. Use \fIcurl_multi_info_read(3)\fP to figure out
! 45: which easy handle that completed.
! 46:
! 47: The \fIcurl_multi_socket_action(3)\fP functions inform the application about
! 48: updates in the socket (file descriptor) status by doing none, one, or multiple
! 49: calls to the socket callback function set with the
! 50: \fICURLMOPT_SOCKETFUNCTION(3)\fP option to \fIcurl_multi_setopt(3)\fP. They
! 51: update the status with changes since the previous time the callback was
! 52: called.
! 53:
! 54: Get the timeout time by setting the \fICURLMOPT_TIMERFUNCTION(3)\fP option
! 55: with \fIcurl_multi_setopt(3)\fP. Your application will then get called with
! 56: information on how long to wait for socket actions at most before doing the
! 57: timeout action: call the \fIcurl_multi_socket_action(3)\fP function with the
! 58: \fBsockfd\fP argument set to CURL_SOCKET_TIMEOUT. You can also use the
! 59: \fIcurl_multi_timeout(3)\fP function to poll the value at any given time, but
! 60: for an event-based system using the callback is far better than relying on
! 61: polling the timeout value.
! 62:
! 63: Usage of \fIcurl_multi_socket(3)\fP is deprecated, whereas the function is
! 64: equivalent to \fIcurl_multi_socket_action(3)\fP with \fBev_bitmask\fP set to
! 65: 0.
! 66:
! 67: Force libcurl to (re-)check all its internal sockets and transfers instead of
! 68: just a single one by calling \fIcurl_multi_socket_all(3)\fP. Note that there
! 69: should not be any reason to use this function!
! 70: .SH "CALLBACK DETAILS"
! 71:
! 72: The socket \fBcallback\fP function uses a prototype like this
! 73: .nf
! 74:
! 75: int curl_socket_callback(CURL *easy, /* easy handle */
! 76: curl_socket_t s, /* socket */
! 77: int action, /* see values below */
! 78: void *userp, /* private callback pointer */
! 79: void *socketp); /* private socket pointer */
! 80:
! 81: .fi
! 82: The callback MUST return 0.
! 83:
! 84: The \fIeasy\fP argument is a pointer to the easy handle that deals with this
! 85: particular socket. Note that a single handle may work with several sockets
! 86: simultaneously.
! 87:
! 88: The \fIs\fP argument is the actual socket value as you use it within your
! 89: system.
! 90:
! 91: The \fIaction\fP argument to the callback has one of five values:
! 92: .RS
! 93: .IP "CURL_POLL_NONE (0)"
! 94: register, not interested in readiness (yet)
! 95: .IP "CURL_POLL_IN (1)"
! 96: register, interested in read readiness
! 97: .IP "CURL_POLL_OUT (2)"
! 98: register, interested in write readiness
! 99: .IP "CURL_POLL_INOUT (3)"
! 100: register, interested in both read and write readiness
! 101: .IP "CURL_POLL_REMOVE (4)"
! 102: unregister
! 103: .RE
! 104:
! 105: The \fIsocketp\fP argument is a private pointer you have previously set with
! 106: \fIcurl_multi_assign(3)\fP to be associated with the \fIs\fP socket. If no
! 107: pointer has been set, socketp will be NULL. This argument is of course a
! 108: service to applications that want to keep certain data or structs that are
! 109: strictly associated to the given socket.
! 110:
! 111: The \fIuserp\fP argument is a private pointer you have previously set with
! 112: \fIcurl_multi_setopt(3)\fP and the \fICURLMOPT_SOCKETDATA(3)\fP option.
! 113: .SH "RETURN VALUE"
! 114: CURLMcode type, general libcurl multi interface error code.
! 115:
! 116: Legacy: If you receive \fICURLM_CALL_MULTI_PERFORM\fP, this basically means
! 117: that you should call \fIcurl_multi_socket(3)\fP again, before you wait for
! 118: more actions on libcurl's sockets. You don't have to do it immediately, but
! 119: the return code means that libcurl may have more data available to return or
! 120: that there may be more data to send off before it is "satisfied".
! 121:
! 122: In modern libcurls, \fICURLM_CALL_MULTI_PERFORM\fP or
! 123: \fICURLM_CALL_MULTI_SOCKET\fP should not be returned and no application needs
! 124: to care about them.
! 125:
! 126: NOTE that the return code is for the whole multi stack. Problems still might have
! 127: occurred on individual transfers even when one of these functions
! 128: return OK.
! 129: .SH "TYPICAL USAGE"
! 130: 1. Create a multi handle
! 131:
! 132: 2. Set the socket callback with \fICURLMOPT_SOCKETFUNCTION(3)\fP
! 133:
! 134: 3. Set the timeout callback with \fICURLMOPT_TIMERFUNCTION(3)\fP, to get to
! 135: know what timeout value to use when waiting for socket activities.
! 136:
! 137: 4. Add easy handles with curl_multi_add_handle()
! 138:
! 139: 5. Provide some means to manage the sockets libcurl is using, so you can check
! 140: them for activity. This can be done through your application code, or by way
! 141: of an external library such as libevent or glib.
! 142:
! 143: 6. Wait for activity on any of libcurl's sockets, use the timeout value your
! 144: callback has been told
! 145:
! 146: 7, When activity is detected, call curl_multi_socket_action() for the
! 147: socket(s) that got action. If no activity is detected and the timeout expires,
! 148: call \fIcurl_multi_socket_action(3)\fP with \fICURL_SOCKET_TIMEOUT\fP
! 149:
! 150: 8. Go back to step 6.
! 151: .SH AVAILABILITY
! 152: This function was added in libcurl 7.15.4, and is deemed stable since
! 153: 7.16.0.
! 154:
! 155: \fIcurl_multi_socket(3)\fP is deprecated, use
! 156: \fIcurl_multi_socket_action(3)\fP instead!
! 157: .SH "SEE ALSO"
! 158: .BR curl_multi_cleanup "(3), " curl_multi_init "(3), "
! 159: .BR curl_multi_fdset "(3), " curl_multi_info_read "(3), "
! 160: .BR "the hiperfifo.c example"
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to curl_multi_socket.3 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / curl / docs / libcurl