Go to main content

man pages section 3: Library Interfaces and Headers

Exit Print View

Updated: Thursday, June 13, 2019
 
 

CURLOPT_STREAM_WEIGHT (3)

Name

CURLOPT_STREAM_WEIGHT - set numerical stream weight

Synopsis

#include <curl/curl.h>

CURLcode  curl_easy_setopt(CURL  *handle,  CURLOPT_STREAM_WEIGHT,  long
weight);

Description

CURLOPT_STREAM_WEIGHT(3)   curl_easy_setopt options   CURLOPT_STREAM_WEIGHT(3)



NAME
       CURLOPT_STREAM_WEIGHT - set numerical stream weight

SYNOPSIS
       #include <curl/curl.h>

       CURLcode  curl_easy_setopt(CURL  *handle,  CURLOPT_STREAM_WEIGHT,  long
       weight);

DESCRIPTION
       Set the long weight to a number between 1 and 256.

       When using HTTP/2, this option sets the individual weight for this par-
       ticular  stream used by the easy handle. Setting and using weights only
       makes sense and is only usable when doing  multiple  streams  over  the
       same  connections,  which  thus  implies that you use CURLMOPT_PIPELIN-
       ING(3).

       This option can be set during transfer and will then cause the  updated
       weight  info  get  sent  to the server the next time an HTTP/2 frame is
       sent to the server.

       See   section   5.3    of    RFC    7540    for    protocol    details:
       https://httpwg.github.io/specs/rfc7540.html#StreamPriority

       Streams  with the same parent should be allocated resources proportion-
       ally based on their weight. So if you have two streams going, stream  A
       with  weight  16  and  stream  B  with weight 32, stream B will get two
       thirds (32/48) of the available bandwidth (assuming the server can send
       off the data equally for both streams).

DEFAULT
       If  nothing is set, the HTTP/2 protocol itself will use its own default
       which is 16.

PROTOCOLS
       HTTP/2

EXAMPLE
       CURL *curl = curl_easy_init();
       CURL *curl2 = curl_easy_init(); /* a second handle */
       if(curl) {
         curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/one");
         curl_easy_setopt(curl, CURLOPT_STREAM_WEIGHT, 10L);

         /* the second has twice the weight */
         curl_easy_setopt(curl2, CURLOPT_URL, "https://example.com/two");
         curl_easy_setopt(curl2, CURLOPT_STREAM_WEIGHT, 20L);

         /* then add both to a multi handle and transfer them! */
       }

AVAILABILITY
       Added in 7.46.0

RETURN VALUE
       Returns CURLE_OK if the option is supported,  and  CURLE_UNKNOWN_OPTION
       if not.


ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+------------------+
       |ATTRIBUTE TYPE | ATTRIBUTE VALUE  |
       +---------------+------------------+
       |Availability   | web/curl         |
       +---------------+------------------+
       |Stability      | Uncommitted      |
       +---------------+------------------+
SEE ALSO
       CURLOPT_STREAM_DEPENDS(3),       CURLOPT_STREAM_DEPENDS_E(3),      CUR-
       LOPT_PIPEWAIT(3), CURLMOPT_PIPELINING(3),



NOTES
       This    software    was    built    from    source     available     at
       https://github.com/oracle/solaris-userland.    The  original  community
       source   was    downloaded    from     https://github.com/curl/curl/ar-
       chive/curl-7_64_0.zip

       Further information about this software can be found on the open source
       community website at http://curl.haxx.se/.



libcurl 7.46.0                    13 Sep 2015         CURLOPT_STREAM_WEIGHT(3)