Annotation of embedaddon/curl/docs/libcurl/curl_multi_socket.3, revision 1.1.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