1---
2c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_BUFFERSIZE
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_MAXFILESIZE (3)
9  - CURLOPT_MAX_RECV_SPEED_LARGE (3)
10  - CURLOPT_UPLOAD_BUFFERSIZE (3)
11  - CURLOPT_WRITEFUNCTION (3)
12---
13
14# NAME
15
16CURLOPT_BUFFERSIZE - receive buffer size
17
18# SYNOPSIS
19
20~~~c
21#include <curl/curl.h>
22
23CURLcode curl_easy_setopt(CURL *handle, CURLOPT_BUFFERSIZE, long size);
24~~~
25
26# DESCRIPTION
27
28Pass a long specifying your preferred *size* (in bytes) for the receive buffer
29in libcurl. The main point of this would be that the write callback gets
30called more often and with smaller chunks. Secondly, for some protocols, there
31is a benefit of having a larger buffer for performance.
32
33This is just treated as a request, not an order. You cannot be guaranteed to
34actually get the given size.
35
36This buffer size is by default *CURL_MAX_WRITE_SIZE* (16kB). The maximum
37buffer size allowed to be set is *CURL_MAX_READ_SIZE* (10MB). The minimum
38buffer size allowed to be set is 1024.
39
40DO NOT set this option on a handle that is currently used for an active
41transfer as that may lead to unintended consequences.
42
43The maximum size was 512kB until 7.88.0.
44
45# DEFAULT
46
47CURL_MAX_WRITE_SIZE (16kB)
48
49# PROTOCOLS
50
51All
52
53# EXAMPLE
54
55~~~c
56int main(void)
57{
58  CURL *curl = curl_easy_init();
59  if(curl) {
60    CURLcode res;
61    curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/foo.bin");
62
63    /* ask libcurl to allocate a larger receive buffer */
64    curl_easy_setopt(curl, CURLOPT_BUFFERSIZE, 120000L);
65
66    res = curl_easy_perform(curl);
67
68    curl_easy_cleanup(curl);
69  }
70}
71~~~
72
73# AVAILABILITY
74
75Added in 7.10. Growing the buffer was added in 7.53.0.
76
77# RETURN VALUE
78
79Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
80