50
50
<p class="level0">curl_easy_setopt() is used to tell libcurl how to behave. By using the appropriate options to <span Class="emphasis">curl_easy_setopt</span>, you can change libcurl's behavior. All options are set with the <span Class="emphasis">option</span> followed by a <span Class="emphasis">parameter</span>. That parameter can be a <span Class="bold">long</span>, a <span Class="bold">function pointer</span>, an <span Class="bold">object pointer</span> or a <span Class="bold">curl_off_t</span>, 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. A typical application uses many curl_easy_setopt() calls in the setup phase.
51
51
<p class="level0">Options set with this function call are valid for all forthcoming transfers performed using this <span Class="emphasis">handle</span>. The options are not in any way reset between transfers, so if you want subsequent transfers with different options, you must change them between the transfers. You can optionally reset all options back to internal default with <a class="emphasis" href="./curl_easy_reset.html">curl_easy_reset(3)</a>.
52
52
<p class="level0">Strings passed to libcurl as 'char *' arguments, are copied by the library; thus the string storage associated to the pointer argument may be overwritten after curl_easy_setopt() returns. Exceptions to this rule are described in the option details below.
53
<p class="level0">NOTE: before 7.17.0 strings were not copied. Instead the user was forced keep them available until libcurl no longer needed them.
53
<p class="level0">Before version 7.17.0, strings were not copied. Instead the user was forced keep them available until libcurl no longer needed them.
54
54
<p class="level0">The <span Class="emphasis">handle</span> is the return code from a <a class="emphasis" href="./curl_easy_init.html">curl_easy_init(3)</a> or <a class="emphasis" href="./curl_easy_duphandle.html">curl_easy_duphandle(3)</a> call. <a name="BEHAVIOR"></a><h2 class="nroffsh">BEHAVIOR OPTIONS</h2>
56
56
<p class="level0"><a name="CURLOPTVERBOSE"></a><span class="nroffip">CURLOPT_VERBOSE</span>
64
64
<p class="level0"><a name="CURLOPTNOSIGNAL"></a><span class="nroffip">CURLOPT_NOSIGNAL</span>
65
65
<p class="level1">Pass a long. If it is 1, libcurl will not use any functions that install signal handlers or any functions that cause signals to be sent to the process. This option is mainly here to allow multi-threaded unix applications to still set/use all timeout options etc, without risking getting signals. (Added in 7.10)
66
66
<p class="level1">If this option is set and libcurl has been built with the standard name resolver, timeouts will not occur while the name resolve takes place. Consider building libcurl with c-ares support to enable asynchronous DNS lookups, which enables nice timeouts for name resolves without signals.
67
<p class="level1"><a name="CALLBACK"></a><h2 class="nroffsh">CALLBACK OPTIONS</h2>
67
<p class="level0"><a name="CURLOPTWILDCARDMATCH"></a><span class="nroffip">CURLOPT_WILDCARDMATCH</span>
68
<p class="level1">Set this option to 1 if you want to transfer multiple files according to a file name pattern. The pattern can be specified as part of the <a class="emphasis" href="#CURLOPTURL">CURLOPT_URL</a> option, using an fnmatch-like pattern (Shell Pattern Matching) in the last part of URL (file name).
69
<p class="level1">By default, libcurl uses its internal wildcard matching implementation. You can provide your own matching function by the <a class="emphasis" href="#CURLOPTFNMATCHFUNCTION">CURLOPT_FNMATCH_FUNCTION</a> option.
70
<p class="level1">This feature is only supported by the FTP download for now.
71
<p class="level1">A brief introduction of its syntax follows:
73
<p class="level1"><a name="fBfP"></a><span class="nroffip">\fB*\fP - ASTERISK</span>
74
<p class="level2"><a href="ftp://example.com/some/path/">ftp://example.com/some/path/</a><span Class="bold">*.txt</span> (for all txt's from the root directory)
77
<p class="level1"><a name="fBfP"></a><span class="nroffip">\fB?\fP - QUESTION MARK</span>
78
<p class="level2">Question mark matches any (exactly one) character.
79
<p class="level2"><a href="ftp://example.com/some/path/">ftp://example.com/some/path/</a><span Class="bold">photo?.jpeg</span>
82
<p class="level1"><a name="fBfP"></a><span class="nroffip">\fB[\fP - BRACKET EXPRESSION</span>
83
<p class="level2">The left bracket opens a bracket expression. The question mark and asterisk have no special meaning in a bracket expression. Each bracket expression ends by the right bracket and matches exactly one character. Some examples follow:
84
<p class="level2"><span Class="bold">[a-zA-Z0-9]</span> or <span Class="bold">[f-gF-G]</span> - character interval
85
<p class="level2"><span Class="bold">[abc]</span> - character enumeration
86
<p class="level2"><span Class="bold">[^abc]</span> or <span Class="bold">[!abc]</span> - negation
87
<p class="level2"><span Class="bold">[[:</span><span Class="emphasis">name</span><span Class="bold">:]]</span> class expression. Supported classes are <span Class="bold">alnum</span>,<span Class="bold">lower</span>, <span Class="bold">space</span>, <span Class="bold">alpha</span>, <span Class="bold">digit</span>, <span Class="bold">print</span>, <span Class="bold">upper</span>, <span Class="bold">blank</span>, <span Class="bold">graph</span>, <span Class="bold">xdigit</span>.
88
<p class="level2"><span Class="bold">[][-!^]</span> - special case - matches only '-', ']', '[', '!' or '^'. These characters have no special purpose.
89
<p class="level2"><span Class="bold">[\[\]\\]</span> - escape syntax. Matches '[', ']' or '´.
90
<p class="level2">Using the rules above, a file name pattern can be constructed:
91
<p class="level2"><a href="ftp://example.com/some/path/">ftp://example.com/some/path/</a><span Class="bold">[a-z[:upper:]\\].jpeg</span>
93
<p class="level1">(This was added in 7.21.0) <a name="CALLBACK"></a><h2 class="nroffsh">CALLBACK OPTIONS</h2>
69
95
<p class="level0"><a name="CURLOPTWRITEFUNCTION"></a><span class="nroffip">CURLOPT_WRITEFUNCTION</span>
70
<p class="level1">Function pointer that should match the following prototype: <span class="bold">size_t function( void *ptr, size_t size, size_t nmemb, void *stream);</span> This function gets called by libcurl as soon as there is data received that needs to be saved. The size of the data pointed to by <span Class="emphasis">ptr</span> is <span Class="emphasis">size</span> multiplied with <span Class="emphasis">nmemb</span>, it will not be zero terminated. Return the number of bytes actually taken care of. If that amount differs from the amount passed to your function, it'll signal an error to the library and it will abort the transfer and return <span Class="emphasis">CURLE_WRITE_ERROR</span>.
96
<p class="level1">Function pointer that should match the following prototype: <span class="bold">size_t function( void *ptr, size_t size, size_t nmemb, void *stream);</span> This function gets called by libcurl as soon as there is data received that needs to be saved. The size of the data pointed to by <span Class="emphasis">ptr</span> is <span Class="emphasis">size</span> multiplied with <span Class="emphasis">nmemb</span>, it will not be zero terminated. Return the number of bytes actually taken care of. If that amount differs from the amount passed to your function, it'll signal an error to the library. This will abort the transfer and return <span Class="emphasis">CURLE_WRITE_ERROR</span>.
71
97
<p class="level1">From 7.18.0, the function can return CURL_WRITEFUNC_PAUSE which then will cause writing to this connection to become paused. See <a class="emphasis" href="./curl_easy_pause.html">curl_easy_pause(3)</a> for further details.
72
98
<p class="level1">This function may be called with zero bytes data if the transferred file is empty.
73
99
<p class="level1">Set this option to NULL to get the internal default function. The internal default function will write the data to the FILE * given with <a class="emphasis" href="#CURLOPTWRITEDATA">CURLOPT_WRITEDATA</a>.
111
137
<p class="level0"><a name="CURLOPTOPENSOCKETDATA"></a><span class="nroffip">CURLOPT_OPENSOCKETDATA</span>
112
138
<p class="level1">Pass a pointer that will be untouched by libcurl and passed as the first argument in the opensocket callback set with <a class="emphasis" href="#CURLOPTOPENSOCKETFUNCTION">CURLOPT_OPENSOCKETFUNCTION</a>. (Option added in 7.17.1.)
113
139
<p class="level0"><a name="CURLOPTPROGRESSFUNCTION"></a><span class="nroffip">CURLOPT_PROGRESSFUNCTION</span>
114
<p class="level1">Function pointer that should match the <span Class="emphasis">curl_progress_callback</span> prototype found in <span Class="emphasis"><curl/curl.h></span>. This function gets called by libcurl instead of its internal equivalent with a frequent interval during operation (roughly once per second) no matter if data is being transfered or not. Unknown/unused argument values passed to the callback will be set to zero (like if you only download data, the upload size will remain 0). Returning a non-zero value from this callback will cause libcurl to abort the transfer and return <span Class="emphasis">CURLE_ABORTED_BY_CALLBACK</span>.
140
<p class="level1">Function pointer that should match the <span Class="emphasis">curl_progress_callback</span> prototype found in <span Class="emphasis"><curl/curl.h></span>. This function gets called by libcurl instead of its internal equivalent with a frequent interval during operation (roughly once per second or sooner) no matter if data is being transfered or not. Unknown/unused argument values passed to the callback will be set to zero (like if you only download data, the upload size will remain 0). Returning a non-zero value from this callback will cause libcurl to abort the transfer and return <span Class="emphasis">CURLE_ABORTED_BY_CALLBACK</span>.
115
141
<p class="level1">If you transfer data with the multi interface, this function will not be called during periods of idleness unless you call the appropriate libcurl function that performs transfers.
116
142
<p class="level1"><a class="emphasis" href="#CURLOPTNOPROGRESS">CURLOPT_NOPROGRESS</a> must be set to 0 to make this function actually get called.
117
143
<p class="level0"><a name="CURLOPTPROGRESSDATA"></a><span class="nroffip">CURLOPT_PROGRESSDATA</span>
118
144
<p class="level1">Pass a pointer that will be untouched by libcurl and passed as the first argument in the progress callback set with <a class="emphasis" href="#CURLOPTPROGRESSFUNCTION">CURLOPT_PROGRESSFUNCTION</a>.
119
145
<p class="level0"><a name="CURLOPTHEADERFUNCTION"></a><span class="nroffip">CURLOPT_HEADERFUNCTION</span>
120
<p class="level1">Function pointer that should match the following prototype: <span class="emphasis">size_t function( void *ptr, size_t size, size_t nmemb, void *stream);</span>. This function gets called by libcurl as soon as it has received header data. The header callback will be called once for each header and only complete header lines are passed on to the callback. Parsing headers should be easy enough using this. The size of the data pointed to by <span Class="emphasis">ptr</span> is <span Class="emphasis">size</span> multiplied with <span Class="emphasis">nmemb</span>. Do not assume that the header line is zero terminated! The pointer named <span Class="emphasis">stream</span> is the one you set with the <a class="emphasis" href="#CURLOPTWRITEHEADER">CURLOPT_WRITEHEADER</a> option. The callback function must return the number of bytes actually taken care of, or return -1 to signal error to the library (it will cause it to abort the transfer with a <span Class="emphasis">CURLE_WRITE_ERROR</span> return code).
146
<p class="level1">Function pointer that should match the following prototype: <span class="emphasis">size_t function( void *ptr, size_t size, size_t nmemb, void *stream);</span>. This function gets called by libcurl as soon as it has received header data. The header callback will be called once for each header and only complete header lines are passed on to the callback. Parsing headers should be easy enough using this. The size of the data pointed to by <span Class="emphasis">ptr</span> is <span Class="emphasis">size</span> multiplied with <span Class="emphasis">nmemb</span>. Do not assume that the header line is zero terminated! The pointer named <span Class="emphasis">stream</span> is the one you set with the <a class="emphasis" href="#CURLOPTWRITEHEADER">CURLOPT_WRITEHEADER</a> option. The callback function must return the number of bytes actually taken care of. If that amount differs from the amount passed to your function, it'll signal an error to the library. This will abort the transfer and return <span Class="emphasis">CURL_WRITE_ERROR</span>.
121
147
<p class="level1">If this option is not set, or if it is set to NULL, but <span Class="emphasis">CURLOPT_HEADERDATA</span> (<a class="emphasis" href="#CURLOPTWRITEHEADER">CURLOPT_WRITEHEADER</a>) is set to anything but NULL, the function used to accept response data will be used instead. That is, it will be the function specified with <a class="emphasis" href="#CURLOPTWRITEFUNCTION">CURLOPT_WRITEFUNCTION</a>, or if it is not specified or NULL - the default, stream-writing function.
122
148
<p class="level1">It's important to note that the callback will be invoked for the headers of all responses received after initiating a request and not just the final response. This includes all responses which occur during authentication negotiation. If you need to operate on only the headers from the final response, you will need to collect headers in the callback yourself and use HTTP status lines, for example, to delimit response boundaries.
123
149
<p class="level1">Since 7.14.1: When a server sends a chunked encoded transfer, it may contain a trailer. That trailer is identical to a HTTP header and if such a trailer is received it is passed to the application using this callback as well. There are several ways to detect it being a trailer and not an ordinary header: 1) it comes after the response-body. 2) it comes after the final header line (CR LF) 3) a Trailer: header among the response-headers mention what header to expect in the trailer.
163
189
<p class="level1">The iconv code in libcurl will default the network and UTF8 codeset names as follows:
164
190
<p class="level1"> #define CURL_ICONV_CODESET_OF_NETWORK "ISO8859-1"
165
191
<p class="level1"> #define CURL_ICONV_CODESET_FOR_UTF8 "UTF-8"
166
<p class="level1">You will need to override these definitions if they are different on your system. <a name="ERROR"></a><h2 class="nroffsh">ERROR OPTIONS</h2>
192
<p class="level1">You will need to override these definitions if they are different on your system.
193
<p class="level0"><a name="CURLOPTINTERLEAVEFUNCTION"></a><span class="nroffip">CURLOPT_INTERLEAVEFUNCTION</span>
194
<p class="level1">Function pointer that should match the following prototype: <span class="emphasis">size_t function( void *ptr, size_t size, size_t nmemb, void *stream)</span>. This function gets called by libcurl as soon as it has received interleaved RTP data. This function gets called for each $ block and therefore contains exactly one upper-layer protocol unit (e.g. one RTP packet). Curl writes the interleaved header as well as the included data for each call. The first byte is always an ASCII dollar sign. The dollar sign is followed by a one byte channel identifier and then a 2 byte integer length in network byte order. See <span Class="emphasis">RFC 2326 Section 10.12</span> for more information on how RTP interleaving behaves. If unset or set to NULL, curl will use the default write function.
195
<p class="level1">Interleaved RTP poses some challeneges for the client application. Since the stream data is sharing the RTSP control connection, it is critical to service the RTP in a timely fashion. If the RTP data is not handled quickly, subsequent response processing may become unreasonably delayed and the connection may close. The application may use <a class="emphasis" href="#CURLRTSPREQRECEIVE">CURL_RTSPREQ_RECEIVE</a> to service RTP data when no requests are desired. If the application makes a request, (e.g. <a class="emphasis" href="#CURLRTSPREQPAUSE">CURL_RTSPREQ_PAUSE</a>) then the response handler will process any pending RTP data before marking the request as finished. (Added in 7.20.0)
196
<p class="level0"><a name="CURLOPTINTERLEAVEDATA"></a><span class="nroffip">CURLOPT_INTERLEAVEDATA</span>
197
<p class="level1">This is the stream that will be passed to <a class="emphasis" href="#CURLOPTINTERLEAVEFUNCTION">CURLOPT_INTERLEAVEFUNCTION</a> when interleaved RTP data is received. (Added in 7.20.0)
198
<p class="level0"><a name="CURLOPTCHUNKBGNFUNCTION"></a><span class="nroffip">CURLOPT_CHUNK_BGN_FUNCTION</span>
199
<p class="level1">Function pointer that should match the following prototype: <span class="bold">long function (const void *transfer_info, void *ptr, int remains)</span>. This function gets called by libcurl before a part of the stream is going to be transferred (if the transfer supports chunks).
200
<p class="level1">This callback makes sense only when using the <a class="emphasis" href="#CURLOPTWILDCARDMATCH">CURLOPT_WILDCARDMATCH</a> option for now.
201
<p class="level1">The target of transfer_info parameter is a "feature depended" structure. For the FTP wildcard download, the target is curl_fileinfo structure (see <span Class="emphasis">curl/curl.h</span>). The parameter ptr is a pointer given by <a class="emphasis" href="#CURLOPTCHUNKDATA">CURLOPT_CHUNK_DATA</a>. The parameter remains contains number of chunks remaining per the transfer. If the feature is not available, the parameter has zero value.
202
<p class="level1">Return <span Class="emphasis">CURL_CHUNK_BGN_FUNC_OK</span> if everything is fine, <span Class="emphasis">CURL_CHUNK_BGN_FUNC_SKIP</span> if you want to skip the concrete chunk or <span Class="emphasis">CURL_CHUNK_BGN_FUNC_FAIL</span> to tell libcurl to stop if some error occurred. (This was added in 7.21.0)
203
<p class="level0"><a name="CURLOPTCHUNKENDFUNCTION"></a><span class="nroffip">CURLOPT_CHUNK_END_FUNCTION</span>
204
<p class="level1">Function pointer that should match the following prototype: <span class="bold">long function(void *ptr)</span>. This function gets called by libcurl as soon as a part of the stream has been transferred (or skipped).
205
<p class="level1">Return <span Class="emphasis">CURL_CHUNK_END_FUNC_OK</span> if everything is fine or <span Class="bold">CURL_CHUNK_END_FUNC_FAIL</span> to tell the lib to stop if some error occurred. (This was added in 7.21.0)
206
<p class="level0"><a name="CURLOPTCHUNKDATA"></a><span class="nroffip">CURLOPT_CHUNK_DATA</span>
207
<p class="level1">Pass a pointer that will be untouched by libcurl and passed as the ptr argument to the <span Class="emphasis">CURL_CHUNK_BGN_FUNTION</span> and <span Class="emphasis">CURL_CHUNK_END_FUNTION</span>. (This was added in 7.21.0)
208
<p class="level0"><a name="CURLOPTFNMATCHFUNCTION"></a><span class="nroffip">CURLOPT_FNMATCH_FUNCTION</span>
209
<p class="level1">Function pointer that should match <span class="bold">int function(void *ptr, const char *pattern, const char *string)</span> prototype (see <span Class="emphasis">curl/curl.h</span>). It is used internally for the wildcard matching feature.
210
<p class="level1">Return <span Class="emphasis">CURL_FNMATCHFUNC_MATCH</span> if pattern matches the string, <span Class="emphasis">CURL_FNMATCHFUNC_NOMATCH</span> if not or <span Class="emphasis">CURL_FNMATCHFUNC_FAIL</span> if an error occurred. (This was added in 7.21.0)
211
<p class="level0"><a name="CURLOPTFNMATCHDATA"></a><span class="nroffip">CURLOPT_FNMATCH_DATA</span>
212
<p class="level1">Pass a pointer that will be untouched by libcurl and passed as the ptr argument to the <span Class="emphasis">CURL_FNMATCH_FUNCTION</span>. (This was added in 7.21.0) <a name="ERROR"></a><h2 class="nroffsh">ERROR OPTIONS</h2>
167
213
<p class="level0">
168
214
<p class="level0"><a name="CURLOPTERRORBUFFER"></a><span class="nroffip">CURLOPT_ERRORBUFFER</span>
169
<p class="level1">Pass a char * to a buffer that the libcurl may store human readable error messages in. This may be more helpful than just the return code from <span Class="emphasis">curl_easy_perform</span>. The buffer must be at least CURL_ERROR_SIZE big. Although this argument is a 'char *', it does not describe an input string. Therefore the (probably undefined) contents of the buffer is NOT copied by the library. You should keep the associated storage available until libcurl no longer needs it. Failing to do so will cause very odd behavior or even crashes. libcurl will need it until you call <a class="emphasis" href="./curl_easy_cleanup.html">curl_easy_cleanup(3)</a> or you set the same option again to use a different pointer.
215
<p class="level1">Pass a char * to a buffer that the libcurl may store human readable error messages in. This may be more helpful than just the return code from <span Class="emphasis">curl_easy_perform</span>. The buffer must be at least CURL_ERROR_SIZE big. Although this argument is a 'char *', it does not describe an input string. Therefore the (probably undefined) contents of the buffer is NOT copied by the library. You should keep the associated storage available until libcurl no longer needs it. Failing to do so will cause very odd behavior or even crashes. libcurl will need it until you call <a class="emphasis" href="./curl_easy_cleanup.html">curl_easy_cleanup(3)</a> or you set the same option again to use a different pointer.
170
216
<p class="level1">Use <a class="emphasis" href="#CURLOPTVERBOSE">CURLOPT_VERBOSE</a> and <a class="emphasis" href="#CURLOPTDEBUGFUNCTION">CURLOPT_DEBUGFUNCTION</a> to better debug/trace why errors happen.
171
217
<p class="level1">If the library does not return an error, the buffer may not have been touched. Do not rely on the contents in those cases.
172
218
<p class="level1">
181
227
<p class="level1">The actual URL to deal with. The parameter should be a char * to a zero terminated string.
182
228
<p class="level1">If the given URL lacks the protocol part ("http://" or "ftp://" etc), it will attempt to guess which protocol to use based on the given host name. If the given protocol of the set URL is not supported, libcurl will return on error (<span Class="emphasis">CURLE_UNSUPPORTED_PROTOCOL</span>) when you call <a class="emphasis" href="./curl_easy_perform.html">curl_easy_perform(3)</a> or <a class="emphasis" href="./curl_multi_perform.html">curl_multi_perform(3)</a>. Use <a class="emphasis" href="./curl_version_info.html">curl_version_info(3)</a> for detailed info on which protocols are supported.
183
229
<p class="level1">The string given to CURLOPT_URL must be url-encoded and follow RFC 2396 (<a href="http://curl.haxx.se/rfc/rfc2396.txt">http://curl.haxx.se/rfc/rfc2396.txt</a>).
230
<p class="level1">Starting with version 7.20.0, the fragment part of the URI will not be send as part of the path, which was the case previously.
184
231
<p class="level1"><a class="emphasis" href="#CURLOPTURL">CURLOPT_URL</a> is the only option that <span Class="bold">must</span> be set before <a class="emphasis" href="./curl_easy_perform.html">curl_easy_perform(3)</a> is called.
185
232
<p class="level1"><a class="emphasis" href="#CURLOPTPROTOCOLS">CURLOPT_PROTOCOLS</a> can be used to limit what protocols libcurl will use for this transfer, independent of what libcurl has been compiled to support. That may be useful if you accept the URL from an external source and want to limit the accessibility.
186
233
<p class="level0"><a name="CURLOPTPROTOCOLS"></a><span class="nroffip">CURLOPT_PROTOCOLS</span>
208
255
<p class="level0"><a name="CURLOPTINTERFACE"></a><span class="nroffip">CURLOPT_INTERFACE</span>
209
256
<p class="level1">Pass a char * as parameter. This sets the interface name to use as outgoing network interface. The name can be an interface name, an IP address, or a host name.
210
257
<p class="level0"><a name="CURLOPTLOCALPORT"></a><span class="nroffip">CURLOPT_LOCALPORT</span>
211
<p class="level1">Pass a long. This sets the local port number of the socket used for connection. This can be used in combination with <a class="emphasis" href="#CURLOPTINTERFACE">CURLOPT_INTERFACE</a> and you are recommended to use <a class="emphasis" href="#CURLOPTLOCALPORTRANGE">CURLOPT_LOCALPORTRANGE</a> as well when this is set. Note that the only valid port numbers are 1 - 65535. (Added in 7.15.2)
258
<p class="level1">Pass a long. This sets the local port number of the socket used for connection. This can be used in combination with <a class="emphasis" href="#CURLOPTINTERFACE">CURLOPT_INTERFACE</a> and you are recommended to use <a class="emphasis" href="#CURLOPTLOCALPORTRANGE">CURLOPT_LOCALPORTRANGE</a> as well when this is set. Valid port numbers are 1 - 65535. (Added in 7.15.2)
212
259
<p class="level0"><a name="CURLOPTLOCALPORTRANGE"></a><span class="nroffip">CURLOPT_LOCALPORTRANGE</span>
213
<p class="level1">Pass a long. This is the number of attempts libcurl should make to find a working local port number. It starts with the given <a class="emphasis" href="#CURLOPTLOCALPORT">CURLOPT_LOCALPORT</a> and adds one to the number for each retry. Setting this to 1 or below will make libcurl do only one try for the exact port number. Note that port numbers by nature are scarce resources that will be busy at times so setting this value to something too low might cause unnecessary connection setup failures. (Added in 7.15.2)
260
<p class="level1">Pass a long. This is the number of attempts libcurl should make to find a working local port number. It starts with the given <a class="emphasis" href="#CURLOPTLOCALPORT">CURLOPT_LOCALPORT</a> and adds one to the number for each retry. Setting this to 1 or below will make libcurl do only one try for the exact port number. Port numbers by nature are scarce resources that will be busy at times so setting this value to something too low might cause unnecessary connection setup failures. (Added in 7.15.2)
214
261
<p class="level0"><a name="CURLOPTDNSCACHETIMEOUT"></a><span class="nroffip">CURLOPT_DNS_CACHE_TIMEOUT</span>
215
262
<p class="level1">Pass a long, this sets the timeout in seconds. Name resolves will be kept in memory for this number of seconds. Set to zero to completely disable caching, or set to -1 to make the cached entries remain forever. By default, libcurl caches this info for 60 seconds.
216
<p class="level1">NOTE: the name resolve functions of various libc implementations don't re-read name server information unless explicitly told so (for example, by calling <span Class="emphasis">res_init(3)</span>). This may cause libcurl to keep using the older server even if DHCP has updated the server info, and this may look like a DNS cache issue to the casual libcurl-app user.
263
<p class="level1">The name resolve functions of various libc implementations don't re-read name server information unless explicitly told so (for example, by calling <span Class="emphasis">res_init(3)</span>). This may cause libcurl to keep using the older server even if DHCP has updated the server info, and this may look like a DNS cache issue to the casual libcurl-app user.
217
264
<p class="level0"><a name="CURLOPTDNSUSEGLOBALCACHE"></a><span class="nroffip">CURLOPT_DNS_USE_GLOBAL_CACHE</span>
218
265
<p class="level1">Pass a long. If the value is 1, it tells curl to use a global DNS cache that will survive between easy handle creations and deletions. This is not thread-safe and this will use a global variable.
219
266
<p class="level1"><span Class="bold">WARNING:</span> this option is considered obsolete. Stop using it. Switch over to using the share interface instead! See <a class="emphasis" href="#CURLOPTSHARE">CURLOPT_SHARE</a> and <a class="emphasis" href="./curl_share_init.html">curl_share_init(3)</a>.
261
308
<p class="level1">The CURLOPT_PASSWORD option should be used in conjunction with the <a class="emphasis" href="#CURLOPTUSERNAME">CURLOPT_USERNAME</a> option. (Added in 7.19.1)
262
309
<p class="level0"><a name="CURLOPTPROXYUSERNAME"></a><span class="nroffip">CURLOPT_PROXYUSERNAME</span>
263
310
<p class="level1">Pass a char * as parameter, which should be pointing to the zero terminated user name to use for the transfer while connecting to Proxy.
264
<p class="level1">The CURLOPT_PROXYUSERNAME option should be used in same way as the <a class="emphasis" href="#CURLOPTPROXYUSERPWD">CURLOPT_PROXYUSERPWD</a> is used. In comparison to <a class="emphasis" href="#CURLOPTPROXYUSERPWD">CURLOPT_PROXYUSERPWD</a> the CURLOPT_PROXYUSERNAME allows the username to contain a colon, like in the following example: "sip:user@example.com". Note the CURLOPT_PROXYUSERNAME option is an alternative way to set the user name while connecting to Proxy. There is no meaning to use it together with the <a class="emphasis" href="#CURLOPTPROXYUSERPWD">CURLOPT_PROXYUSERPWD</a> option.
311
<p class="level1">The CURLOPT_PROXYUSERNAME option should be used in same way as the <a class="emphasis" href="#CURLOPTPROXYUSERPWD">CURLOPT_PROXYUSERPWD</a> is used. In comparison to <a class="emphasis" href="#CURLOPTPROXYUSERPWD">CURLOPT_PROXYUSERPWD</a> the CURLOPT_PROXYUSERNAME allows the username to contain a colon, like in the following example: "sip:user@example.com". The CURLOPT_PROXYUSERNAME option is an alternative way to set the user name while connecting to Proxy. There is no meaning to use it together with the <a class="emphasis" href="#CURLOPTPROXYUSERPWD">CURLOPT_PROXYUSERPWD</a> option.
265
312
<p class="level1">In order to specify the password to be used in conjunction with the user name use the <a class="emphasis" href="#CURLOPTPROXYPASSWORD">CURLOPT_PROXYPASSWORD</a> option. (Added in 7.19.1)
266
313
<p class="level0"><a name="CURLOPTPROXYPASSWORD"></a><span class="nroffip">CURLOPT_PROXYPASSWORD</span>
267
314
<p class="level1">Pass a char * as parameter, which should be pointing to the zero terminated password to use for the transfer while connecting to Proxy.
297
344
<p class="level0"><a name="CURLOPTFOLLOWLOCATION"></a><span class="nroffip">CURLOPT_FOLLOWLOCATION</span>
298
345
<p class="level1">A parameter set to 1 tells the library to follow any Location: header that the server sends as part of an HTTP header.
299
346
<p class="level1">This means that the library will re-send the same request on the new location and follow new Location: headers all the way until no more such headers are returned. <a class="emphasis" href="#CURLOPTMAXREDIRS">CURLOPT_MAXREDIRS</a> can be used to limit the number of redirects libcurl will follow.
300
<p class="level1">NOTE: since 7.19.4, libcurl can limit to what protocols it will automatically follow. The accepted protocols are set with <a class="emphasis" href="#CURLOPTREDIRPROTOCOLS">CURLOPT_REDIR_PROTOCOLS</a> and it excludes the FILE protocol by default.
347
<p class="level1">Since 7.19.4, libcurl can limit what protocols it will automatically follow. The accepted protocols are set with <a class="emphasis" href="#CURLOPTREDIRPROTOCOLS">CURLOPT_REDIR_PROTOCOLS</a> and it excludes the FILE protocol by default.
301
348
<p class="level0"><a name="CURLOPTUNRESTRICTEDAUTH"></a><span class="nroffip">CURLOPT_UNRESTRICTED_AUTH</span>
302
349
<p class="level1">A parameter set to 1 tells the library it can continue to send authentication (user+password) when following locations, even when hostname changed. This option is meaningful only when setting <a class="emphasis" href="#CURLOPTFOLLOWLOCATION">CURLOPT_FOLLOWLOCATION</a>.
303
350
<p class="level0"><a name="CURLOPTMAXREDIRS"></a><span class="nroffip">CURLOPT_MAXREDIRS</span>
318
365
<p class="level1">When setting <a class="emphasis" href="#CURLOPTPOST">CURLOPT_POST</a> to 1, it will automatically set <a class="emphasis" href="#CURLOPTNOBODY">CURLOPT_NOBODY</a> to 0 (since 7.14.1).
319
366
<p class="level1">If you issue a POST request and then want to make a HEAD or GET using the same re-used handle, you must explicitly set the new request type using <a class="emphasis" href="#CURLOPTNOBODY">CURLOPT_NOBODY</a> or <a class="emphasis" href="#CURLOPTHTTPGET">CURLOPT_HTTPGET</a> or similar.
320
367
<p class="level0"><a name="CURLOPTPOSTFIELDS"></a><span class="nroffip">CURLOPT_POSTFIELDS</span>
321
<p class="level1">Pass a void * as parameter, which should be the full data to post in an HTTP POST operation. You must make sure that the data is formatted the way you want the server to receive it. libcurl will not convert or encode it for you. Most web servers will assume this data to be url-encoded. Take note.
368
<p class="level1">Pass a void * as parameter, which should be the full data to post in an HTTP POST operation. You must make sure that the data is formatted the way you want the server to receive it. libcurl will not convert or encode it for you. Most web servers will assume this data to be url-encoded.
322
369
<p class="level1">The pointed data are NOT copied by the library: as a consequence, they must be preserved by the calling application until the transfer finishes.
323
370
<p class="level1">This POST is a normal application/x-www-form-urlencoded kind (and libcurl will set that Content-Type by default when this option is used), which is the most commonly used one by HTML forms. See also the <a class="emphasis" href="#CURLOPTPOST">CURLOPT_POST</a>. Using <a class="emphasis" href="#CURLOPTPOSTFIELDS">CURLOPT_POSTFIELDS</a> implies <a class="emphasis" href="#CURLOPTPOST">CURLOPT_POST</a>.
324
371
<p class="level1">If you want to do a zero-byte POST, you need to set <a class="emphasis" href="#CURLOPTPOSTFIELDSIZE">CURLOPT_POSTFIELDSIZE</a> explicitly to zero, as simply setting <a class="emphasis" href="#CURLOPTPOSTFIELDS">CURLOPT_POSTFIELDS</a> to NULL or "" just effectively disables the sending of the specified string. libcurl will instead assume that you'll send the POST data using the read callback!
351
398
<p class="level0"><a name="CURLOPTCOOKIE"></a><span class="nroffip">CURLOPT_COOKIE</span>
352
399
<p class="level1">Pass a pointer to a zero terminated string as parameter. It will be used to set a cookie in the http request. The format of the string should be NAME=CONTENTS, where NAME is the cookie name and CONTENTS is what the cookie should contain.
353
400
<p class="level1">If you need to set multiple cookies, you need to set them all using a single option and thus you need to concatenate them all in one single string. Set multiple cookies in one string like this: "name1=content1; name2=content2;" etc.
354
<p class="level1">Note that this option sets the cookie header explictly in the outgoing request(s). If multiple requests are done due to authentication, followed redirections or similar, they will all get this cookie passed on.
401
<p class="level1">This option sets the cookie header explictly in the outgoing request(s). If multiple requests are done due to authentication, followed redirections or similar, they will all get this cookie passed on.
355
402
<p class="level1">Using this option multiple times will only make the latest string override the previous ones.
356
403
<p class="level0"><a name="CURLOPTCOOKIEFILE"></a><span class="nroffip">CURLOPT_COOKIEFILE</span>
357
404
<p class="level1">Pass a pointer to a zero terminated string as parameter. It should contain the name of your file holding cookie data to read. The cookie data may be in Netscape / Mozilla cookie data format or just regular HTTP-style headers dumped to a file.
380
427
<p class="level0"><a name="CURLOPTIGNORECONTENTLENGTH"></a><span class="nroffip">CURLOPT_IGNORE_CONTENT_LENGTH</span>
381
428
<p class="level1">Ignore the Content-Length header. This is useful for Apache 1.x (and similar servers) which will report incorrect content length for files over 2 gigabytes. If this option is used, curl will not be able to accurately report progress, and will simply stop the download when the server ends the connection. (added in 7.14.1)
382
429
<p class="level0"><a name="CURLOPTHTTPCONTENTDECODING"></a><span class="nroffip">CURLOPT_HTTP_CONTENT_DECODING</span>
383
<p class="level1">Pass a long to tell libcurl how to act on content decoding. If set to zero, content decoding will be disabled. If set to 1 it is enabled. Note however that libcurl has no default content decoding but requires you to use <a class="emphasis" href="#CURLOPTENCODING">CURLOPT_ENCODING</a> for that. (added in 7.16.2)
430
<p class="level1">Pass a long to tell libcurl how to act on content decoding. If set to zero, content decoding will be disabled. If set to 1 it is enabled. Libcurl has no default content decoding but requires you to use <a class="emphasis" href="#CURLOPTENCODING">CURLOPT_ENCODING</a> for that. (added in 7.16.2)
384
431
<p class="level0"><a name="CURLOPTHTTPTRANSFERDECODING"></a><span class="nroffip">CURLOPT_HTTP_TRANSFER_DECODING</span>
385
<p class="level1">Pass a long to tell libcurl how to act on transfer decoding. If set to zero, transfer decoding will be disabled, if set to 1 it is enabled (default). libcurl does chunked transfer decoding by default unless this option is set to zero. (added in 7.16.2) <a name="TFTP"></a><h2 class="nroffsh">TFTP OPTIONS</h2>
387
<p class="level0"><a name="CURLOPTTFTPBLKSIZE"></a><span class="nroffip">CURLOPT_TFTPBLKSIZE</span>
432
<p class="level1">Pass a long to tell libcurl how to act on transfer decoding. If set to zero, transfer decoding will be disabled, if set to 1 it is enabled (default). libcurl does chunked transfer decoding by default unless this option is set to zero. (added in 7.16.2) <a name="SMTP"></a><h2 class="nroffsh">SMTP OPTIONS</h2>
434
<p class="level0"><a name="CURLOPTMAILFROM"></a><span class="nroffip">CURLOPT_MAIL_FROM</span>
435
<p class="level1">Pass a pointer to a zero terminated string as parameter. It will be used to specify the sender address in a mail when sending an SMTP mail with libcurl.
436
<p class="level1">(Added in 7.20.0)
437
<p class="level0"><a name="CURLOPTMAILRCPT"></a><span class="nroffip">CURLOPT_MAIL_RCPT</span>
438
<p class="level1">Pass a pointer to a linked list of recipients to pass to the server in your SMTP mail request. The linked list should be a fully valid list of <span class="bold">struct curl_slist</span> structs properly filled in. Use <a class="emphasis" href="./curl_slist_append.html">curl_slist_append(3)</a> to create the list and <a class="emphasis" href="./curl_slist_free_all.html">curl_slist_free_all(3)</a> to clean up an entire list.
439
<p class="level1">Each recipient in SMTP lingo is specified with angle brackets (<>), but should you not use an angle bracket as first letter libcurl will assume you provide a single email address only and enclose that with angle brackets for you.
440
<p class="level1">(Added in 7.20.0) <a name="TFTP"></a><h2 class="nroffsh">TFTP OPTIONS</h2>
442
<p class="level0"><a name="CURLOPTTFTPBLKSIZE"></a><span class="nroffip">CURLOPT_TFTP_BLKSIZE</span>
388
443
<p class="level1">Specify block size to use for TFTP data transmission. Valid range as per RFC 2348 is 8-65464 bytes. The default of 512 bytes will be used if this option is not specified. The specified block size will only be used pending support by the remote server. If the server does not return an option acknowledgement or returns an option acknowledgement with no blksize, the default of 512 bytes will be used. (added in 7.19.4) <a name="FTP"></a><h2 class="nroffsh">FTP OPTIONS</h2>
389
444
<p class="level0">
390
445
<p class="level0"><a name="CURLOPTFTPPORT"></a><span class="nroffip">CURLOPT_FTPPORT</span>
419
474
<p class="level0"><a name="CURLOPTFTPUSEEPSV"></a><span class="nroffip">CURLOPT_FTP_USE_EPSV</span>
420
475
<p class="level1">Pass a long. If the value is 1, it tells curl to use the EPSV command when doing passive FTP downloads (which it always does by default). Using EPSV means that it will first attempt to use EPSV before using PASV, but if you pass zero to this option, it will not try using EPSV, only plain PASV.
421
476
<p class="level1">If the server is an IPv6 host, this option will have no effect as of 7.12.3.
477
<p class="level0"><a name="CURLOPTFTPUSEPRET"></a><span class="nroffip">CURLOPT_FTP_USE_PRET</span>
478
<p class="level1">Pass a long. If the value is 1, it tells curl to send a PRET command before PASV (and EPSV). Certain FTP servers, mainly drftpd, require this non-standard command for directory listings as well as up and downloads in PASV mode. Has no effect when using the active FTP transfers mode. (Added in 7.20.0)
422
479
<p class="level0"><a name="CURLOPTFTPCREATEMISSINGDIRS"></a><span class="nroffip">CURLOPT_FTP_CREATE_MISSING_DIRS</span>
423
480
<p class="level1">Pass a long. If the value is 1, curl will attempt to create any remote directory that it fails to CWD into. CWD is the command that changes working directory. (Added in 7.10.7)
424
481
<p class="level1">This setting also applies to SFTP-connections. curl will attempt to create the remote directory if it can't obtain a handle to the target-location. The creation will fail if a file of the same name as the directory to create already exists or lack of permissions prevents creation. (Added in 7.16.3)
475
532
<p class="level2">libcurl does no CWD at all. libcurl will do SIZE, RETR, STOR etc and give a full path to the server for all these commands. This is the fastest behavior.
476
533
<p class="level1"><a name="CURLFTPMETHODSINGLECWD"></a><span class="nroffip">CURLFTPMETHOD_SINGLECWD</span>
477
534
<p class="level2">libcurl does one CWD with the full target directory and then operates on the file "normally" (like in the multicwd case). This is somewhat more standards compliant than 'nocwd' but without the full penalty of 'multicwd'.
478
<p class="level1">(Added in 7.15.1) <a name="PROTOCOL"></a><h2 class="nroffsh">PROTOCOL OPTIONS</h2>
535
<p class="level1">(Added in 7.15.1) <a name="RTSP"></a><h2 class="nroffsh">RTSP OPTIONS</h2>
537
<p class="level0"><a name="CURLOPTRTSPREQUEST"></a><span class="nroffip">CURLOPT_RTSP_REQUEST</span>
538
<p class="level1">Tell libcurl what kind of RTSP request to make. Pass one of the following RTSP enum values. Unless noted otherwise, commands require the Session ID to be initialized. (Added in 7.20.0)
540
<p class="level1"><a name="CURLRTSPREQOPTIONS"></a><span class="nroffip">CURL_RTSPREQ_OPTIONS</span>
541
<p class="level2">Used to retrieve the available methods of the server. The application is responsbile for parsing and obeying the response. <span class="bold">(The session ID is not needed for this method.)</span> (Added in 7.20.0)
542
<p class="level1"><a name="CURLRTSPREQDESCRIBE"></a><span class="nroffip">CURL_RTSPREQ_DESCRIBE</span>
543
<p class="level2">Used to get the low level description of a stream. The application should note what formats it understands in the <span Class="emphasis">'Accept:'</span> header. Unless set manually, libcurl will automatically fill in <span class="emphasis">'Accept: application/sdp'</span>. Time-condition headers will be added to Describe requests if the <a class="emphasis" href="#CURLOPTTIMECONDITION">CURLOPT_TIMECONDITION</a> option is active. <span class="bold">(The session ID is not needed for this method)</span> (Added in 7.20.0)
544
<p class="level1"><a name="CURLRTSPREQANNOUNCE"></a><span class="nroffip">CURL_RTSPREQ_ANNOUNCE</span>
545
<p class="level2">When sent by a client, this method changes the description of the session. For example, if a client is using the server to record a meeting, the client can use Announce to inform the server of all the meta-information about the session. ANNOUNCE acts like an HTTP PUT or POST just like <a class="emphasis" href="#CURLRTSPREQSETPARAMETER">CURL_RTSPREQ_SET_PARAMETER</a> (Added in 7.20.0)
546
<p class="level1"><a name="CURLRTSPREQSETUP"></a><span class="nroffip">CURL_RTSPREQ_SETUP</span>
547
<p class="level2">Setup is used to initialize the transport layer for the session. The application must set the desired Transport options for a session by using the <a class="emphasis" href="#CURLOPTRTSPTRANSPORT">CURLOPT_RTSP_TRANSPORT</a> option prior to calling setup. If no session ID is currently set with <a class="emphasis" href="#CURLOPTRTSPSESSIONID">CURLOPT_RTSP_SESSION_ID</a>, libcurl will extract and use the session ID in the response to this request. <span class="bold">(The session ID is not needed for this method).</span> (Added in 7.20.0)
548
<p class="level1"><a name="CURLRTSPREQPLAY"></a><span class="nroffip">CURL_RTSPREQ_PLAY</span>
549
<p class="level2">Send a Play command to the server. Use the <a class="emphasis" href="#CURLOPTRANGE">CURLOPT_RANGE</a> option to modify the playback time (e.g. 'npt=10-15'). (Added in 7.20.0)
550
<p class="level1"><a name="CURLRTSPREQPAUSE"></a><span class="nroffip">CURL_RTSPREQ_PAUSE</span>
551
<p class="level2">Send a Pause command to the server. Use the <a class="emphasis" href="#CURLOPTRANGE">CURLOPT_RANGE</a> option with a single value to indicate when the stream should be halted. (e.g. npt='25') (Added in 7.20.0)
552
<p class="level1"><a name="CURLRTSPREQTEARDOWN"></a><span class="nroffip">CURL_RTSPREQ_TEARDOWN</span>
553
<p class="level2">This command terminates an RTSP session. Simply closing a connection does not terminate the RTSP session since it is valid to control an RTSP session over different connections. (Added in 7.20.0)
554
<p class="level1"><a name="CURLRTSPREQGETPARAMETER"></a><span class="nroffip">CURL_RTSPREQ_GET_PARAMETER</span>
555
<p class="level2">Retrieve a parameter from the server. By default, libcurl will automatically include a <span Class="emphasis">Content-Type: text/parameters</span> header on all non-empty requests unless a custom one is set. GET_PARAMETER acts just like an HTTP PUT or POST (see <a class="emphasis" href="#CURLRTSPREQSETPARAMETER">CURL_RTSPREQ_SET_PARAMETER</a>). Applications wishing to send a heartbeat message (e.g. in the presence of a server-specified timeout) should send use an empty GET_PARAMETER request. (Added in 7.20.0)
556
<p class="level1"><a name="CURLRTSPREQSETPARAMETER"></a><span class="nroffip">CURL_RTSPREQ_SET_PARAMETER</span>
557
<p class="level2">Set a parameter on the server. By default, libcurl will automatically include a <span Class="emphasis">Content-Type: text/parameters</span> header unless a custom one is set. The interaction with SET_PARAMTER is much like an HTTP PUT or POST. An application may either use <a class="emphasis" href="#CURLOPTUPLOAD">CURLOPT_UPLOAD</a> with <a class="emphasis" href="#CURLOPTREADDATA">CURLOPT_READDATA</a> like an HTTP PUT, or it may use <a class="emphasis" href="#CURLOPTPOSTFIELDS">CURLOPT_POSTFIELDS</a> like an HTTP POST. No chunked transfers are allowed, so the application must set the <a class="emphasis" href="#CURLOPTINFILESIZE">CURLOPT_INFILESIZE</a> in the former and <a class="emphasis" href="#CURLOPTPOSTFIELDSIZE">CURLOPT_POSTFIELDSIZE</a> in the latter. Also, there is no use of multi-part POSTs within RTSP. (Added in 7.20.0)
558
<p class="level1"><a name="CURLRTSPREQRECORD"></a><span class="nroffip">CURL_RTSPREQ_RECORD</span>
559
<p class="level2">Used to tell the server to record a session. Use the <a class="emphasis" href="#CURLOPTRANGE">CURLOPT_RANGE</a> option to modify the record time. (Added in 7.20.0)
560
<p class="level1"><a name="CURLRTSPREQRECEIVE"></a><span class="nroffip">CURL_RTSPREQ_RECEIVE</span>
561
<p class="level2">This is a special request because it does not send any data to the server. The application may call this function in order to receive interleaved RTP data. It will return after processing one read buffer of data in order to give the application a chance to run. (Added in 7.20.0)
563
<p class="level0"><a name="CURLOPTRTSPSESSIONID"></a><span class="nroffip">CURLOPT_RTSP_SESSION_ID</span>
564
<p class="level1">Pass a char * as a parameter to set the value of the current RTSP Session ID for the handle. Useful for resuming an in-progress session. Once this value is set to any non-NULL value, libcurl will return <span Class="emphasis">CURLE_RTSP_SESSION_ERROR</span> if ID received from the server does not match. If unset (or set to NULL), libcurl will automatically set the ID the first time the server sets it in a response. (Added in 7.20.0)
565
<p class="level0"><a name="CURLOPTRTSPSTREAMURI"></a><span class="nroffip">CURLOPT_RTSP_STREAM_URI</span>
566
<p class="level1">Set the stream URI to operate on by passing a char * . For example, a single session may be controlling <span Class="emphasis">rtsp://foo/twister/audio</span> and <span Class="emphasis">rtsp://foo/twister/video</span> and the application can switch to the appropriate stream using this option. If unset, libcurl will default to operating on generic server options by passing '*' in the place of the RTSP Stream URI. This option is distinct from <a class="emphasis" href="#CURLOPTURL">CURLOPT_URL</a>. When working with RTSP, the <span Class="emphasis">CURLOPT_STREAM_URI</span> indicates what URL to send to the server in the request header while the <a class="emphasis" href="#CURLOPTURL">CURLOPT_URL</a> indicates where to make the connection to. (e.g. the <a class="emphasis" href="#CURLOPTURL">CURLOPT_URL</a> for the above examples might be set to <span Class="emphasis">rtsp://foo/twister</span> (Added in 7.20.0)
567
<p class="level0"><a name="CURLOPTRTSPTRANSPORT"></a><span class="nroffip">CURLOPT_RTSP_TRANSPORT</span>
568
<p class="level1">Pass a char * to tell libcurl what to pass for the Transport: header for this RTSP session. This is mainly a convenience method to avoid needing to set a custom Transport: header for every SETUP request. The application must set a Transport: header before issuing a SETUP request. (Added in 7.20.0)
569
<p class="level0"><a name="CURLOPTRTSPHEADER"></a><span class="nroffip">CURLOPT_RTSP_HEADER</span>
570
<p class="level1">This option is simply an alias for <a class="emphasis" href="#CURLOPTHTTPHEADER">CURLOPT_HTTP_HEADER</a>. Use this to replace the standard headers that RTSP and HTTP share. It is also valid to use the shortcuts such as <a class="emphasis" href="#CURLOPTUSERAGENT">CURLOPT_USERAGENT</a>. (Added in 7.20.0)
571
<p class="level0"><a name="CURLOPTRTSPCLIENTCSEQ"></a><span class="nroffip">CURLOPT_RTSP_CLIENT_CSEQ</span>
572
<p class="level1">Manually set the the CSEQ number to issue for the next RTSP request. Useful if the application is resuming a previously broken connection. The CSEQ will increment from this new number henceforth. (Added in 7.20.0)
573
<p class="level0"><a name="CURLOPTRTSPSERVERCSEQ"></a><span class="nroffip">CURLOPT_RTSP_SERVER_CSEQ</span>
574
<p class="level1">Manually set the CSEQ number to expect for the next RTSP Server->Client request. At the moment, this feature (listening for Server requests) is unimplemented. (Added in 7.20.0) <a name="PROTOCOL"></a><h2 class="nroffsh">PROTOCOL OPTIONS</h2>
479
575
<p class="level0">
480
576
<p class="level0"><a name="CURLOPTTRANSFERTEXT"></a><span class="nroffip">CURLOPT_TRANSFERTEXT</span>
481
577
<p class="level1">A parameter set to 1 tells the library to use ASCII mode for FTP transfers, instead of the default binary transfer. For win32 systems it does not set the stdout to binary mode. This option can be usable when transferring text data between systems with different views on certain characters, such as newlines or similar.
485
581
<p class="level0"><a name="CURLOPTCRLF"></a><span class="nroffip">CURLOPT_CRLF</span>
486
582
<p class="level1">Convert Unix newlines to CRLF newlines on transfers.
487
583
<p class="level0"><a name="CURLOPTRANGE"></a><span class="nroffip">CURLOPT_RANGE</span>
488
<p class="level1">Pass a char * as parameter, which should contain the specified range you want. It should be in the format "X-Y", where X or Y may be left out. HTTP transfers also support several intervals, separated with commas as in <span Class="emphasis">"X-Y,N-M"</span>. Using this kind of multiple intervals will cause the HTTP server to send the response document in pieces (using standard MIME separation techniques). Pass a NULL to this option to disable the use of ranges.
489
<p class="level1">Ranges work on HTTP, FTP and FILE (since 7.18.0) transfers only.
584
<p class="level1">Pass a char * as parameter, which should contain the specified range you want. It should be in the format "X-Y", where X or Y may be left out. HTTP transfers also support several intervals, separated with commas as in <span Class="emphasis">"X-Y,N-M"</span>. Using this kind of multiple intervals will cause the HTTP server to send the response document in pieces (using standard MIME separation techniques). For RTSP, the formatting of a range should follow RFC 2326 Section 12.29. For RTSP, byte ranges are <span Class="bold">not</span> permitted. Instead, ranges should be given in npt, utc, or smpte formats.
585
<p class="level1">Pass a NULL to this option to disable the use of ranges.
586
<p class="level1">Ranges work on HTTP, FTP, FILE (since 7.18.0), and RTSP (since 7.20.0) transfers only.
490
587
<p class="level0"><a name="CURLOPTRESUMEFROM"></a><span class="nroffip">CURLOPT_RESUME_FROM</span>
491
588
<p class="level1">Pass a long as parameter. It contains the offset in number of bytes that you want the transfer to start from. Set this option to 0 to make the transfer start from the beginning (effectively disabling resume). For FTP, set this option to -1 to make the transfer start from the end of the target file (useful to continue an interrupted upload).
492
589
<p class="level0"><a name="CURLOPTRESUMEFROMLARGE"></a><span class="nroffip">CURLOPT_RESUME_FROM_LARGE</span>
506
603
<p class="level0"><a name="CURLOPTINFILESIZE"></a><span class="nroffip">CURLOPT_INFILESIZE</span>
507
604
<p class="level1">When uploading a file to a remote site, this option should be used to tell libcurl what the expected size of the infile is. This value should be passed as a long. See also <a class="emphasis" href="#CURLOPTINFILESIZELARGE">CURLOPT_INFILESIZE_LARGE</a>.
508
605
<p class="level1">For uploading using SCP, this option or <a class="emphasis" href="#CURLOPTINFILESIZELARGE">CURLOPT_INFILESIZE_LARGE</a> is mandatory.
509
<p class="level1">Note that this option does not limit how much data libcurl will actually send, as that is controlled entirely by what the read callback returns.
606
<p class="level1">This option does not limit how much data libcurl will actually send, as that is controlled entirely by what the read callback returns.
510
607
<p class="level0"><a name="CURLOPTINFILESIZELARGE"></a><span class="nroffip">CURLOPT_INFILESIZE_LARGE</span>
511
608
<p class="level1">When uploading a file to a remote site, this option should be used to tell libcurl what the expected size of the infile is. This value should be passed as a curl_off_t. (Added in 7.11.0)
512
609
<p class="level1">For uploading using SCP, this option or <a class="emphasis" href="#CURLOPTINFILESIZE">CURLOPT_INFILESIZE</a> is mandatory.
513
<p class="level1">Note that this option does not limit how much data libcurl will actually send, as that is controlled entirely by what the read callback returns.
610
<p class="level1">This option does not limit how much data libcurl will actually send, as that is controlled entirely by what the read callback returns.
514
611
<p class="level0"><a name="CURLOPTUPLOAD"></a><span class="nroffip">CURLOPT_UPLOAD</span>
515
612
<p class="level1">A parameter set to 1 tells the library to prepare for an upload. The <a class="emphasis" href="#CURLOPTREADDATA">CURLOPT_READDATA</a> and <a class="emphasis" href="#CURLOPTINFILESIZE">CURLOPT_INFILESIZE</a> or <a class="emphasis" href="#CURLOPTINFILESIZELARGE">CURLOPT_INFILESIZE_LARGE</a> options are also interesting for uploads. If the protocol is HTTP, uploading means using the PUT request unless you tell libcurl otherwise.
516
613
<p class="level1">Using PUT with HTTP 1.1 implies the use of a "Expect: 100-continue" header. You can disable this header with <a class="emphasis" href="#CURLOPTHTTPHEADER">CURLOPT_HTTPHEADER</a> as usual.
522
619
<p class="level1">Pass a curl_off_t as parameter. This allows you to specify the maximum size (in bytes) of a file to download. If the file requested is larger than this value, the transfer will not start and <span Class="emphasis">CURLE_FILESIZE_EXCEEDED</span> will be returned. (Added in 7.11.0)
523
620
<p class="level1">The file size is not always known prior to download, and for such files this option has no effect even if the file transfer ends up being larger than this given limit. This concerns both FTP and HTTP transfers.
524
621
<p class="level0"><a name="CURLOPTTIMECONDITION"></a><span class="nroffip">CURLOPT_TIMECONDITION</span>
525
<p class="level1">Pass a long as parameter. This defines how the <a class="emphasis" href="#CURLOPTTIMEVALUE">CURLOPT_TIMEVALUE</a> time value is treated. You can set this parameter to <span Class="emphasis">CURL_TIMECOND_IFMODSINCE</span> or <span Class="emphasis">CURL_TIMECOND_IFUNMODSINCE</span>. This feature applies to HTTP and FTP.
622
<p class="level1">Pass a long as parameter. This defines how the <a class="emphasis" href="#CURLOPTTIMEVALUE">CURLOPT_TIMEVALUE</a> time value is treated. You can set this parameter to <span Class="emphasis">CURL_TIMECOND_IFMODSINCE</span> or <span Class="emphasis">CURL_TIMECOND_IFUNMODSINCE</span>. This feature applies to HTTP, FTP, and RTSP.
526
623
<p class="level1">The last modification time of a file is not always known and in such instances this feature will have no effect even if the given time condition would not have been met. <a class="emphasis" href="./curl_easy_getinfo.html">curl_easy_getinfo(3)</a> with the <span Class="emphasis">CURLINFO_CONDITION_UNMET</span> option can be used after a transfer to learn if a zero-byte successful "transfer" was due to this condition not matching.
527
624
<p class="level0"><a name="CURLOPTTIMEVALUE"></a><span class="nroffip">CURLOPT_TIMEVALUE</span>
528
625
<p class="level1">Pass a long as parameter. This should be the time in seconds since 1 Jan 1970, and the time will be used in a condition as specified with <a class="emphasis" href="#CURLOPTTIMECONDITION">CURLOPT_TIMECONDITION</a>. <a name="CONNECTION"></a><h2 class="nroffsh">CONNECTION OPTIONS</h2>
544
641
<p class="level1">Pass a long. The set number will be the persistent connection cache size. The set amount will be the maximum amount of simultaneously open connections that libcurl may cache in this easy handle. Default is 5, and there isn't much point in changing this value unless you are perfectly aware of how this works and changes libcurl's behaviour. This concerns connections using any of the protocols that support persistent connections.
545
642
<p class="level1">When reaching the maximum limit, curl closes the oldest one in the cache to prevent increasing the number of open connections.
546
643
<p class="level1">If you already have performed transfers with this curl handle, setting a smaller MAXCONNECTS than before may cause open connections to get closed unnecessarily.
547
<p class="level1">Note that if you add this easy handle to a multi handle, this setting is not acknowledged, and you must instead use <a class="emphasis" href="./curl_multi_setopt.html">curl_multi_setopt(3)</a> and the <span Class="emphasis">CURLMOPT_MAXCONNECTS</span> option.
644
<p class="level1">If you add this easy handle to a multi handle, this setting is not acknowledged, and you must instead use <a class="emphasis" href="./curl_multi_setopt.html">curl_multi_setopt(3)</a> and the <span Class="emphasis">CURLMOPT_MAXCONNECTS</span> option.
548
645
<p class="level0"><a name="CURLOPTCLOSEPOLICY"></a><span class="nroffip">CURLOPT_CLOSEPOLICY</span>
549
646
<p class="level1">(Obsolete) This option does nothing.
550
647
<p class="level0"><a name="CURLOPTFRESHCONNECT"></a><span class="nroffip">CURLOPT_FRESH_CONNECT</span>
589
686
<p class="level0"><a name="CURLOPTSSLENGINEDEFAULT"></a><span class="nroffip">CURLOPT_SSLENGINE_DEFAULT</span>
590
687
<p class="level1">Sets the actual crypto engine as the default for (asymmetric) crypto operations.
591
688
<p class="level1">If the crypto device cannot be set, <span Class="emphasis">CURLE_SSL_ENGINE_SETFAILED</span> is returned.
592
<p class="level1">Note that even though this option doesn't need any parameter, in some configurations <span Class="emphasis">curl_easy_setopt</span> might be defined as a macro taking exactly three arguments. Therefore, it's recommended to pass 1 as parameter to this option.
689
<p class="level1">Even though this option doesn't need any parameter, in some configurations <span Class="emphasis">curl_easy_setopt</span> might be defined as a macro taking exactly three arguments. Therefore, it's recommended to pass 1 as parameter to this option.
593
690
<p class="level0"><a name="CURLOPTSSLVERSION"></a><span class="nroffip">CURLOPT_SSLVERSION</span>
594
691
<p class="level1">Pass a long as parameter to control what version of SSL/TLS to attempt to use. The available options are:
595
692
<p class="level2">
610
707
<p class="level1">Authenticating the certificate is not by itself very useful. You typically want to ensure that the server, as authentically identified by its certificate, is the server you mean to be talking to. Use <a class="emphasis" href="#CURLOPTSSLVERIFYHOST">CURLOPT_SSL_VERIFYHOST</a> to control that.
611
708
<p class="level0"><a name="CURLOPTCAINFO"></a><span class="nroffip">CURLOPT_CAINFO</span>
612
709
<p class="level1">Pass a char * to a zero terminated string naming a file holding one or more certificates to verify the peer with. This makes sense only when used in combination with the <a class="emphasis" href="#CURLOPTSSLVERIFYPEER">CURLOPT_SSL_VERIFYPEER</a> option. If <a class="emphasis" href="#CURLOPTSSLVERIFYPEER">CURLOPT_SSL_VERIFYPEER</a> is zero, <a class="emphasis" href="#CURLOPTCAINFO">CURLOPT_CAINFO</a> need not even indicate an accessible file.
613
<p class="level1">Note that option is by default set to the system path where libcurl's cacert bundle is assumed to be stored, as established at build time.
710
<p class="level1">This option is by default set to the system path where libcurl's cacert bundle is assumed to be stored, as established at build time.
614
711
<p class="level1">When built against NSS, this is the directory that the NSS certificate database resides in.
615
712
<p class="level0"><a name="CURLOPTISSUERCERT"></a><span class="nroffip">CURLOPT_ISSUERCERT</span>
616
713
<p class="level1">Pass a char * to a zero terminated string naming a file holding a CA certificate in PEM format. If the option is set, an additional check against the peer certificate is performed to verify the issuer is indeed the one associated with the certificate provided by the option. This additional check is useful in multi-level PKI where one needs to enforce that the peer certificate is from a specific branch of the tree.
622
719
<p class="level1">Pass a char * to a zero terminated string naming a file with the concatenation of CRL (in PEM format) to use in the certificate validation that occurs during the SSL exchange.
623
720
<p class="level1">When curl is built to use NSS or GnuTLS, there is no way to influence the use of CRL passed to help in the verification process. When libcurl is built with OpenSSL support, X509_V_FLAG_CRL_CHECK and X509_V_FLAG_CRL_CHECK_ALL are both set, requiring CRL check against all the elements of the certificate chain if a CRL file is passed.
624
721
<p class="level1">This option makes sense only when used in combination with the <a class="emphasis" href="#CURLOPTSSLVERIFYPEER">CURLOPT_SSL_VERIFYPEER</a> option.
625
<p class="level1">A specific error code (CURLE_SSL_CRL_BADFILE) is defined with the option. It is returned when the SSL exchange fails because the CRL file cannot be loaded. Note that a failure in certificate verification due to a revocation information found in the CRL does not trigger this specific error. (Added in 7.19.0)
722
<p class="level1">A specific error code (CURLE_SSL_CRL_BADFILE) is defined with the option. It is returned when the SSL exchange fails because the CRL file cannot be loaded. A failure in certificate verification due to a revocation information found in the CRL does not trigger this specific error. (Added in 7.19.0)
626
723
<p class="level0"><a name="CURLOPTCERTINFO"></a><span class="nroffip">CURLOPT_CERTINFO</span>
627
724
<p class="level1">Pass a long set to 1 to enable libcurl's certificate chain info gatherer. With this enabled, libcurl (if built with OpenSSL) will extract lots of information and data about the certificates in the certificate chain used in the SSL connection. This data is then possible to extract after a transfer using <a class="emphasis" href="./curl_easy_getinfo.html">curl_easy_getinfo(3)</a> and its option <span Class="emphasis">CURLINFO_CERTINFO</span>. (Added in 7.19.1)
628
725
<p class="level0"><a name="CURLOPTRANDOMFILE"></a><span class="nroffip">CURLOPT_RANDOM_FILE</span>
647
744
<p class="level1">You'll find more details about the NSS cipher lists on this URL: <span Class="emphasis"><a href="http://directory.fedora.redhat.com/docs/mod_nss.html">http://directory.fedora.redhat.com/docs/mod_nss.html</a>#Directives</span>
648
745
<p class="level1">
649
746
<p class="level0"><a name="CURLOPTSSLSESSIONIDCACHE"></a><span class="nroffip">CURLOPT_SSL_SESSIONID_CACHE</span>
650
<p class="level1">Pass a long set to 0 to disable libcurl's use of SSL session-ID caching. Set this to 1 to enable it. By default all transfers are done using the cache. Note that while nothing ever should get hurt by attempting to reuse SSL session-IDs, there seem to be broken SSL implementations in the wild that may require you to disable this in order for you to succeed. (Added in 7.16.0)
747
<p class="level1">Pass a long set to 0 to disable libcurl's use of SSL session-ID caching. Set this to 1 to enable it. By default all transfers are done using the cache. While nothing ever should get hurt by attempting to reuse SSL session-IDs, there seem to be broken SSL implementations in the wild that may require you to disable this in order for you to succeed. (Added in 7.16.0)
651
748
<p class="level0"><a name="CURLOPTKRBLEVEL"></a><span class="nroffip">CURLOPT_KRBLEVEL</span>
652
749
<p class="level1">Pass a char * as parameter. Set the kerberos security level for FTP; this also enables kerberos awareness. This is a string, 'clear', 'safe', 'confidential' or 'private'. If the string is set but doesn't match one of these, 'private' will be used. Set the string to NULL to disable kerberos support for FTP.
653
750
<p class="level1">(This option was known as CURLOPT_KRB4LEVEL up to 7.16.3) <a name="SSH"></a><h2 class="nroffsh">SSH OPTIONS</h2>
659
756
<p class="level0"><a name="CURLOPTSSHPUBLICKEYFILE"></a><span class="nroffip">CURLOPT_SSH_PUBLIC_KEYFILE</span>
660
757
<p class="level1">Pass a char * pointing to a file name for your public key. If not used, libcurl defaults to using <span Class="bold">~/.ssh/id_dsa.pub</span>. (Added in 7.16.1)
661
758
<p class="level0"><a name="CURLOPTSSHPRIVATEKEYFILE"></a><span class="nroffip">CURLOPT_SSH_PRIVATE_KEYFILE</span>
662
<p class="level1">Pass a char * pointing to a file name for your private key. If not used, libcurl defaults to using <span Class="bold">~/.ssh/id_dsa</span>. If the file is password-protected, set the password with <a class="emphasis" href="#CURLOPTKEYPASSWD">CURLOPT_KEYPASSWD</a>. (Added in 7.16.1)
759
<p class="level1">Pass a char * pointing to a file name for your private key. If not used, libcurl defaults to using <span Class="bold">~/.ssh/id_dsa</span>. If the file is password-protected, set the password with <a class="emphasis" href="#CURLOPTKEYPASSWD">CURLOPT_KEYPASSWD</a>. (Added in 7.16.1)
663
760
<p class="level0"><a name="CURLOPTSSHKNOWNHOSTS"></a><span class="nroffip">CURLOPT_SSH_KNOWNHOSTS</span>
664
761
<p class="level1">Pass a pointer to a zero terminated string holding the file name of the known_host file to use. The known_hosts file should use the OpenSSH file format as supported by libssh2. If this file is specified, libcurl will only accept connections with hosts that are known and present in that file, with a matching public key. Use <a class="emphasis" href="#CURLOPTSSHKEYFUNCTION">CURLOPT_SSH_KEYFUNCTION</a> to alter the default behavior on host and key (mis)matching. (Added in 7.19.6)
665
762
<p class="level0"><a name="CURLOPTSSHKEYFUNCTION"></a><span class="nroffip">CURLOPT_SSH_KEYFUNCTION</span>
666
763
<p class="level1">Pass a pointer to a curl_sshkeycallback function. It gets called when the known_host matching has been done, to allow the application to act and decide for libcurl how to proceed. It gets passed the CURL handle, the key from the known_hosts file, the key from the remote site, info from libcurl on the matching status and a custom pointer (set with <a class="emphasis" href="#CURLOPTSSHKEYDATA">CURLOPT_SSH_KEYDATA</a>). It MUST return one of the following return codes to tell libcurl how to act:
667
764
<p class="level2">
668
765
<p class="level1"><a name="CURLKHSTATFINEADDTOFILE"></a><span class="nroffip">CURLKHSTAT_FINE_ADD_TO_FILE</span>
669
<p class="level2">The host+key is accepted and libcurl will append it to the known_hosts file before continuing with the connection. This will also add the host+key combo to the known_host pool kept in memory if it wasn't already present there. Note that the adding of data to the file is done by completely replacing the file with a new copy, so the permissions of the file must allow this.
766
<p class="level2">The host+key is accepted and libcurl will append it to the known_hosts file before continuing with the connection. This will also add the host+key combo to the known_host pool kept in memory if it wasn't already present there. The adding of data to the file is done by completely replacing the file with a new copy, so the permissions of the file must allow this.
670
767
<p class="level1"><a name="CURLKHSTATFINE"></a><span class="nroffip">CURLKHSTAT_FINE</span>
671
768
<p class="level2">The host+key is accepted libcurl will continue with the connection. This will also add the host+key combo to the known_host pool kept in memory if it wasn't already present there.
672
769
<p class="level1"><a name="CURLKHSTATREJECT"></a><span class="nroffip">CURLKHSTAT_REJECT</span>
added
removed
docs/libcurl/curl_easy_setopt.html
