| .\" ************************************************************************** |
| .\" * _ _ ____ _ |
| .\" * Project ___| | | | _ \| | |
| .\" * / __| | | | |_) | | |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| .\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. |
| .\" * |
| .\" * This software is licensed as described in the file COPYING, which |
| .\" * you should have received as part of this distribution. The terms |
| .\" * are also available at http://curl.haxx.se/docs/copyright.html. |
| .\" * |
| .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell |
| .\" * copies of the Software, and permit persons to whom the Software is |
| .\" * furnished to do so, under the terms of the COPYING file. |
| .\" * |
| .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY |
| .\" * KIND, either express or implied. |
| .\" * |
| .\" ************************************************************************** |
| .TH curl_multi_setopt 3 "10 Oct 2006" "libcurl 7.16.0" "libcurl Manual" |
| .SH NAME |
| curl_multi_setopt \- set options for a curl multi handle |
| .SH SYNOPSIS |
| #include <curl/curl.h> |
| |
| CURLMcode curl_multi_setopt(CURLM * multi_handle, CURLMoption option, param); |
| .SH DESCRIPTION |
| curl_multi_setopt() is used to tell a libcurl multi handle how to behave. By |
| using the appropriate options to \fIcurl_multi_setopt(3)\fP, you can change |
| libcurl's behaviour when using that multi handle. All options are set with |
| the \fIoption\fP followed by the parameter \fIparam\fP. That parameter can be |
| a \fBlong\fP, a \fBfunction pointer\fP, an \fBobject pointer\fP or a |
| \fBcurl_off_t\fP type, depending on what the specific option expects. Read |
| this manual carefully as bad input values may cause libcurl to behave badly! |
| You can only set one option in each function call. |
| |
| .SH OPTIONS |
| .IP CURLMOPT_SOCKETFUNCTION |
| Pass a pointer to a function matching the \fBcurl_socket_callback\fP |
| prototype. The \fIcurl_multi_socket_action(3)\fP function informs the |
| application about updates in the socket (file descriptor) status by doing |
| none, one, or multiple calls to the curl_socket_callback given in the |
| \fBparam\fP argument. They update the status with changes since the previous |
| time a \fIcurl_multi_socket(3)\fP function was called. If the given callback |
| pointer is NULL, no callback will be called. Set the callback's \fBuserp\fP |
| argument with \fICURLMOPT_SOCKETDATA\fP. See \fIcurl_multi_socket(3)\fP for |
| more callback details. |
| .IP CURLMOPT_SOCKETDATA |
| Pass a pointer to whatever you want passed to the \fBcurl_socket_callback\fP's |
| forth argument, the userp pointer. This is not used by libcurl but only |
| passed-thru as-is. Set the callback pointer with |
| \fICURLMOPT_SOCKETFUNCTION\fP. |
| .IP CURLMOPT_PIPELINING |
| Pass a long set to 1 to enable or 0 to disable. Enabling pipelining on a multi |
| handle will make it attempt to perform HTTP Pipelining as far as possible for |
| transfers using this handle. This means that if you add a second request that |
| can use an already existing connection, the second request will be \&"piped" |
| on the same connection rather than being executed in parallel. (Added in |
| 7.16.0) |
| .IP CURLMOPT_TIMERFUNCTION |
| Pass a pointer to a function matching the \fBcurl_multi_timer_callback\fP |
| prototype. This function will then be called when the timeout value |
| changes. The timeout value is at what latest time the application should call |
| one of the \&"performing" functions of the multi interface |
| (\fIcurl_multi_socket_action(3)\fP and \fIcurl_multi_perform(3)\fP) - to allow |
| libcurl to keep timeouts and retries etc to work. A timeout value of -1 means |
| that there is no timeout at all, and 0 means that the timeout is already |
| reached. Libcurl attempts to limit calling this only when the fixed future |
| timeout time actually changes. See also \fICURLMOPT_TIMERDATA\fP. This |
| callback can be used instead of, or in addition to, |
| \fIcurl_multi_timeout(3)\fP. (Added in 7.16.0) |
| .IP CURLMOPT_TIMERDATA |
| Pass a pointer to whatever you want passed to the |
| \fBcurl_multi_timer_callback\fP's third argument, the userp pointer. This is |
| not used by libcurl but only passed-thru as-is. Set the callback pointer with |
| \fICURLMOPT_TIMERFUNCTION\fP. (Added in 7.16.0) |
| .IP CURLMOPT_MAXCONNECTS |
| Pass a long. The set number will be used as the maximum amount of |
| simultaneously open connections that libcurl may cache. Default is 10, and |
| libcurl will enlarge the size for each added easy handle to make it fit 4 |
| times the number of added easy handles. |
| |
| By setting this option, you can prevent the cache size from growing beyond the |
| limit set by you. |
| |
| When the cache is full, curl closes the oldest one in the cache to prevent the |
| number of open connections from increasing. |
| |
| This option is for the multi handle's use only, when using the easy interface |
| you should instead use the \fICURLOPT_MAXCONNECTS\fP option. |
| |
| (Added in 7.16.3) |
| .SH RETURNS |
| The standard CURLMcode for multi interface error codes. Note that it returns a |
| CURLM_UNKNOWN_OPTION if you try setting an option that this version of libcurl |
| doesn't know of. |
| .SH AVAILABILITY |
| This function was added in libcurl 7.15.4. |
| .SH "SEE ALSO" |
| .BR curl_multi_cleanup "(3), " curl_multi_init "(3), " |
| .BR curl_multi_socket "(3), " curl_multi_info_read "(3)" |
