65
65
this when you debug/report problems. Another neat option for debugging is the
66
66
\fICURLOPT_DEBUGFUNCTION\fP.
68
A non-zero parameter tells the library to include the header in the body
68
A parameter set to 1 tells the library to include the header in the body
69
69
output. This is only relevant for protocols that actually have headers
70
70
preceding the data (like HTTP).
71
71
.IP CURLOPT_NOPROGRESS
72
A non-zero parameter tells the library to shut off the built-in progress meter
72
A parameter set to 1 tells the library to shut off the built-in progress meter
75
Future versions of libcurl is likely to not have any built-in progress meter
75
Future versions of libcurl are likely to not have any built-in progress meter
77
77
.IP CURLOPT_NOSIGNAL
78
Pass a long. If it is non-zero, libcurl will not use any functions that
78
Pass a long. If it is 1, libcurl will not use any functions that
79
79
install signal handlers or any functions that cause signals to be sent to the
80
80
process. This option is mainly here to allow multi-threaded unix applications
81
81
to still set/use all timeout options etc, without risking getting signals.
84
Consider building libcurl with ares support to enable asynchronous DNS
85
lookups. It enables nice timeouts for name resolves without signals.
84
If this option is set and libcurl has been built with the standard name
85
resolver, timeouts will not occur while the name resolve takes place.
86
Consider building libcurl with c-ares support to enable asynchronous DNS
87
lookups, which enables nice timeouts for name resolves without signals.
87
89
.SH CALLBACK OPTIONS
88
90
.IP CURLOPT_WRITEFUNCTION
431
433
given protocol of the set URL is not supported, libcurl will return on error
432
434
(\fICURLE_UNSUPPORTED_PROTOCOL\fP) when you call \fIcurl_easy_perform(3)\fP or
433
435
\fIcurl_multi_perform(3)\fP. Use \fIcurl_version_info(3)\fP for detailed info
434
on which protocols that are supported.
436
on which protocols are supported.
436
The string given to CURLOPT_URL must be url-encoded and following the RFC 2396
438
The string given to CURLOPT_URL must be url-encoded and follow RFC 2396
437
439
(http://curl.haxx.se/rfc/rfc2396.txt).
439
441
\fICURLOPT_URL\fP is the only option that \fBmust\fP be set before
440
442
\fIcurl_easy_perform(3)\fP is called.
444
\fICURLOPT_PROTOCOLS\fP can be used to limit what protocols libcurl will use
445
for this transfer, independent of what libcurl has been compiled to
446
support. That may be useful if you accept the URL from an external source and
447
want to limit the accessibility.
448
.IP CURLOPT_PROTOCOLS
449
Pass a long that holds a bitmask of CURLPROTO_* defines. If used, this bitmask
450
limits what protocols libcurl may use in the transfer. This allows you to have
451
a libcurl built to support a wide range of protocols but still limit specific
452
transfers to only be allowed to use a subset of them. By default libcurl will
453
accept all protocols it supports. See also
454
\fICURLOPT_REDIR_PROTOCOLS\fP. (Added in 7.19.4)
455
.IP CURLOPT_REDIR_PROTOCOLS
456
Pass a long that holds a bitmask of CURLPROTO_* defines. If used, this bitmask
457
limits what protocols libcurl may use in a transfer that it follows to in a
458
redirect when \fICURLOPT_FOLLOWLOCATION\fP is enabled. This allows you to
459
limit specific transfers to only be allowed to use a subset of protocols in
460
redirections. By default libcurl will allow all protocols except for FILE and
461
SCP. This is a difference compared to pre-7.19.4 versions which
462
unconditionally would follow to all protocols supported. (Added in 7.19.4)
441
463
.IP CURLOPT_PROXY
442
464
Set HTTP proxy to use. The parameter should be a char * to a zero terminated
443
465
string holding the host name or dotted IP address. To specify port number in
444
466
this string, append :[port] to the end of the host name. The proxy string may
445
467
be prefixed with [protocol]:// since any such prefix will be ignored. The
446
proxy's port number may optionally be specified with the separate option
468
proxy's port number may optionally be specified with the separate option. If
469
not specified, libcurl will default to using port 1080 for proxies.
447
470
\fICURLOPT_PROXYPORT\fP.
449
472
When you tell the library to use an HTTP proxy, libcurl will transparently
468
491
specified in the proxy string \fICURLOPT_PROXY\fP.
469
492
.IP CURLOPT_PROXYTYPE
470
493
Pass a long with this option to set type of the proxy. Available options for
471
this are \fICURLPROXY_HTTP\fP, \fICURLPROXY_SOCKS4\fP (added in 7.15.2),
472
\fICURLPROXY_SOCKS5\fP, \fICURLPROXY_SOCKS4A\fP (added in 7.18.0) and
473
\fICURLPROXY_SOCKS5_HOSTNAME\fP (added in 7.18.0). The HTTP type is
474
default. (Added in 7.10)
494
this are \fICURLPROXY_HTTP\fP, \fICURLPROXY_HTTP_1_0\fP (added in 7.19.4),
495
\fICURLPROXY_SOCKS4\fP (added in 7.15.2), \fICURLPROXY_SOCKS5\fP,
496
\fICURLPROXY_SOCKS4A\fP (added in 7.18.0) and \fICURLPROXY_SOCKS5_HOSTNAME\fP
497
(added in 7.18.0). The HTTP type is default. (Added in 7.10)
499
Pass a pointer to a zero terminated string. The should be a comma- separated
500
list of hosts which do not use a proxy, if one is specified. The only
501
wildcard is a single * character, which matches all hosts, and effectively
502
disables the proxy. Each name in this list is matched as either a domain which
503
contains the hostname, or the hostname itself. For example, local.com would
504
match local.com, local.com:80, and www.local.com, but not www.notlocal.com.
475
506
.IP CURLOPT_HTTPPROXYTUNNEL
476
Set the parameter to non-zero to get the library to tunnel all operations
477
through a given HTTP proxy. There is a big difference between using a proxy
478
and to tunnel through it. If you don't know what this means, you probably
479
don't want this tunneling option.
480
.IP CURLOPT_SOCKS5_RESOLVE_LOCAL
481
Set the parameter to 1 to get the library to resolve the host name locally
482
instead of passing it to the proxy to resolve, when using a SOCKS5 proxy.
484
Note that libcurl before 7.18.0 always resolved the host name locally even
485
when SOCKS5 was used. (Added in 7.18.0)
507
Set the parameter to 1 to make the library tunnel all operations through a
508
given HTTP proxy. There is a big difference between using a proxy and to
509
tunnel through it. If you don't know what this means, you probably don't want
510
this tunneling option.
511
.IP CURLOPT_SOCKS5_GSSAPI_SERVICE
512
Pass a char * as parameter to a string holding the name of the service. The
513
default service name for a SOCKS5 server is rcmd/server-fqdn. This option
514
allows you to change it. (Added in 7.19.4)
515
.IP CURLOPT_SOCKS5_GSSAPI_NEC
516
Pass a long set to 1 to enable or 0 to disable. As part of the gssapi
517
negotiation a protection mode is negotiated. The rfc1961 says in section
518
4.3/4.4 it should be protected, but the NEC reference implementation does not.
519
If enabled, this option allows the unprotected exchange of the protection mode
520
negotiation. (Added in 7.19.4).
486
521
.IP CURLOPT_INTERFACE
487
Pass a char * as parameter. This set the interface name to use as outgoing
488
network interface. The name can be an interface name, an IP address or a host
522
Pass a char * as parameter. This sets the interface name to use as outgoing
523
network interface. The name can be an interface name, an IP address, or a host
490
525
.IP CURLOPT_LOCALPORT
491
526
Pass a long. This sets the local port number of the socket used for
492
527
connection. This can be used in combination with \fICURLOPT_INTERFACE\fP and
493
528
you are recommended to use \fICURLOPT_LOCALPORTRANGE\fP as well when this is
494
set. Note that port numbers are only valid 1 - 65535. (Added in 7.15.2)
529
set. Note that the only valid port numbers are 1 - 65535. (Added in 7.15.2)
495
530
.IP CURLOPT_LOCALPORTRANGE
496
Pass a long. This is the number of attempts libcurl should do to find a
531
Pass a long. This is the number of attempts libcurl should make to find a
497
532
working local port number. It starts with the given \fICURLOPT_LOCALPORT\fP
498
and adds one to the number for each retry. Setting this value to 1 or below
499
will make libcurl do only one try for exact port number. Note that port
500
numbers by nature is a scarce resource that will be busy at times so setting
501
this value to something too low might cause unnecessary connection setup
533
and adds one to the number for each retry. Setting this to 1 or below will
534
make libcurl do only one try for the exact port number. Note that port numbers
535
by nature are scarce resources that will be busy at times so setting this
536
value to something too low might cause unnecessary connection setup
502
537
failures. (Added in 7.15.2)
503
538
.IP CURLOPT_DNS_CACHE_TIMEOUT
504
539
Pass a long, this sets the timeout in seconds. Name resolves will be kept in
505
memory for this number of seconds. Set to zero (0) to completely disable
540
memory for this number of seconds. Set to zero to completely disable
506
541
caching, or set to -1 to make the cached entries remain forever. By default,
507
542
libcurl caches this info for 60 seconds.
544
NOTE: the name resolve functions of various libc implementations don't re-read
545
name server information unless explicitly told so (for example, by calling
546
\fIres_init(3)\fP). This may cause libcurl to keep using the older server even
547
if DHCP has updated the server info, and this may look like a DNS cache issue
548
to the casual libcurl-app user.
508
549
.IP CURLOPT_DNS_USE_GLOBAL_CACHE
509
Pass a long. If the value is non-zero, it tells curl to use a global DNS cache
550
Pass a long. If the value is 1, it tells curl to use a global DNS cache
510
551
that will survive between easy handle creations and deletions. This is not
511
552
thread-safe and this will use a global variable.
579
622
Pass a char * as parameter, pointing to a zero terminated string containing
580
623
the full path name to the file you want libcurl to use as .netrc file. If this
581
624
option is omitted, and \fICURLOPT_NETRC\fP is set, libcurl will attempt to
582
find the a .netrc file in the current user's home directory. (Added in 7.10.9)
625
find a .netrc file in the current user's home directory. (Added in 7.10.9)
583
626
.IP CURLOPT_USERPWD
584
627
Pass a char * as parameter, which should be [user name]:[password] to use for
585
the connection. Use \fICURLOPT_HTTPAUTH\fP to decide authentication method.
628
the connection. Use \fICURLOPT_HTTPAUTH\fP to decide the authentication method.
587
When using NTLM, you can set domain by prepending it to the user name and
630
When using NTLM, you can set the domain by prepending it to the user name and
588
631
separating the domain and name with a forward (/) or backward slash (\\). Like
589
632
this: "domain/user:password" or "domain\\user:password". Some HTTP servers (on
590
633
Windows) support this style even for Basic authentication.
598
641
.IP CURLOPT_PROXYUSERPWD
599
642
Pass a char * as parameter, which should be [user name]:[password] to use for
600
643
the connection to the HTTP proxy. Use \fICURLOPT_PROXYAUTH\fP to decide
601
authentication method.
644
the authentication method.
646
Pass a char * as parameter, which should be pointing to the zero terminated
647
user name to use for the transfer.
649
\fBCURLOPT_USERNAME\fP sets the user name to be used in protocol
650
authentication. You should not use this option together with the (older)
651
CURLOPT_USERPWD option.
653
In order to specify the password to be used in conjunction with the user name
654
use the \fICURLOPT_PASSWORD\fP option. (Added in 7.19.1)
656
Pass a char * as parameter, which should be pointing to the zero terminated
657
password to use for the transfer.
659
The CURLOPT_PASSWORD option should be used in conjunction with
660
the \fICURLOPT_USERNAME\fP option. (Added in 7.19.1)
661
.IP CURLOPT_PROXYUSERNAME
662
Pass a char * as parameter, which should be pointing to the zero terminated
663
user name to use for the transfer while connecting to Proxy.
665
The CURLOPT_PROXYUSERNAME option should be used in same way as the
666
\fICURLOPT_PROXYUSERPWD\fP is used. In comparison to \fICURLOPT_PROXYUSERPWD\fP
667
the CURLOPT_PROXYUSERNAME allows the username to contain a colon,
668
like in the following example: "sip:user@example.com".
669
Note the CURLOPT_PROXYUSERNAME option is an alternative way to set the user name
670
while connecting to Proxy. There is no meaning to use it together
671
with the \fICURLOPT_PROXYUSERPWD\fP option.
673
In order to specify the password to be used in conjunction with the user name
674
use the \fICURLOPT_PROXYPASSWORD\fP option. (Added in 7.19.1)
675
.IP CURLOPT_PROXYPASSWORD
676
Pass a char * as parameter, which should be pointing to the zero terminated
677
password to use for the transfer while connecting to Proxy.
679
The CURLOPT_PROXYPASSWORD option should be used in conjunction with
680
the \fICURLOPT_PROXYUSERNAME\fP option. (Added in 7.19.1)
602
681
.IP CURLOPT_HTTPAUTH
603
Pass a long as parameter, which is set to a bitmask, to tell libcurl what
682
Pass a long as parameter, which is set to a bitmask, to tell libcurl which
604
683
authentication method(s) you want it to use. The available bits are listed
605
684
below. If more than one bit is set, libcurl will first query the site to see
606
what authentication methods it supports and then pick the best one you allow
685
which authentication methods it supports and then pick the best one you allow
607
686
it to use. For some methods, this will induce an extra network round-trip. Set
608
the actual name and password with the \fICURLOPT_USERPWD\fP option. (Added in
687
the actual name and password with the \fICURLOPT_USERPWD\fP option or
688
with the \fICURLOPT_USERNAME\fP and the \fICURLOPT_USERPASSWORD\fP options.
611
691
.IP CURLAUTH_BASIC
612
692
HTTP Basic authentication. This is the default choice, and the only method
613
that is in wide-spread use and supported virtually everywhere. This is sending
693
that is in wide-spread use and supported virtually everywhere. This sends
614
694
the user name and password over the network in plain text, easily captured by
616
696
.IP CURLAUTH_DIGEST
617
697
HTTP Digest authentication. Digest authentication is defined in RFC2617 and
618
698
is a more secure way to do authentication over public networks than the
619
699
regular old-fashioned Basic method.
700
.IP CURLAUTH_DIGEST_IE
701
HTTP Digest authentication with an IE flavor. Digest authentication is
702
defined in RFC2617 and is a more secure way to do authentication over public
703
networks than the regular old-fashioned Basic method. The IE flavor is simply
704
that libcurl will use a special "quirk" that IE is known to have used before
705
version 7 and that some servers require the client to use. (This define was
620
707
.IP CURLAUTH_GSSNEGOTIATE
621
708
HTTP GSS-Negotiate authentication. The GSS-Negotiate (also known as plain
622
709
\&"Negotiate") method was designed by Microsoft and is used in their web
623
710
applications. It is primarily meant as a support for Kerberos5 authentication
624
but may be also used along with another authentication methods. For more
711
but may also be used along with other authentication methods. For more
625
712
information see IETF draft draft-brezak-spnego-http-04.txt.
627
714
You need to build libcurl with a suitable GSS-API library for this to work.
653
740
work. (Added in 7.10.7)
655
742
.IP CURLOPT_AUTOREFERER
656
Pass a non-zero parameter to enable this. When enabled, libcurl will
743
Pass a parameter set to 1 to enable this. When enabled, libcurl will
657
744
automatically set the Referer: field in requests where it follows a Location:
659
746
.IP CURLOPT_ENCODING
660
Sets the contents of the Accept-Encoding: header sent in an HTTP
661
request, and enables decoding of a response when a Content-Encoding:
662
header is received. Three encodings are supported: \fIidentity\fP,
663
which does nothing, \fIdeflate\fP which requests the server to
664
compress its response using the zlib algorithm, and \fIgzip\fP which
665
requests the gzip algorithm. If a zero-length string is set, then an
666
Accept-Encoding: header containing all supported encodings is sent.
747
Sets the contents of the Accept-Encoding: header sent in an HTTP request, and
748
enables decoding of a response when a Content-Encoding: header is received.
749
Three encodings are supported: \fIidentity\fP, which does nothing,
750
\fIdeflate\fP which requests the server to compress its response using the
751
zlib algorithm, and \fIgzip\fP which requests the gzip algorithm. If a
752
zero-length string is set, then an Accept-Encoding: header containing all
753
supported encodings is sent.
668
This is a request, not an order; the server may or may not do it. This
669
option must be set (to any non-NULL value) or else any unsolicited
670
encoding done by the server is ignored. See the special file
671
lib/README.encoding for details.
755
This is a request, not an order; the server may or may not do it. This option
756
must be set (to any non-NULL value) or else any unsolicited encoding done by
757
the server is ignored. See the special file lib/README.encoding for details.
672
758
.IP CURLOPT_FOLLOWLOCATION
673
A non-zero parameter tells the library to follow any Location: header that the
759
A parameter set to 1 tells the library to follow any Location: header that the
674
760
server sends as part of an HTTP header.
676
762
This means that the library will re-send the same request on the new location
677
763
and follow new Location: headers all the way until no more such headers are
678
764
returned. \fICURLOPT_MAXREDIRS\fP can be used to limit the number of redirects
679
765
libcurl will follow.
767
NOTE: since 7.19.4, libcurl can limit to what protocols it will automatically
768
follow. The accepted protocols are set with \fICURLOPT_REDIR_PROTOCOLS\fP and
769
it excludes the FILE protocol by default.
680
770
.IP CURLOPT_UNRESTRICTED_AUTH
681
A non-zero parameter tells the library it can continue to send authentication
771
A parameter set to 1 tells the library it can continue to send authentication
682
772
(user+password) when following locations, even when hostname changed. This
683
773
option is meaningful only when setting \fICURLOPT_FOLLOWLOCATION\fP.
684
774
.IP CURLOPT_MAXREDIRS
688
778
\fICURLOPT_FOLLOWLOCATION\fP is used at the same time. Added in 7.15.1:
689
779
Setting the limit to 0 will make libcurl refuse any redirect. Set it to -1 for
690
780
an infinite number of redirects (which is the default)
692
A non-zero parameter tells the library to respect RFC 2616/10.3.2 and not
693
convert POST requests into GET requests when following a 301 redirection. The
694
non-RFC behaviour is ubiquitous in web browsers, so the library does the
695
conversion by default to maintain consistency. However, a server may requires
696
a POST to remain a POST after such a redirection. This option is meaningful
697
only when setting \fICURLOPT_FOLLOWLOCATION\fP. (Added in 7.17.1)
781
.IP CURLOPT_POSTREDIR
782
Pass a bitmask to control how libcurl acts on redirects after POSTs that get a
783
301 or 302 response back. A parameter with bit 0 set (value
784
\fBCURL_REDIR_POST_301\fP) tells the library to respect RFC 2616/10.3.2 and
785
not convert POST requests into GET requests when following a 301
786
redirection. Setting bit 1 (value CURL_REDIR_POST_302) makes libcurl maintain
787
the request method after a 302 redirect. CURL_REDIR_POST_ALL is a convenience
788
define that sets both bits.
790
The non-RFC behaviour is ubiquitous in web browsers, so the library does the
791
conversion by default to maintain consistency. However, a server may require a
792
POST to remain a POST after such a redirection. This option is meaningful only
793
when setting \fICURLOPT_FOLLOWLOCATION\fP. (Added in 7.17.1) (This option was
794
known as CURLOPT_POST301 up to 7.19.0 as it only supported the 301 way before
699
A non-zero parameter tells the library to use HTTP PUT to transfer data. The
797
A parameter set to 1 tells the library to use HTTP PUT to transfer data. The
700
798
data should be set with \fICURLOPT_READDATA\fP and \fICURLOPT_INFILESIZE\fP.
702
800
This option is deprecated and starting with version 7.12.1 you should instead
703
801
use \fICURLOPT_UPLOAD\fP.
705
A non-zero parameter tells the library to do a regular HTTP post. This will
706
also make the library use the a "Content-Type:
803
A parameter set to 1 tells the library to do a regular HTTP post. This will
804
also make the library use a "Content-Type:
707
805
application/x-www-form-urlencoded" header. (This is by far the most commonly
708
806
used POST method).
819
916
create the list and \fIcurl_slist_free_all(3)\fP to clean up an entire
820
917
list. If you add a header that is otherwise generated and used by libcurl
821
918
internally, your added one will be used instead. If you add a header with no
822
contents as in 'Accept:' (no data on the right side of the colon), the
919
content as in 'Accept:' (no data on the right side of the colon), the
823
920
internally used header will get disabled. Thus, using this option you can add
824
921
new headers, replace internal headers and remove internal headers. To add a
825
header with no contents, make the contents be two quotes: \&"". The headers
922
header with no content, make the content be two quotes: \&"". The headers
826
923
included in the linked list must not be CRLF-terminated, because curl adds
827
924
CRLF after each header item. Failure to comply with this will result in
828
925
strange bugs because the server will most likely ignore part of the headers
894
991
will get a warning to display, but that is the only visible feedback you get
895
992
about this possibly lethal situation.
896
993
.IP CURLOPT_COOKIESESSION
897
Pass a long set to non-zero to mark this as a new cookie "session". It will
898
force libcurl to ignore all cookies it is about to load that are "session
899
cookies" from the previous session. By default, libcurl always stores and
900
loads all cookies, independent if they are session cookies are not. Session
901
cookies are cookies without expiry date and they are meant to be alive and
902
existing for this "session" only.
994
Pass a long set to 1 to mark this as a new cookie "session". It will force
995
libcurl to ignore all cookies it is about to load that are "session cookies"
996
from the previous session. By default, libcurl always stores and loads all
997
cookies, independent if they are session cookies or not. Session cookies are
998
cookies without expiry date and they are meant to be alive and existing for
903
1000
.IP CURLOPT_COOKIELIST
904
1001
Pass a char * to a cookie string. Cookie can be either in Netscape / Mozilla
905
1002
format or just regular HTTP-style header (Set-Cookie: ...) format. If cURL
910
1007
all cookies known by cURL to the file specified by \fICURLOPT_COOKIEJAR\fP.
911
1008
(Added in 7.17.1)
912
1009
.IP CURLOPT_HTTPGET
913
Pass a long. If the long is non-zero, this forces the HTTP request to get back
914
to GET. usable if a POST, HEAD, PUT or a custom request have been used
1010
Pass a long. If the long is 1, this forces the HTTP request to get back
1011
to GET. Usable if a POST, HEAD, PUT, or a custom request has been used
915
1012
previously using the same curl handle.
917
When setting \fICURLOPT_HTTPGET\fP to a non-zero value, it will automatically
918
set \fICURLOPT_NOBODY\fP to 0 (since 7.14.1).
1014
When setting \fICURLOPT_HTTPGET\fP to 1, it will automatically set
1015
\fICURLOPT_NOBODY\fP to 0 (since 7.14.1).
919
1016
.IP CURLOPT_HTTP_VERSION
920
1017
Pass a long, set to one of the values described below. They force libcurl to
921
1018
use the specific HTTP versions. This is not sensible to do unless you have a
945
1042
transfer decoding will be disabled, if set to 1 it is enabled
946
1043
(default). libcurl does chunked transfer decoding by default unless this
947
1044
option is set to zero. (added in 7.16.2)
1046
.IP CURLOPT_TFTPBLKSIZE
1047
Specify block size to use for TFTP data transmission. Valid range as per RFC
1048
2348 is 8-65464 bytes. The default of 512 bytes will be used if this option is
1049
not specified. The specified block size will only be used pending support by
1050
the remote server. If the server does not return an option acknowledgement or
1051
returns an option acknowledgement with no blksize, the default of 512 bytes
1052
will be used. (added in 7.19.4)
949
1054
.IP CURLOPT_FTPPORT
950
1055
Pass a pointer to a zero terminated string as parameter. It will be used to
951
get the IP address to use for the ftp PORT instruction. The PORT instruction
1056
get the IP address to use for the FTP PORT instruction. The PORT instruction
952
1057
tells the remote server to connect to our specified IP address. The string may
953
be a plain IP address, a host name, an network interface name (under Unix) or
954
just a '-' letter to let the library use your systems default IP
1058
be a plain IP address, a host name, a network interface name (under Unix) or
1059
just a '-' symbol to let the library use your system's default IP
955
1060
address. Default FTP operations are passive, and thus won't use PORT.
957
1062
You disable PORT again and go back to using the passive version by setting
958
1063
this option to NULL.
959
1064
.IP CURLOPT_QUOTE
960
1065
Pass a pointer to a linked list of FTP or SFTP commands to pass to
961
the server prior to your ftp request. This will be done before any
1066
the server prior to your FTP request. This will be done before any
962
1067
other commands are issued (even before the CWD command for FTP). The
963
1068
linked list should be a fully valid list of 'struct curl_slist' structs
964
1069
properly filled in with text strings. Use \fIcurl_slist_append(3)\fP
965
1070
to append strings (commands) to the list, and clear the entire list
966
1071
afterwards with \fIcurl_slist_free_all(3)\fP. Disable this operation
967
1072
again by setting a NULL to this option.
1073
The set of valid FTP commands depends on the server (see RFC959 for a
1074
list of mandatory commands).
968
1075
The valid SFTP commands are: chgrp, chmod, chown, ln, mkdir, pwd,
969
rename, rm, rmdir, symlink. (SFTP support added in 7.16.3)
1076
rename, rm, rmdir, symlink (see
1078
(SFTP support added in 7.16.3)
970
1079
.IP CURLOPT_POSTQUOTE
971
1080
Pass a pointer to a linked list of FTP or SFTP commands to pass to the
972
server after your ftp transfer request. The linked list should be a
1081
server after your FTP transfer request. The linked list should be a
973
1082
fully valid list of struct curl_slist structs properly filled in as
974
1083
described for \fICURLOPT_QUOTE\fP. Disable this operation again by
975
1084
setting a NULL to this option.
992
1101
(This option was known as CURLOPT_FTPLISTONLY up to 7.16.4)
993
1102
.IP CURLOPT_APPEND
994
A non-zero parameter tells the library to append to the remote file instead of
995
overwrite it. This is only useful when uploading to an ftp site.
1103
A parameter set to 1 tells the library to append to the remote file instead of
1104
overwrite it. This is only useful when uploading to an FTP site.
997
1106
(This option was known as CURLOPT_FTPAPPEND up to 7.16.4)
998
1107
.IP CURLOPT_FTP_USE_EPRT
999
Pass a long. If the value is non-zero, it tells curl to use the EPRT (and
1108
Pass a long. If the value is 1, it tells curl to use the EPRT (and
1000
1109
LPRT) command when doing active FTP downloads (which is enabled by
1001
1110
\fICURLOPT_FTPPORT\fP). Using EPRT means that it will first attempt to use
1002
EPRT and then LPRT before using PORT, but if you pass FALSE (zero) to this
1111
EPRT and then LPRT before using PORT, but if you pass zero to this
1003
1112
option, it will not try using EPRT or LPRT, only plain PORT. (Added in 7.10.5)
1005
1114
If the server is an IPv6 host, this option will have no effect as of 7.12.3.
1006
1115
.IP CURLOPT_FTP_USE_EPSV
1007
Pass a long. If the value is non-zero, it tells curl to use the EPSV command
1116
Pass a long. If the value is 1, it tells curl to use the EPSV command
1008
1117
when doing passive FTP downloads (which it always does by default). Using EPSV
1009
1118
means that it will first attempt to use EPSV before using PASV, but if you
1010
pass FALSE (zero) to this option, it will not try using EPSV, only plain PASV.
1119
pass zero to this option, it will not try using EPSV, only plain PASV.
1012
1121
If the server is an IPv6 host, this option will have no effect as of 7.12.3.
1013
1122
.IP CURLOPT_FTP_CREATE_MISSING_DIRS
1014
Pass a long. If the value is non-zero, curl will attempt to create any remote
1123
Pass a long. If the value is 1, curl will attempt to create any remote
1015
1124
directory that it fails to CWD into. CWD is the command that changes working
1016
1125
directory. (Added in 7.10.7)
1019
1128
the remote directory if it can't obtain a handle to the target-location. The
1020
1129
creation will fail if a file of the same name as the directory to create
1021
1130
already exists or lack of permissions prevents creation. (Added in 7.16.3)
1132
Starting with 7.19.4, you can also set this value to 2, which will make
1133
libcurl retry the CWD command again if the subsequent MKD command fails. This
1134
is especially useful if you're doing many simultanoes connections against the
1135
same server and they all have this option enabled, as then CWD may first fail
1136
but then another connection does MKD before this connection and thus MKD fails
1137
but trying CWD works! 7.19.4 also introduced the \fICURLFTP_CREATE_DIR\fP and
1138
\fICURLFTP_CREATE_DIR_RETRY\fP enum names for these arguments.
1140
Before version 7.19.4, libcurl will simply ignore arguments set to 2 and act
1141
as if 1 was selected.
1022
1142
.IP CURLOPT_FTP_RESPONSE_TIMEOUT
1023
1143
Pass a long. Causes curl to set a timeout period (in seconds) on the amount
1024
1144
of time that the server is allowed to take in order to generate a response
1034
1154
Tumbleweed's Secure Transport FTPS server using client certificates for
1035
1155
authentication. (Added in 7.15.5)
1036
1156
.IP CURLOPT_FTP_SKIP_PASV_IP
1037
Pass a long. If set to a non-zero value, it instructs libcurl to not use the
1038
IP address the server suggests in its 227-response to libcurl's PASV command
1039
when libcurl connects the data connection. Instead libcurl will re-use the
1040
same IP address it already uses for the control connection. But it will use
1041
the port number from the 227-response. (Added in 7.14.2)
1157
Pass a long. If set to 1, it instructs libcurl to not use the IP address the
1158
server suggests in its 227-response to libcurl's PASV command when libcurl
1159
connects the data connection. Instead libcurl will re-use the same IP address
1160
it already uses for the control connection. But it will use the port number
1161
from the 227-response. (Added in 7.14.2)
1043
1163
This option has no effect if PORT, EPRT or EPSV is used instead of PASV.
1044
1164
.IP CURLOPT_USE_SSL
1045
1165
Pass a long using one of the values from below, to make libcurl use your
1046
desired level of SSL for the ftp transfer. (Added in 7.11.0)
1166
desired level of SSL for the FTP transfer. (Added in 7.11.0)
1048
1168
(This option was known as CURLOPT_FTP_SSL up to 7.16.4, and the constants
1049
1169
were known as CURLFTPSSL_*)
1116
1237
libcurl does not do a complete ASCII conversion when doing ASCII transfers
1117
1238
over FTP. This is a known limitation/flaw that nobody has rectified. libcurl
1118
simply sets the mode to ascii and performs a standard transfer.
1239
simply sets the mode to ASCII and performs a standard transfer.
1119
1240
.IP CURLOPT_PROXY_TRANSFER_MODE
1120
1241
Pass a long. If the value is set to 1 (one), it tells libcurl to set the
1121
1242
transfer mode (binary or ASCII) for FTP transfers done via an HTTP proxy, by
1122
appending ;type=a or ;type=i to the URL. Without this setting, or it being
1123
set to 0 (zero, the default), \fICURLOPT_TRANSFERTEXT\fP has no effect when
1124
doing FTP via a proxy. Beware that not all proxies support this feature.
1243
appending ;type=a or ;type=i to the URL. Without this setting, or it being set
1244
to 0 (zero, the default), \fICURLOPT_TRANSFERTEXT\fP has no effect when doing
1245
FTP via a proxy. Beware that not all proxies support this feature. (Added in
1126
1247
.IP CURLOPT_CRLF
1127
1248
Convert Unix newlines to CRLF newlines on transfers.
1128
1249
.IP CURLOPT_RANGE
1146
1267
.IP CURLOPT_CUSTOMREQUEST
1147
1268
Pass a pointer to a zero terminated string as parameter. It will be used
1148
1269
instead of GET or HEAD when doing an HTTP request, or instead of LIST or NLST
1149
when doing an ftp directory listing. This is useful for doing DELETE or other
1270
when doing a FTP directory listing. This is useful for doing DELETE or other
1150
1271
more or less obscure HTTP requests. Don't do this at will, make sure your
1151
1272
server supports the command first.
1153
Note that libcurl will still act and assume the keyword it would use if you
1154
didn't set your custom one is the one in use and it will act according to
1155
that. Thus, changing this to a HEAD when libcurl otherwise would do a GET
1156
might cause libcurl to act funny, and similar. To switch to a proper HEAD, use
1157
\fICURLOPT_NOBODY\fP, to switch to a proper POST, use \fICURLOPT_POST\fP or
1158
\fICURLOPT_POSTFIELDS\fP and so on.
1274
When you change the request method by setting \fBCURLOPT_CUSTOMREQUEST\fP to
1275
something, you don't actually change how libcurl behaves or acts in regards to
1276
the particular request method, it will only change the actual string sent in
1279
For example: if you tell libcurl to do a HEAD request, but then change the
1280
request to a "GET" with \fBCURLOPT_CUSTOMREQUEST\fP you'll still see libcurl
1281
act as if it sent a HEAD even when it does send a GET.
1283
To switch to a proper HEAD, use \fICURLOPT_NOBODY\fP, to switch to a proper
1284
POST, use \fICURLOPT_POST\fP or \fICURLOPT_POSTFIELDS\fP and so on.
1160
1286
Restore to the internal default by setting this to NULL.
1167
1293
replace or extend the set of headers sent by libcurl. Use
1168
1294
\fICURLOPT_HTTP_VERSION\fP to change HTTP version.
1169
1295
.IP CURLOPT_FILETIME
1170
Pass a long. If it is a non-zero value, libcurl will attempt to get the
1171
modification date of the remote document in this operation. This requires that
1172
the remote server sends the time or replies to a time querying command. The
1296
Pass a long. If it is 1, libcurl will attempt to get the modification date of
1297
the remote document in this operation. This requires that the remote server
1298
sends the time or replies to a time querying command. The
1173
1299
\fIcurl_easy_getinfo(3)\fP function with the \fICURLINFO_FILETIME\fP argument
1174
1300
can be used after a transfer to extract the received time (if any).
1175
1301
.IP CURLOPT_NOBODY
1176
A non-zero parameter tells the library to not include the body-part in the
1302
A parameter set to 1 tells the library to not include the body-part in the
1177
1303
output. This is only relevant for protocols that have separate header and body
1178
1304
parts. On HTTP(S) servers, this will make libcurl do a HEAD request.
1265
1395
should be below the \fICURLOPT_LOW_SPEED_LIMIT\fP for the library to consider
1266
1396
it too slow and abort.
1267
1397
.IP CURLOPT_MAX_SEND_SPEED_LARGE
1268
Pass a curl_off_t as parameter. If an upload exceeds this speed on cumulative
1269
average during the transfer, the transfer will pause to keep the average rate
1270
less than or equal to the parameter value. Defaults to unlimited
1271
speed. (Added in 7.15.5)
1398
Pass a curl_off_t as parameter. If an upload exceeds this speed (counted in
1399
bytes per second) on cumulative average during the transfer, the transfer will
1400
pause to keep the average rate less than or equal to the parameter value.
1401
Defaults to unlimited speed. (Added in 7.15.5)
1272
1402
.IP CURLOPT_MAX_RECV_SPEED_LARGE
1273
Pass a curl_off_t as parameter. If a download exceeds this speed on
1274
cumulative average during the transfer, the transfer will pause to keep the
1275
average rate less than or equal to the parameter value. Defaults to unlimited
1276
speed. (Added in 7.15.5)
1403
Pass a curl_off_t as parameter. If a download exceeds this speed (counted in
1404
bytes per second) on cumulative average during the transfer, the transfer will
1405
pause to keep the average rate less than or equal to the parameter
1406
value. Defaults to unlimited speed. (Added in 7.15.5)
1277
1407
.IP CURLOPT_MAXCONNECTS
1278
1408
Pass a long. The set number will be the persistent connection cache size. The
1279
1409
set amount will be the maximum amount of simultaneously open connections that
1280
1410
libcurl may cache in this easy handle. Default is 5, and there isn't much
1281
point in changing this value unless you are perfectly aware of how this work
1282
and changes libcurl's behaviour. This concerns connection using any of the
1411
point in changing this value unless you are perfectly aware of how this works
1412
and changes libcurl's behaviour. This concerns connections using any of the
1283
1413
protocols that support persistent connections.
1285
1415
When reaching the maximum limit, curl closes the oldest one in the cache to
1286
prevent the number of open connections to increase.
1416
prevent increasing the number of open connections.
1288
1418
If you already have performed transfers with this curl handle, setting a
1289
1419
smaller MAXCONNECTS than before may cause open connections to get closed
1292
1422
Note that if you add this easy handle to a multi handle, this setting is not
1293
being acknowledged, but you must instead use \fIcurl_multi_setopt(3)\fP and
1423
acknowledged, and you must instead use \fIcurl_multi_setopt(3)\fP and
1294
1424
the \fICURLMOPT_MAXCONNECTS\fP option.
1295
1425
.IP CURLOPT_CLOSEPOLICY
1296
1426
(Obsolete) This option does nothing.
1297
1427
.IP CURLOPT_FRESH_CONNECT
1298
Pass a long. Set to non-zero to make the next transfer use a new (fresh)
1299
connection by force. If the connection cache is full before this connection,
1300
one of the existing connections will be closed as according to the selected or
1301
default policy. This option should be used with caution and only if you
1302
understand what it does. Set this to 0 to have libcurl attempt re-using an
1303
existing connection (default behavior).
1428
Pass a long. Set to 1 to make the next transfer use a new (fresh) connection
1429
by force. If the connection cache is full before this connection, one of the
1430
existing connections will be closed as according to the selected or default
1431
policy. This option should be used with caution and only if you understand
1432
what it does. Set this to 0 to have libcurl attempt re-using an existing
1433
connection (default behavior).
1304
1434
.IP CURLOPT_FORBID_REUSE
1305
Pass a long. Set to non-zero to make the next transfer explicitly close the
1306
connection when done. Normally, libcurl keep all connections alive when done
1307
with one transfer in case there comes a succeeding one that can re-use them.
1435
Pass a long. Set to 1 to make the next transfer explicitly close the
1436
connection when done. Normally, libcurl keeps all connections alive when done
1437
with one transfer in case a succeeding one follows that can re-use them.
1308
1438
This option should be used with caution and only if you understand what it
1309
does. Set to 0 to have libcurl keep the connection open for possibly later
1439
does. Set to 0 to have libcurl keep the connection open for possible later
1310
1440
re-use (default behavior).
1311
1441
.IP CURLOPT_CONNECTTIMEOUT
1312
1442
Pass a long. It should contain the maximum time in seconds that you allow the
1410
1543
.IP CURLOPT_SSL_VERIFYPEER
1411
1544
Pass a long as parameter.
1413
This option determines whether curl verifies the authenticity of the
1414
peer's certificate. A nonzero value means curl verifies; zero means it
1415
doesn't. The default is nonzero, but before 7.10, it was zero.
1546
This option determines whether curl verifies the authenticity of the peer's
1547
certificate. A value of 1 means curl verifies; zero means it doesn't. The
1548
default is nonzero, but before 7.10, it was zero.
1417
When negotiating an SSL connection, the server sends a certificate
1418
indicating its identity. Curl verifies whether the certificate is
1419
authentic, i.e. that you can trust that the server is who the
1420
certificate says it is. This trust is based on a chain of digital
1421
signatures, rooted in certification authority (CA) certificates you
1422
supply. As of 7.10, curl installs a default bundle of CA certificates
1423
and you can specify alternate certificates with the
1550
When negotiating an SSL connection, the server sends a certificate indicating
1551
its identity. Curl verifies whether the certificate is authentic, i.e. that
1552
you can trust that the server is who the certificate says it is. This trust
1553
is based on a chain of digital signatures, rooted in certification authority
1554
(CA) certificates you supply. As of 7.10, curl installs a default bundle of
1555
CA certificates and you can specify alternate certificates with the
1424
1556
\fICURLOPT_CAINFO\fP option or the \fICURLOPT_CAPATH\fP option.
1426
When \fICURLOPT_SSL_VERIFYPEER\fP is nonzero, and the verification
1427
fails to prove that the certificate is authentic, the connection
1428
fails. When the option is zero, the connection succeeds regardless.
1558
When \fICURLOPT_SSL_VERIFYPEER\fP is nonzero, and the verification fails to
1559
prove that the certificate is authentic, the connection fails. When the
1560
option is zero, the connection succeeds regardless.
1430
Authenticating the certificate is not by itself very useful. You
1431
typically want to ensure that the server, as authentically identified
1432
by its certificate, is the server you mean to be talking to. Use
1562
Authenticating the certificate is not by itself very useful. You typically
1563
want to ensure that the server, as authentically identified by its
1564
certificate, is the server you mean to be talking to. Use
1433
1565
\fICURLOPT_SSL_VERIFYHOST\fP to control that.
1434
1566
.IP CURLOPT_CAINFO
1435
1567
Pass a char * to a zero terminated string naming a file holding one or more
1441
1573
Note that option is by default set to the system path where libcurl's cacert
1442
1574
bundle is assumed to be stored, as established at build time.
1444
When built against NSS this is the directory that the NSS certificate
1576
When built against NSS, this is the directory that the NSS certificate
1445
1577
database resides in.
1578
.IP CURLOPT_ISSUERCERT
1579
Pass a char * to a zero terminated string naming a file holding a CA
1580
certificate in PEM format. If the option is set, an additional check against
1581
the peer certificate is performed to verify the issuer is indeed the one
1582
associated with the certificate provided by the option. This additional check
1583
is useful in multi-level PKI where one needs to enforce that the peer certificate is
1584
from a specific branch of the tree.
1586
This option makes sense only when used in combination with the
1587
\fICURLOPT_SSL_VERIFYPEER\fP option. Otherwise, the result of the check is not
1588
considered as failure.
1590
A specific error code (CURLE_SSL_ISSUER_ERROR) is defined with the option,
1591
which is returned if the setup of the SSL/TLS session has failed due to a
1592
mismatch with the issuer of peer certificate (\fICURLOPT_SSL_VERIFYPEER\fP has
1593
to be set too for the check to fail). (Added in 7.19.0)
1446
1594
.IP CURLOPT_CAPATH
1447
1595
Pass a char * to a zero terminated string naming a directory holding multiple
1448
1596
CA certificates to verify the peer with. The certificate directory must be
1452
1600
indicate an accessible path. The \fICURLOPT_CAPATH\fP function apparently
1453
1601
does not work in Windows due to some limitation in openssl. This option is
1454
1602
OpenSSL-specific and does nothing if libcurl is built to use GnuTLS.
1604
Pass a char * to a zero terminated string naming a file with the concatenation
1605
of CRL (in PEM format) to use in the certificate validation that occurs during
1608
When curl is built to use NSS or GnuTLS, there is no way to influence the use
1609
of CRL passed to help in the verification process. When libcurl is built with
1610
OpenSSL support, X509_V_FLAG_CRL_CHECK and X509_V_FLAG_CRL_CHECK_ALL are both
1611
set, requiring CRL check against all the elements of the certificate chain if
1612
a CRL file is passed.
1614
This option makes sense only when used in combination with the
1615
\fICURLOPT_SSL_VERIFYPEER\fP option.
1617
A specific error code (CURLE_SSL_CRL_BADFILE) is defined with the option. It
1618
is returned when the SSL exchange fails because the CRL file cannot be loaded.
1619
Note that a failure in certificate verification due to a revocation information
1620
found in the CRL does not trigger this specific error. (Added in 7.19.0)
1621
.IP CURLOPT_CERTINFO
1622
Pass a long set to 1 to enable libcurl's certificate chain info gatherer. With
1623
this enabled, libcurl (if built with OpenSSL) will extract lots of information
1624
and data about the certificates in the certificate chain used in the SSL
1625
connection. This data is then possible to extract after a transfer using
1626
\fIcurl_easy_getinfo(3)\fP and its option \fICURLINFO_CERTINFO\fP. (Added in
1455
1628
.IP CURLOPT_RANDOM_FILE
1456
1629
Pass a char * to a zero terminated file name. The file will be used to read
1457
1630
from to seed the random engine for SSL. The more random the specified file is,
1485
1658
The default, since 7.10, is 2.
1487
The checking this option controls is of the identity that the server
1488
\fIclaims\fP. The server could be lying. To control lying, see
1489
\fICURLOPT_SSL_VERIFYPEER\fP.
1660
This option controls checking the server's claimed identity. The server could
1661
be lying. To control lying, see \fICURLOPT_SSL_VERIFYPEER\fP.
1490
1662
.IP CURLOPT_SSL_CIPHER_LIST
1491
1663
Pass a char *, pointing to a zero terminated string holding the list of
1492
1664
ciphers to use for the SSL connection. The list must be syntactically correct,
1493
it consists of one or more cipher strings separated by colons. Commas or spaces
1494
are also acceptable separators but colons are normally used, \!, \- and \+ can
1495
be used as operators.
1665
it consists of one or more cipher strings separated by colons. Commas or
1666
spaces are also acceptable separators but colons are normally used, \&!, \&-
1667
and \&+ can be used as operators.
1497
1669
For OpenSSL and GnuTLS valid examples of cipher lists include 'RC4-SHA',
1498
1670
\'SHA1+DES\', 'TLSv1' and 'DEFAULT'. The default list is normally set when you
1568
1740
Pass a long as a parameter, containing the value of the permissions that will
1569
1741
be assigned to newly created files on the remote server. The default value is
1570
1742
\fI0644\fP, but any valid value can be used. The only protocols that can use
1571
this are \fIsftp://\fP, \fIscp://\fP and \fIfile://\fP. (Added in 7.16.4)
1743
this are \fIsftp://\fP, \fIscp://\fP, and \fIfile://\fP. (Added in 7.16.4)
1572
1744
.IP CURLOPT_NEW_DIRECTORY_PERMS
1573
1745
Pass a long as a parameter, containing the value of the permissions that will
1574
1746
be assigned to newly created directories on the remote server. The default
1575
1747
value is \fI0755\fP, but any valid value can be used. The only protocols that
1576
can use this are \fIsftp://\fP, \fIscp://\fP and \fIfile://\fP.
1748
can use this are \fIsftp://\fP, \fIscp://\fP, and \fIfile://\fP.
1577
1749
(Added in 7.16.4)
1578
1750
.SH TELNET OPTIONS
1579
1751
.IP CURLOPT_TELNETOPTIONS
added
removed
docs/libcurl/curl_easy_setopt.3
