.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2017, 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.
+.\" * are also available at https://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
.\" *
.\" **************************************************************************
.\"
-.TH CURLMOPT_PIPELINING 3 "17 Jun 2014" "libcurl 7.37.0" "curl_multi_setopt options"
+.TH CURLMOPT_PIPELINING 3 "May 27, 2017" "libcurl 7.59.0" "curl_multi_setopt options"
+
.SH NAME
-CURLMOPT_PIPELINING \- enable/disable HTTP pipelining
+CURLMOPT_PIPELINING \- enable HTTP pipelining and multiplexing
.SH SYNOPSIS
#include <curl/curl.h>
-CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PIPELINING, bool onoff);
+CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PIPELINING, long bitmask);
.SH DESCRIPTION
-Set the \fBonoff\fP parameter to 1 to make libcurl use HTTP pipelining for
-HTTP transfers done using this multi handle, as far as possible. 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.
-
-When using pipelining, there are also several other related options that are
-interesting to tweak and adjust to alter how libcurl spreads out requests on
-different connections or not etc.
+Pass in the \fBbitmask\fP parameter to instruct libcurl to enable HTTP
+pipelining and/or HTTP/2 multiplexing for this multi handle.
+
+When enabled, libcurl will attempt to use those protocol features when doing
+parallel requests to the same hosts.
+
+For pipelining, 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.
+
+For multiplexing, this means that follow-up requests can re-use an existing
+connection and send the new request multiplexed over that at the same time as
+other transfers are already using that single connection.
+
+There are several other related options that are interesting to tweak and
+adjust to alter how libcurl spreads out requests on different connections or
+not etc.
+
+Before 7.43.0, this option was set to 1 and 0 to enable and disable HTTP/1.1
+pipelining.
+
+Starting in 7.43.0, \fBbitmask\fP's second bit also has a meaning, and you can
+ask for pipelining and multiplexing independently of each other by toggling
+the correct bits.
+.IP CURLPIPE_NOTHING (0)
+Default, which means doing no attempts at pipelining or multiplexing.
+.IP CURLPIPE_HTTP1 (1)
+If this bit is set, libcurl will try to pipeline HTTP/1.1 requests on
+connections that are already established and in use to hosts.
+.IP CURLPIPE_MULTIPLEX (2)
+If this bit is set, libcurl will try to multiplex the new transfer over an
+existing connection if possible. This requires HTTP/2.
.SH DEFAULT
-0 (off)
+0 (both pipeline and multiplexing are off)
.SH PROTOCOLS
HTTP(S)
.SH EXAMPLE
-TODO
+.nf
+CURLM *m = curl_multi_init();
+/* try HTTP/1 pipelining and HTTP/2 multiplexing */
+curl_multi_setopt(m, CURLMOPT_PIPELINING, CURLPIPE_HTTP1 |
+ CURLPIPE_MULTIPLEX);
+.fi
.SH AVAILABILITY
-Added in 7.16.0
+Added in 7.16.0. Multiplex support bit added in 7.43.0.
.SH RETURN VALUE
Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
projects / platform / upstream / curl.git / blobdiff