.\" -*- mode: troff; coding: utf-8 -*-
.TH "TclCurl" "n" "15 May 2026" "TclCurl 8.0.3" "TclCurl Easy Interface"
.SH NAME
.LP
TclCurl - Transfer data to and from URLs using FTP, FTPS, HTTP, HTTPS, SCP,
SFTP, TFTP, TELNET, DICT, FILE, LDAP, LDAPS, IMAP, IMAPS, POP, POP3, SMTP,
SMTPS, and GOPHER.
.SH SYNOPSIS
.LP
.EX
curl::init
curl::transfer ?options?
curl::version
curl::escape url
curl::unescape url
curl::curlConfig option
curl::versioninfo option
curl::easystrerror errorCode
.EE
.LP
.EX
curlHandle configure ?options?
curlHandle perform
curlHandle getinfo curlinfo_option
curlHandle cleanup
curlHandle reset
curlHandle duphandle
curlHandle pause
curlHandle resume
.EE
.SH DESCRIPTION
.LP
The TclCurl extension gives Tcl programmers access to the libcurl library
written by \fBDaniel Stenberg\fR. With TclCurl, you can download from URLs,
upload to them, and perform many other network transfer operations. For more
information, see \c
.UR http://curl.haxx.se
.UE \c
\&.
.SH curl::init
.LP
This procedure must be called first. It returns a \f(CRcurlHandle\fR, which you use
to invoke TclCurl procedures. Calling \f(CRinit\fR initializes TclCurl, and each
call to \f(CRinit\fR MUST have a corresponding call to \f(CRcleanup\fR when the operation
is complete.
.PP
You should perform all sequential file transfers using the same \f(CRcurlHandle\fR.
This allows TclCurl to reuse persistent connections when possible.
.PP
\fBRETURN VALUE\fR
.PP
The \f(CRcurlHandle\fR to use.
.SH curlHandle configure ?OPTIONS?
.LP
\fBconfigure\fR
.PP
is used to set the options for a transfer. Most operations in TclCurl have
default behavior, and you can change that behavior by setting the appropriate
options as documented. Each option is specified as the \fIoption\fR followed by a
parameter.
.PP
\fBNotes:\fR
.PP
The options set with this procedure apply to subsequent data transfers
performed when you invoke \f(CRperform\fR.
.PP
The options are not reset between transfers (except where noted), so if you
want subsequent transfers with different options, you must change them between
the transfers. You can optionally reset all options back to the internal
default with \fBcurlHandle reset\fR.
.PP
\f(CRcurlHandle\fR is the value returned by the \f(CRcurl::init\fR call.
.PP
\fBOPTIONS\fR
.SH BEHAVIOUR OPTIONS
.TP 3
\fB-verbose\fR
Set this option to 1 to make the library display detailed
information about its operations. This option is useful when debugging
libcurl and protocol-related problems.
.IP
You will rarely want to enable this in production, but it is often helpful
when debugging or reporting problems. Another useful debugging option is
.IP
\fB-debugproc\fR
.TP 3
\fB-header\fR
Set this option to 1 to include headers in the body output.
This is relevant only for protocols that actually send headers before the
data, such as HTTP.
.TP 3
\fB-noprogress\fR
Set this option to 1 to disable the progress meter
completely. It also prevents \fIprogressproc\fR from being called.
.TP 3
\fB-nosignal\fR
Set this option to 1 to make TclCurl avoid functions that
install signal handlers or cause signals to be sent to the process. This
option exists mainly so that multi-threaded Unix applications can still
use timeout options without risking signal-related side effects.
.IP
If this option is set and libcurl has been built with the standard name
resolver, timeouts will not occur while name resolution is in progress.
Consider building libcurl with c-ares support to enable asynchronous DNS
lookups, which allows proper timeouts for name resolution without signals.
.IP
Setting \fInosignal\fR to 1 makes libcurl stop asking the system to ignore
SIGPIPE signals. Such signals may otherwise be sent by the system when
data is written to a socket that has been closed by the peer. libcurl
tries to avoid triggering SIGPIPE, but some operating systems provide no
reliable way to prevent it, and even on those that do, some corner cases
remain. In addition, using \fIntlm_Wb\fR authentication may cause a SIGCHLD
signal to be raised.
.TP 3
\fB-wildcard\fR
Set this option to 1 to transfer multiple files that match a
file name pattern. The pattern can be specified as part of the \fB-url\fR
option, using an fnmatch-like pattern (shell pattern matching) in the last
part of the URL, that is, the file name.
.IP
By default, TclCurl uses its internal wildcard matching implementation. You
can provide your own matching function with the \fB-fnmatchproc\fR option.
.IP
At present, this feature is supported only for FTP downloads.
.IP
A brief introduction of its syntax follows:
.RS
.IP "\(bu" 3
* - ASTERISK
.RE
.IP
\f(CRftp://example.com/some/path/***.txt**\fR (for all \f(CR.txt\fR files from the root
directory)
- ? - QUESTION MARK
.IP
The question mark matches any single character.
.IP
\f(CRftp://example.com/some/path/**photo?.jpeg**\fR
- [ - BRACKET EXPRESSION
.IP
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:
.IP
\fB[a-zA-Z0-9]\fR or \fB[f-gF-G]\fR - character interval
.IP
\fB[abc]\fR - character enumeration
.IP
\fB[\(haabc]\fR or \fB[!abc]\fR - negation
.IP
\fB[[:\fR\fIname\fR\fB:]]\fR class expression. Supported classes are
\fBalnum\fR,\fBlower\fR, \fBspace\fR, \fBalpha\fR, \fBdigit\fR, \fBprint\fR, \fBupper\fR,
\fBblank\fR, \fBgraph\fR, \fBxdigit\fR.
.IP
\fB[][-!\(ha]\fR - special case - matches only \(oq-\(cq, \(oq]\(cq, \(oq[\(oq, \(oq!\(cq or \(oq\(ha\(cq. These
characters have no special purpose.
.IP
\fB[\e[\e]\e\e]\fR - escape syntax. Matches \(oq[\(oq, \(oq]\(cq or \(oq\e\(oq.
.IP
Using the rules above, a file name pattern can be constructed:
.IP
\f(CRftp://example.com/some/path/**[a-z[:upper:]\e\e\e\e].jpeg**\fR
.SH CALLBACK OPTIONS
.TP 3
\fB-writeproc\fR
Sets a Tcl procedure that TclCurl invokes whenever received data is
available to be handled. The callback procedure must have a single
argument. When the procedure is invoked, that argument refers to the
contents of a data buffer managed by libcurl.
.IP
NOTE: The amount of data passed on each invocation is not fixed. The
callback may be invoked with an empty buffer, or with a buffer containing
a large amount of data.
.TP 3
\fB-file\fR
File in which the transferred data will be saved.
.TP 3
\fB-readproc\fR
Sets a Tcl procedure that TclCurl calls whenever it needs to read data to
send to the peer. The procedure must take one parameter, which contains the
maximum number of bytes to read. It should return the actual number of
bytes read, or \f(CR0\fR if you want to stop the transfer.
.IP
If you stop the current transfer by returning \f(CR0\fR prematurely, for example
after indicating that you would upload \fIN\fR bytes but uploading fewer than
\fIN\fR, the server may appear to hang while waiting for the remaining data.
.IP
When doing TFTP uploads, you must return exactly the amount of data
requested by the callback. Otherwise, the server may treat it as the final
packet and end the transfer.
.TP 3
\fB-infile\fR
File from which the data will be transferred.
.TP 3
\fB-progressproc\fR
Name of the Tcl procedure that TclCurl invokes at regular intervals during
an operation, roughly once per second or more often, whether or not data is
currently being transferred. Unknown or unused argument values passed to
the callback are set to zero. For example, if you only download data, the
upload size remains \f(CR0\fR. The procedure must have the following prototype:
.IP
\fBproc ProgressCallback {dltotal dlnow ultotal ulnow}\fR
.IP
For this option to work, you must set the \fB-noprogress\fR option to \f(CR0\fR.
Setting this option to the empty string restores the original progress
function.
.IP
If you transfer data with the multi interface, this procedure will not be
called during periods of idleness unless you call the appropriate procedure
that performs transfers.
.IP
You can pause and resume a transfer from within this procedure using the
\fBpause\fR and \fBresume\fR commands.
.TP 3
\fB-writeheader\fR
Pass the file name to which the header part of the received data will be
written. Headers are written to this file one by one, and only complete
lines are written. This makes header parsing straightforward.
.IP
See also the \fB-headervar\fR option to get the headers into an array.
.TP 3
\fB-debugproc\fR
Name of the procedure that receives the debug data produced by the
\fB-verbose\fR option. The callback procedure must have two arguments:
.IP
\fBdebugProc {infoType data}\fR
.IP
The \fBinfoType\fR argument identifies the kind of debug information:
\f(CR0\fR text, \f(CR1\fR incoming header, \f(CR2\fR outgoing header, \f(CR3\fR incoming data,
\f(CR4\fR outgoing data, \f(CR5\fR incoming SSL data, and \f(CR6\fR outgoing SSL data.
The \fBdata\fR argument contains the corresponding data buffer.
.TP 3
\fB-chunkbgnproc\fR
Name of the procedure that is called before a file is transferred by FTP.
The callback procedure must have one argument:
.IP
\fBChunkBgnProc {remains}\fR
.IP
The \fIremains\fR argument is the number of files left to be transferred or
skipped.
.IP
This callback makes sense only when using the \fB-wildcard\fR option.
.TP 3
\fB-chunkbgnvar\fR
Name of the variable in the global scope that will contain the data for the
file about to be transferred. If you do not use this option, \f(CR::fileData\fR
is used.
.IP
The available data is: \f(CRfilename\fR, \f(CRfiletype\fR (\f(CRfile\fR, \f(CRdirectory\fR,
\f(CRsymlink\fR, \f(CRdevice block\fR, \f(CRdevice char\fR, \f(CRnamed pipe\fR, \f(CRsocket\fR, \f(CRdoor\fR,
or \f(CRerror\fR if it could not be identified), \f(CRtime\fR, \f(CRperm\fR, \f(CRuid\fR, \f(CRgid\fR,
\f(CRsize\fR, \f(CRhardlinks\fR, and \f(CRflags\fR.
.TP 3
\fB-chunkendproc\fR
Name of the procedure that is called after a file has been transferred or
skipped by FTP. The callback procedure takes no arguments:
.IP
\fBChunkEndProc {}\fR
.IP
It should return \f(CR0\fR if everything is fine and \f(CR1\fR if an error occurred.
.TP 3
\fB-fnmatchProc\fR
Name of the procedure that is called instead of the internal wildcard
matching function. The callback procedure must have two arguments:
.IP
\fBFnMatchProc {pattern string}\fR
.IP
The \fIpattern\fR argument contains the pattern to be matched. The \fIstring\fR
argument contains the candidate string. The procedure must return \f(CR0\fR if
the string matches the pattern and \f(CR1\fR otherwise.
.SH ERROR OPTIONS
.TP 3
\fB-errorbuffer\fR
Pass the name of a variable in which TclCurl may store human-readable
error messages. This can provide more information than the command return
code alone.
.TP 3
\fB-stderr\fR
Pass a file name. TclCurl uses this stream instead of \f(CRstderr\fR when
reporting errors.
.TP 3
\fB-failonerror\fR
Set this option to 1 to make the transfer fail if the returned HTTP status
code is 400 or greater. By default, TclCurl returns the page normally and
does not treat such status codes as transfer errors.
.IP
This behavior is not fail-safe, and in some cases non-successful response
codes may still pass through, especially when authentication is involved,
as with status codes 401 and 407.
.IP
Some header data may be transferred before this condition is detected. For
example, a \f(CR100-continue\fR response may be received for a POST or PUT
request before a subsequent \f(CR401\fR or \f(CR407\fR response is returned.
.SH NETWORK OPTIONS
.TP 3
\fB-url\fR
The URL to use for the transfer.
.IP
If the URL does not include a protocol part, such as \f(CRhttp://\fR or
\f(CRftp://\fR, TclCurl attempts to guess the protocol from the host name.
If the protocol specified in the URL is not supported, TclCurl returns the
\fBunsupported protocol\fR error when you call \fBperform\fR. Use
\fBcurl::versioninfo\fR for detailed information about the supported
protocols.
.IP
Starting with version 7.22.0, the fragment part of the URI is no longer
sent as part of the path, unlike earlier versions.
.IP
\fBNOTE\fR: This is the only option that must be set before \fBperform\fR is
called.
.TP 3
\fB-protocols\fR
Pass a lowercase list of protocols to limit which protocols TclCurl may
use for the transfer. This allows a TclCurl build that supports a wide
range of protocols to be restricted for specific transfers to a subset of
them.
.IP
Accepted protocols are \f(CRhttp\fR, \f(CRhttps\fR, \f(CRftp\fR, \f(CRftps\fR, \f(CRscp\fR, \f(CRsftp\fR,
\f(CRtelnet\fR, \f(CRldap\fR, \f(CRldaps\fR, \f(CRdict\fR, \f(CRfile\fR, \f(CRtftp\fR, \f(CRimap\fR, \f(CRimaps\fR,
\f(CRpop\fR, \f(CRpop3\fR, \f(CRsmtp\fR, \f(CRsmtps\fR, \f(CRgopher\fR, and \f(CRall\fR.
.TP 3
\fB-redirprotocols\fR
Pass a lowercase list of accepted protocols to limit which protocols
TclCurl may use when following a redirect with \fB-followlocation\fR
enabled. This allows specific transfers to be restricted to a subset of
protocols for redirections.
.IP
By default, TclCurl allows all protocols except \f(CRFILE\fR and \f(CRSCP\fR. This
differs from versions before 7.19.4, which would follow redirects to all
supported protocols unconditionally.
.TP 3
\fB-proxy\fR
If you need to use an HTTP proxy, set the proxy string with this option.
To specify a port number in the string, append \f(CR:[port]\fR to the end of
the host name. The proxy string may be prefixed with \f(CR[protocol]://\fR,
although such a prefix is ignored unless noted otherwise below.
.IP
When you configure an HTTP proxy, TclCurl transparently converts
operations to HTTP even if you specify an FTP URL or another protocol.
This may affect which library features are available. For example,
\fBquote\fR and similar FTP-specific features do not work unless you tunnel
through the HTTP proxy. Such tunneling is enabled with \fB-proxytunnel\fR.
.IP
TclCurl respects the environment variables \f(CRhttp_proxy\fR, \f(CRftp_proxy\fR,
\f(CRall_proxy\fR, and others of the same kind, if they are set. Using this
option overrides any such environment variables.
.IP
Setting the proxy string to \f(CR\(dq\(dq\fR explicitly disables proxy use, even if a
corresponding environment variable is set.
.IP
The proxy host string can be specified in the same way as the proxy
environment variables, including a protocol prefix such as \f(CRhttp://\fR and
embedded user name and password information.
.IP
Since 7.22.0, the proxy string may include a \f(CRprotocol://\fR prefix to
specify alternative proxy protocols. Use \f(CRsocks4://\fR, \f(CRsocks4a://\fR,
\f(CRsocks5://\fR, or \f(CRsocks5h://\fR to request a specific SOCKS version. The
last form enables SOCKS5 and asks the proxy to perform name resolution.
If no protocol is specified, and for \f(CRhttp://\fR and all other prefixes,
the proxy is treated as an HTTP proxy.
.TP 3
\fB-proxyport\fR
Use this option to set the proxy port unless it is already specified in
the proxy string passed with \fB-proxy\fR. If not specified, TclCurl uses
port \f(CR1080\fR by default.
.TP 3
\fB-proxytype\fR
Pass the proxy type. Available values are \f(CRhttp\fR, \f(CRhttp1.0\fR, \f(CRsocks4\fR,
\f(CRsocks4a\fR, \f(CRsocks5\fR, and \f(CRsocks5h\fR. The default is \f(CRhttp\fR.
.IP
If you set it to \fIhttp1.0\fR, it will only affect how libcurl speaks to a
proxy when CONNECT is used. The HTTP version used for ordinary HTTP
requests is instead controlled by \fIhttpversion\fR.
.TP 3
\fB-noproxy\fR
Pass a string containing a comma-separated list of hosts that should not
use a proxy, if one is specified. The only wildcard is a single \f(CR*\fR
character, which matches all hosts and effectively disables the proxy.
Each name in this list is matched either as a domain containing the host
name, or as the host name itself. For example, \f(CRlocal.com\fR matches
\f(CRlocal.com\fR, \f(CRlocal.com:80\fR, and \f(CRwww.local.com\fR, but not
\f(CRwww.notlocal.com\fR.
.TP 3
\fB-httpproxytunnel\fR
Set this option to 1 to tunnel all non-HTTP operations through the given
HTTP proxy. Using a proxy and tunneling through a proxy are different
behaviors. This option should be enabled only when that distinction is
required.
.TP 3
\fB-socks5gssapiservice\fR
Pass the service name. The default service name for a SOCKS5 server is
\f(CRrcmd/server-fqdn\fR. This option allows you to change it.
.TP 3
\fB-socks5gssapinec\fR
Pass \f(CR1\fR to enable this option or \f(CR0\fR to disable it. As part of the
GSSAPI negotiation, a protection mode is negotiated. RFC 1961 specifies in
sections 4.3 and 4.4 that this exchange should be protected, but the NEC
reference implementation does not do so. When enabled, this option allows
the protection mode negotiation to be exchanged unprotected.
.TP 3
\fB-interface\fR
Pass the interface name to use as the outgoing network interface. The name
may be an interface name, an IP address, or a host name.
.TP 3
\fB-localport\fR
Sets the local port number of the socket used for the connection. This can
be used together with \fB-interface\fR, and it is recommended to use
\fB-localportrange\fR as well when this option is set. Valid port numbers
are \f(CR1\fR through \f(CR65535\fR.
.TP 3
\fB-localportrange\fR
Number of attempts TclCurl should make to find a working local port
number. It starts with the port specified by \fB-localport\fR and increments
it by one for each retry. Setting this value to \f(CR1\fR or less makes TclCurl
try only one port number. Because port numbers are a limited resource and
may already be in use, setting this value too low may cause unnecessary
connection setup failures.
.TP 3
\fB-dnscachetimeout\fR
Pass the timeout in seconds. Name resolution results are kept in memory
for this number of seconds. Set this option to \f(CR0\fR to disable caching
completely, or to \f(CR-1\fR to keep cached entries indefinitely. By default,
TclCurl caches this information for \f(CR60\fR seconds.
.IP
The name resolution functions in various libc implementations do not
re-read name server information unless explicitly told to do so, for
example by calling \fIres_init(3)\fR. As a result, TclCurl may continue to use
older server information even after DHCP has updated it, which may appear
to be a DNS cache issue.
.TP 3
\fB-dnsuseglobalcache\fR
If this option is set to \f(CR1\fR, TclCurl uses a global DNS cache that
survives the creation and deletion of curl handles. This is not
thread-safe because it relies on a global variable. \fIThis option was
deprecated in libcurl v7.11.1 and is disabled by default in the TclCurl
build. See \f(CIREADME.md\fI for instructions on how to re-enable it.\fR
.IP
\fBWARNING:\fR This option is obsolete. Use the share interface instead. See
\fItclcurl_share\fR.
.TP 3
\fB-buffersize\fR
Pass the preferred size for the TclCurl receive buffer. A smaller buffer
may cause the write callback to be invoked more often with smaller chunks.
This value is treated as a request, not as a guarantee.
.TP 3
\fB-port\fR
Pass the remote port number to connect to instead of the port specified
in the URL or the default port for the protocol in use.
.TP 3
\fB-tcpnodelay\fR
Pass a number to specify whether the \f(CRTCP_NODELAY\fR option should be set or
cleared (\f(CR1\fR = set, \f(CR0\fR = clear). This option is cleared by default. It
has no effect after the connection has been established.
.IP
Setting this option will disable TCP\(cqs Nagle algorithm. The purpose of this
algorithm is to try to minimize the number of small packets on the network
(where \(lqsmall packets\(rq means TCP segments less than the Maximum Segment
Size (MSS) for the network).
.IP
Maximizing the amount of data sent per TCP segment is good because it
amortizes the overhead of the send. However, in some cases (most notably
telnet or rlogin) small segments may need to be sent without delay. This is
less efficient than sending larger amounts of data at a time, and can
contribute to congestion on the network if overdone.
.TP 3
\fB-addressscope\fR
Pass a number specifying the \f(CRscope_id\fR value to use when connecting to
IPv6 link-local or site-local addresses.
.SH NAMES AND PASSWORDS OPTIONS
.TP 3
\fB-netrc\fR
Set this option to make TclCurl scan your \fB\(ti/.netrc\fR file for the user
name and password of the remote site you are about to access. TclCurl does
not verify that the file has the correct properties set, as the standard
Unix \f(CRftp\fR client does. Only machine name, user name, and password are
taken into account; \f(CRinit\fR macros and similar entries are not supported.
.IP
Accepted values:
.RS
.TP 3
\f(CRoptional\fR
Use of \fB\(ti/.netrc\fR is optional, and information in the URL takes
precedence. The file is searched using the host and user name, to find
the password only, or using the host name alone, to find the first
user name and password for that machine, depending on which
information is not specified in the URL.
.RE
.IP
Undefined values for this option have the same effect.
.RS
.TP 3
\f(CRignored\fR
TclCurl ignores the file and uses only the information in the URL.
This is the default.
.TP 3
\f(CRrequired\fR
TclCurl requires use of the file, ignores the information in the URL,
and searches the file using the host name only.
.RE
.TP 3
\fB-netrcfile\fR
Pass a string containing the full path name of the file to use as the
\f(CR.netrc\fR file. For this option to work, you must set \fB-netrc\fR to
\fBrequired\fR. If this option is omitted and \fB-netrc\fR is set, TclCurl
attempts to find a \f(CR.netrc\fR file in the current user\(cqs home directory.
.TP 3
\fB-userpwd\fR
Pass a string in the form \f(CR[username]:[password]\fR to use for the
connection. Use \fB-httpauth\fR to select the authentication method.
.IP
When using NTLM, you can specify a domain by prepending it to the user
name and separating the domain and name with a forward slash (\f(CR/\fR) or
backward slash (\f(CR\e\e\fR), for example \f(CRdomain/user:password\fR or
\f(CRdomain\e\euser:password\fR. Some HTTP servers on Windows also support this
form for Basic authentication.
.IP
When using HTTP and \fB-followlocation\fR, TclCurl might perform several
requests to possibly different hosts. TclCurl will only send this user and
password information to hosts using the initial host name (unless
\fB-unrestrictedauth\fR is set), so if TclCurl follows locations to other
hosts it will not send the user and password to those. This is enforced to
prevent accidental information leakage.
.TP 3
\fB-proxyuserpwd\fR
Pass a string in the form \f(CR[username]:[password]\fR to use for the
connection to the HTTP proxy.
.TP 3
\fB-username\fR
Pass a string containing the user name to use for the transfer. It sets
the user name used in protocol authentication. This option should not be
used together with the older \fB-userpwd\fR option.
.IP
To specify the password to use together with the user name, use the
\fB-password\fR option.
.TP 3
\fB-password\fR
Pass a string containing the password to use for the transfer.
.IP
This option should be used together with \fB-username\fR.
.TP 3
\fB-proxyusername\fR
Pass a string containing the user name to use for the transfer while
connecting to the proxy.
.IP
This option is used in the same way as \fB-proxyuserpwd\fR, except that it
allows the user name to contain a colon, as in
\f(CRsip:user@example.com\fR.
.IP
\fB-proxyusername\fR is an alternative way to set the user name while
connecting to the proxy. It should not be used together with
\fB-proxyuserpwd\fR.
.TP 3
\fB-proxypassword\fR
Pass a string containing the password to use for the transfer while
connecting to the proxy. This option is intended to be used together with
\fB-proxyusername\fR.
.TP 3
\fB-httpauth\fR
Set this option to the authentication method to use. Accepted values are:
.RS
.TP 3
\f(CRbasic\fR
HTTP Basic authentication. This is the default choice and the only
method in widespread use that is supported almost everywhere. It sends
the user name and password over the network in plain text.
.TP 3
\f(CRdigest\fR
HTTP Digest authentication. Over public networks, this is generally
more secure than Basic authentication.
.TP 3
\f(CRdigestie\fR
HTTP Digest authentication with an Internet Explorer-specific variant.
TclCurl uses a compatibility behavior known to have been used by
Internet Explorer before version 7 and still required by some servers.
.TP 3
\f(CRgssnegotiate\fR
HTTP GSS-Negotiate authentication. This method, also known simply as
\f(CRNegotiate\fR, was designed by Microsoft and is used in Microsoft web
applications. It is primarily intended to support Kerberos 5
authentication, but it may also be used with other authentication
methods.
.TP 3
\f(CRntlm\fR
HTTP NTLM authentication. This is a proprietary protocol developed and
used by Microsoft. It uses a challenge-response mechanism and hashing,
similar to Digest, to avoid sending the password in clear text.
.TP 3
\f(CRntlmwb\fR
NTLM delegated to the winbind helper. Authentication is performed by a
separate binary application that is executed when needed. The name of
that application is specified when libcurl is built, but it is
typically \f(CR/usr/bin/ntlm_auth\fR.
.RE
.IP
Note that libcurl will fork when necessary to run the winbind application
and kill it when complete, calling waitpid() to await its exit when done.
On POSIX operating systems, killing the process will cause a SIGCHLD signal
to be raised (regardless of whether \fB-nosignal\fR is set). This behavior is
subject to change in future versions of libcurl.
.RS
.TP 3
\f(CRany\fR
TclCurl automatically selects the method it considers the most secure.
.TP 3
\f(CRanysafe\fR
TclCurl may use any method except Basic and automatically selects the
one it considers the most secure.
.RE
.TP 3
\fB-tlsauthtype\fR
Selects the authentication method to use for TLS authentication.
.IP
Accepted values:
.RS
.TP 3
\f(CRtlsauthsrp\fR
Uses TLS-SRP authentication. Secure Remote Password authentication for
TLS is defined in RFC 5054 and provides mutual authentication if both
sides share a secret. To use this value, you must also set
\fB-tlsauthusername\fR and \fB-tlsauthpassword\fR.
.RE
.IP
libcurl must be built with GnuTLS or with OpenSSL support for TLS-SRP for
this to work.
.TP 3
\fB-tlsauthusername\fR
Pass a string containing the user name to use for the TLS authentication
method specified with \fB-tlsauthtype\fR. This option requires
\fB-tlsauthpassword\fR to be set as well.
.TP 3
\fB-tlsauthpassword\fR
Pass a string containing the password to use for the TLS authentication
method specified with \fB-tlsauthtype\fR. This option requires
\fB-tlsauthusername\fR to be set as well.
.TP 3
\fB-proxyauth\fR
Use this option to tell TclCurl which authentication method to use for
proxy authentication. For some methods, this causes an extra network
round trip. Set the actual user name and password with
\fB-proxyuserpwd\fR.
.IP
The methods are those listed above for the \fBhttpauth\fR option. As of this
writing, only Basic and NTLM work.
.SH HTTP OPTIONS
.TP 3
\fB-autoreferer\fR
Set this option to \f(CR1\fR to enable automatic updates of the \f(CRReferer:\fR
header when TclCurl follows a \f(CRLocation:\fR redirect.
.TP 3
\fB-encoding\fR
Sets the contents of the \f(CRAccept-Encoding:\fR header sent in an HTTP
request, and enables decoding of a response when a \f(CRContent-Encoding:\fR
header is received.
.IP
Accepted values:
.RS
.TP 3
\f(CRidentity\fR
Requests no encoding.
.TP 3
\f(CRdeflate\fR
Requests compression using the zlib algorithm.
.TP 3
\f(CRgzip\fR
Requests gzip compression.
.TP 3
\f(CRall\fR
Sends an \f(CRAccept-Encoding:\fR header containing all supported
encodings.
.RE
.IP
This is a request, not a requirement; the server may or may not honor it.
This option must be set or any unsolicited encoding used by the server is
ignored. See \f(CRlib/README.encoding\fR in the libcurl documentation for
details.
.TP 3
\fB-transferencoding\fR
Adds a request for compressed \f(CRTransfer-Encoding\fR in the outgoing HTTP
request. If the server supports this and chooses to use it, the response
may use a compressed \f(CRTransfer-Encoding\fR, which TclCurl then decompresses
automatically when receiving the data.
.IP
\f(CRTransfer-Encoding\fR differs from the \f(CRContent-Encoding\fR requested with
\fB-encoding\fR in that \f(CRTransfer-Encoding\fR applies strictly to the
transfer and therefore must be decoded before the data reaches the client.
Traditionally, \f(CRTransfer-Encoding\fR has been used less widely and is less
consistently supported by HTTP clients and servers.
.TP 3
\fB-followlocation\fR
Set this option to \f(CR1\fR to make TclCurl follow any
.IP
\f(CRLocation:\fR header
.IP
sent by the server as part of an HTTP response.
.IP
TclCurl resends the request to the new location and continues to follow
further \f(CRLocation:\fR headers until no more are returned. Use
\fB-maxredirs\fR to limit the number of redirects TclCurl follows.
.IP
Since 7.19.4, TclCurl can also restrict which protocols it follows
automatically. The accepted protocols are set with \fB-redirprotocols\fR.
By default, the \f(CRFILE\fR protocol is excluded.
.TP 3
\fB-unrestrictedauth\fR
Set this option to \f(CR1\fR to allow TclCurl to continue sending authentication
credentials when following redirects, even if the host name changes. This
option is meaningful only when \fB-followlocation\fR is enabled.
.TP 3
\fB-maxredirs\fR
Sets the redirection limit. After that many redirects have been followed,
the next redirect causes an error. This option is meaningful only when
\fB-followlocation\fR is enabled. Set the limit to \f(CR0\fR to refuse all
redirects. Set it to \f(CR-1\fR for an unlimited number of redirects, which is
the default.
.TP 3
-postredir
Controls how TclCurl acts on redirects after POST requests that receive a
\f(CR301\fR, \f(CR302\fR, or \f(CR303\fR response. Accepted values are \f(CR301\fR, \f(CR302\fR, \f(CR303\fR,
and \f(CRall\fR. The values \f(CR301\fR, \f(CR302\fR, and \f(CR303\fR make TclCurl preserve the
POST request method for the corresponding redirect status code. The value
\f(CRall\fR enables all three behaviors.
.IP
The non-RFC behavior is common in web browsers, so TclCurl performs this
conversion by default to maintain consistency. However, a server may
require a POST to remain a POST after such a redirection.
.IP
This option is meaningful only when \fB-followlocation\fR is enabled.
.IP
The legacy alias \fB-post301\fR is accepted for compatibility and uses the
same values.
.TP 3
\fB-put\fR
Set this option to \f(CR1\fR to make TclCurl upload a file using HTTP \f(CRPUT\fR. The
file to upload must be specified with \fB-infile\fR and \fB-infilesize\fR.
.IP
This option is deprecated as of version 0.12.1. Use
\fB-upload\fR.
.IP
This option does not limit how much data TclCurl will actually send, as
that is controlled entirely by what the read callback returns.
.TP 3
\fB-post\fR
Set this option to \f(CR1\fR to make TclCurl perform a regular HTTP \f(CRPOST\fR
request using the \f(CRapplication/x-www-form-urlencoded\fR format commonly used
by HTML forms. Use \fB-postfields\fR to specify the data to post and
\fB-postfieldsize\fR to specify its size.
.IP
Use the \fB-postfields\fR option to specify what data to post and
\fB-postfieldsize\fR to set the data size. Optionally, you can also provide
\f(CRPOST\fR data using \fB-readproc\fR.
.IP
You can override the default \f(CRPOST\fR \f(CRContent-Type:\fR header by setting your own
with \fB-httpheader\fR.
.IP
Using \f(CRPOST\fR with HTTP 1.1 implies the use of an \f(CRExpect: 100-continue\fR
header. You can disable this header with \fB-httpheader\fR as usual.
.IP
If you use \f(CRPOST\fR with an HTTP 1.1 server, you can send data without
knowing the size in advance by using chunked encoding. Enable this by
adding a header such as \f(CRTransfer-Encoding: chunked\fR with \fB-httpheader\fR.
With HTTP 1.0, or without chunked transfer encoding, you must specify the
size in the request.
.IP
Setting \fB-post\fR to \f(CR1\fR also sets \fB-nobody\fR to \f(CR0\fR.
.IP
\fBNOTE:\fR If you have issued a \f(CRPOST\fR request and later want to make a
\f(CRHEAD\fR or \f(CRGET\fR request instead, you must explicitly select the new
request type with \fB-nobody\fR, \fB-httpget\fR, or a similar option.
.TP 3
\fB-postfields\fR
Pass a string containing the complete data to send in an HTTP \f(CRPOST\fR
request. You must ensure that the data is formatted exactly as you want
the server to receive it. TclCurl does not convert or encode it for you.
Most web servers assume this data is URL-encoded.
.IP
This is the normal \f(CRapplication/x-www-form-urlencoded\fR form, which is the most
commonly used one by HTML forms.
.IP
If you want to do a zero-byte POST, you need to set \fB-postfieldsize\fR
explicitly to zero, because setting \fB-postfields\fR to \f(CRNULL\fR or \f(CR\(dq\(dq\fR
effectively disables sending the specified string. TclCurl then assumes
that the \f(CRPOST\fR data is supplied through the read callback.
.IP
Using \f(CRPOST\fR with HTTP 1.1 implies the use of an \f(CRExpect: 100-continue\fR
header. You can disable this header with \fB-httpheader\fR as usual.
.IP
\fBNOTE:\fR To make \f(CRmultipart/form-data\fR posts, see \fB-httppost\fR.
.TP 3
\fB-postfieldsize\fR
Use this option to post data without letting TclCurl call \f(CRstrlen()\fR to
determine the data size. This is also required if you want to post fully
binary data, which would otherwise likely fail. If this size is set to
zero, the library uses \f(CRstrlen()\fR to determine the data size.
.TP 3
\fB-httppost\fR
Makes TclCurl perform an HTTP \f(CRmultipart/form-data\fR \f(CRPOST\fR request. The
data to send is described through a Tcl list.
.IP
\fBThis is the only case where the data is reset after a transfer.\fR
.IP
Each part consists of at least a \fBNAME\fR and a \fBCONTENTS\fR part. If the
part is used for file upload, it may also contain \fBCONTENT-TYPE\fR and
\fBFILENAME\fR information.
.IP
The list must contain a \fB\(oqname\(cq\fR tag followed by the section name. The
section value can then be described with \fB\(oqvalue\(cq\fR, followed by a string
containing the data to post, \fB\(oqfile\(cq\fR, followed by the name of the file
to post, or \fB\(oqcontenttype\(cq\fR, followed by the content type
(\f(CRtext/plain\fR, \f(CRimage/jpg\fR, and so on). You can also supply an alternate
file name with \fB\(oqfilename\(cq\fR. This is useful if the server checks whether
the provided file name is valid, or if you want to include the full path
of the file being posted. You can also post the contents of a variable as
if it were a file by using \fB\(oqbufferName\(cq\fR and \fB\(oqbuffer\(cq\fR, or use
\fB\(oqfilecontent\(cq\fR followed by a file name to read that file and use its
contents as data.
.IP
To specify additional headers for a form section, use \fB\(oqcontentheader\(cq\fR
followed by a list of headers.
.IP
See \f(CRhttpPost.tcl\fR and \f(CRhttpBufferPost.tcl\fR for examples.
.IP
Return values:
.RS
.TP 3
\f(CR1\fR
If the memory allocation fails.
.TP 3
\f(CR2\fR
If one option is given twice for one form.
.TP 3
\f(CR3\fR
If an empty string was given.
.TP 3
\f(CR4\fR
If an unknown option was used.
.TP 3
\f(CR5\fR
If some form information is incomplete or invalid.
.TP 3
\f(CR6\fR
If an illegal option is used in an array.
.TP 3
\f(CR7\fR
If TclCurl has no HTTP support.
.RE
.TP 3
\fB-referer\fR
Pass a string to set the \f(CRReferer:\fR header in the HTTP request sent to the
remote server.
.IP
The \f(CRReferer:\fR header identifies the resource from which the target URI
was obtained. Servers may use it for logging, analytics, backlink
generation, caching decisions, or request-flow checks.
.IP
This option is useful when a scripted client must reproduce the request
context normally sent by a web browser, or when a server expects a
specific referring URI.
.IP
The header value should normally be a URI identifying the referring
resource. Fragments and userinfo components are not part of a valid
\f(CRReferer:\fR field value.
.IP
The field name \f(CRReferer\fR is a historical misspelling of \f(CRreferrer\fR, but
the misspelled form is the standardized HTTP header name.
.IP
Because this header may reveal navigation context or sensitive URI data,
it should be set with care. It should not be relied upon as a secure means
of authentication or access control.
.IP
You can also set this header through \fB-httpheader\fR.
.TP 3
\fB-useragent\fR
Pass a string to set the \f(CRUser-Agent:\fR header in the HTTP request sent to
the remote server. You can also set custom headers with \fB-httpheader\fR.
.TP 3
\fB-httpheader\fR
Pass a list of HTTP headers to send in the request. If you add a header
that TclCurl would otherwise generate internally, your header is used
instead. If you add a header with no value, such as \f(CRAccept:\fR, the
internal header is disabled. This option can therefore be used to add,
replace, or remove internal headers.
.IP
This option is useful when the request must include headers not exposed by
dedicated TclCurl options, or when you need exact control over the final
HTTP request. Common uses include setting custom authentication-related
headers, API-specific headers, cache-control directives, or overriding
headers such as \f(CRContent-Type:\fR or \f(CRAccept:\fR.
.IP
The headers in the list must not be CRLF-terminated, because TclCurl adds
CRLF after each header item. If you include CRLF yourself, the server will
likely ignore part of the headers you specified.
.IP
The first line of a request, containing the method, usually \f(CRGET\fR or
\f(CRPOST\fR, is not a header and cannot be replaced with this option. Only the
lines following the request line are headers. Adding the method line to
this list causes an invalid header to be sent.
.IP
\fBNOTE:\fR The most commonly replaced headers have dedicated shortcut
options: \fB-cookie\fR, \fB-useragent\fR, and \fB-referer\fR.
.TP 3
\fB-http200aliases\fR
Pass a list of aliases to be treated as valid HTTP 200 responses. Some
servers return a custom response line. For example, IceCast servers may
return \f(CRICY 200 OK\fR. If you include such a string in the list, it is
treated as a valid HTTP status line such as \f(CRHTTP/1.0 200 OK\fR.
.IP
\fBNOTE:\fR The alias itself is not parsed for a version string. Before
version 7.16.3, TclCurl used the value set by \fB-httpversion\fR, but since
7.16.3 the protocol is assumed to match HTTP 1.0 when an alias matches.
.TP 3
\fB-cookie\fR
Pass a string to set a cookie in the HTTP request. The string should use
the format \f(CR[NAME]=[CONTENTS];\fR, where \f(CRNAME\fR is the cookie name and
\f(CRCONTENTS\fR is the cookie value.
.IP
If you need to set multiple cookies, you must set them all in a single
option value by concatenating them into one string, for example
\f(CRname1=content1; name2=content2;\fR.
.IP
This option sets the cookie header explicitly in the outgoing request(s).
If multiple requests are performed because of authentication, redirects,
or similar causes, they all receive this cookie header.
.IP
If this option is used multiple times, only the last value is kept.
.TP 3
\fB-cookiefile\fR
Pass the name of a file containing cookie data. The cookie data may be in
Netscape cookie file format or in regular HTTP-style headers written to a
file.
.IP
If the file is empty or does not exist, this option still enables cookies
for the handle, causing TclCurl to parse received cookies and use matching
cookies in later requests.
.IP
If you use this option multiple times, each use adds another file to read.
.TP 3
\fB-cookiejar\fR
Pass a file name to which TclCurl writes all internally known cookies when
\fBcurlHandle cleanup\fR is called. If no cookies are known, no file is
created. Specify \f(CR-\fR to write the cookies to standard output.
.IP
Using this option also enables cookies for the session, so matching
cookies are sent on later requests, including those caused by redirects.
.IP
TclCurl cannot report an error if writing the cookie jar fails. If
\fB-verbose\fR is enabled, a warning is displayed, but that is the only
visible feedback in this case.
.TP 3
\fB-cookiesession\fR
Set this option to \f(CR1\fR to mark the current run as a new cookie session.
This makes TclCurl ignore session cookies loaded from a previous session.
By default, TclCurl stores and loads all cookies, including session
cookies. Session cookies are cookies without an expiry date and are meant
to exist only for the current session.
.TP 3
\fB-cookielist\fR
Pass a string containing a cookie. The cookie may be in Netscape/Mozilla
format or in regular HTTP-style header form, such as \f(CRSet-Cookie: ...\fR.
If the cookie engine is not enabled, it is enabled automatically.
.IP
Special values are \f(CRALL\fR, which erases all known cookies, and \f(CRFLUSH\fR,
which writes all known cookies to the file specified by \fB-cookiejar\fR.
.TP 3
\fB-httpget\fR
Set this option to \f(CR1\fR to force the HTTP request method back to \f(CRGET\fR.
This is useful if \f(CRPOST\fR, \f(CRPUT\fR, or a custom request has previously been
used with the same handle.
.IP
Setting \fB-httpget\fR to \f(CR1\fR also sets \fB-nobody\fR to \f(CR0\fR.
.TP 3
\fB-httpversion\fR
Selects the HTTP version to use. This option should be used only when it
is necessary to override the default behavior because of server-side
requirements.
.IP
Accepted values:
.RS
.TP 3
\f(CRnone\fR
Lets TclCurl use the HTTP version it considers appropriate.
.TP 3
\f(CR1.0\fR
Enforce HTTP 1.0 requests.
.TP 3
\f(CR1.1\fR
Enforce HTTP 1.1 requests.
.TP 3
\f(CR2.0\fR
Enforce HTTP version 2 requests.
.TP 3
\f(CR2TLS\fR
Enforce version 2 requests for HTTPS, version 1.1 for HTTP.
.TP 3
\f(CR2_PRIOR_KNOWLEDGE\fR
Enforce HTTP 2 requests without performing an HTTP/1.1 \f(CRUpgrade\fR
first.
.RE
.TP 3
\fB-ignorecontentlength\fR
Ignores the \f(CRContent-Length\fR header. This is useful for Apache 1.x and
similar servers, which may report an incorrect content length for files
larger than 2 gigabytes. If this option is used, TclCurl cannot report
progress accurately and stops the download only when the server closes the
connection.
.TP 3
\fB-httpcontentdecoding\fR
Set this option to \f(CR0\fR to disable content decoding, or to \f(CR1\fR to enable
it. TclCurl does not enable content decoding by default; for that, you
must also use \fB-encoding\fR.
.TP 3
\fB-httptransferencoding\fR
Set this option to \f(CR0\fR to disable transfer decoding, or to \f(CR1\fR to enable
it. The default is \f(CR1\fR. TclCurl performs chunked transfer decoding by
default unless this option is disabled.
.SH SMTP OPTIONS
.TP 3
\fB-mailfrom\fR
Pass a string specifying the sender address to use in the SMTP envelope.
.IP
This option controls the envelope sender used at the SMTP protocol level.
It does not set or modify the \f(CRFrom:\fR header field in the message body.
.TP 3
\fB-mailrcpt\fR
Pass a list of recipient addresses to use in the SMTP envelope.
.IP
This option controls the envelope recipients used at the SMTP protocol
level. It does not set or modify message header fields such as \f(CRTo:\fR,
\f(CRCc:\fR, or \f(CRBcc:\fR.
.IP
In SMTP, recipients are specified with angle brackets (\f(CR<>\fR). If a
recipient value does not begin with an angle bracket, TclCurl assumes that
it is a plain email address and adds the angle brackets automatically.
.SH TFTP OPTION
.TP 3
\fB-tftpblksize\fR
Specifies the block size to use for TFTP data transmission. According to
RFC 2348, valid values range from \f(CR8\fR to \f(CR65464\fR bytes. If this option is
not specified, the default block size is \f(CR512\fR bytes.
.IP
The requested block size is used only if the remote server supports it. If
the server does not return an option acknowledgment, or if it returns an
acknowledgment without a block size value, the default of \f(CR512\fR bytes is
used.
.SH FTP OPTIONS
.TP 3
\fB-ftpport\fR
Pass a string identifying the address to use for the FTP \f(CRPORT\fR
instruction. The \f(CRPORT\fR instruction tells the remote server to connect to
the specified client address. The string may be a plain IP address, a host
name, a network interface name on Unix, or simply \f(CR-\fR to let the library
use the system\(cqs default IP address. By default, FTP transfers are
passive, so \f(CRPORT\fR is not used.
.IP
The address can be followed by \f(CR:\fR and a port number, optionally followed
by \f(CR-\fR and a port range. If the port specified is \f(CR0\fR, the operating
system chooses a free port. If a range is provided and no port in that
range is available, libcurl reports \f(CRCURLE_FTP_PORT_FAILED\fR for the
handle. Invalid port or port-range settings are ignored. IPv6 addresses
followed by a port or port range must be enclosed in brackets. IPv6
addresses without a port or port range may also be enclosed in brackets.
.IP
Examples:
.IP
\f(CReth0:0\fR   \f(CR192.168.1.2:32000-33000\fR   \f(CRcurl.se:32123\fR
\f(CR[::1]:1234-4567\fR
.IP
To disable \f(CRPORT\fR and return to passive mode, set this option to the empty
string.
.TP 3
\fB-quote\fR
Pass a list of FTP or SFTP commands to send to the server before the FTP
transfer request. These commands are sent before any other FTP commands,
including \f(CRCWD\fR. If you do not want to transfer any files, set
\fB-nobody\fR to \f(CR1\fR and \fB-header\fR to \f(CR0\fR.
.IP
Prefix a command with an asterisk (\f(CR*\fR) to make TclCurl continue even if
that command fails. By default, a failure stops the transfer.
.IP
To disable this option, set it to the empty string.
.IP
The commands must be raw FTP commands. For example, to create a directory
you must send \f(CRmkd Test\fR, not \f(CRmkdir Test\fR.
.IP
Valid SFTP commands are \f(CRchgrp\fR, \f(CRchmod\fR, \f(CRchown\fR, \f(CRln\fR, \f(CRmkdir\fR, \f(CRpwd\fR,
\f(CRrename\fR, \f(CRrm\fR, \f(CRrmdir\fR, and \f(CRsymlink\fR.
.TP 3
\fB-postquote\fR
Pass a list of FTP commands to send to the server after the FTP transfer
request. If you do not want to transfer any files, set \fB-nobody\fR to \f(CR1\fR
and \fB-header\fR to \f(CR0\fR.
.TP 3
\fB-prequote\fR
Pass a list of FTP or SFTP commands to send to the server after the
transfer type has been set.
.TP 3
\fB-dirlistonly\fR
Set this option to \f(CR1\fR to list only file names in a directory instead of
requesting a full directory listing with file sizes, dates, and similar
information. This option works with both FTP and SFTP URLs.
.IP
For FTP, this causes an \f(CRNLST\fR command to be sent. Some FTP servers return
only files in response to \f(CRNLST\fR, and may omit subdirectories and symbolic
links.
.IP
Setting this option to \f(CR1\fR also implies a directory listing even if the
URL does not end with a slash, which would otherwise be required.
.IP
Do not use this option together with \fB-wildcardmatch\fR, as it effectively
disables that feature.
.TP 3
\fB-append\fR
Set this option to \f(CR1\fR to append to the remote file instead of
overwriting it. This is useful only when uploading to an FTP site.
.TP 3
\fB-ftpuseeprt\fR
Set this option to \f(CR1\fR to make TclCurl use the \f(CREPRT\fR and \f(CRLPRT\fR commands
for active FTP transfers, which are enabled with \fB-ftpport\fR. When this
option is enabled, TclCurl first attempts \f(CREPRT\fR, then \f(CRLPRT\fR, and only
then falls back to \f(CRPORT\fR. If this option is set to \f(CR0\fR, only \f(CRPORT\fR is
used.
.TP 3
\fB-ftpuseepsv\fR
Set this option to \f(CR1\fR to make TclCurl use the \f(CREPSV\fR command for passive
FTP transfers. This is the default behavior. When enabled, TclCurl first
attempts \f(CREPSV\fR before using \f(CRPASV\fR. If this option is set to \f(CR0\fR, TclCurl
uses only \f(CRPASV\fR.
.TP 3
\fB-ftpusepret\fR
Set this option to \f(CR1\fR to make TclCurl send a \f(CRPRET\fR command before \f(CRPASV\fR
or \f(CREPSV\fR. Some FTP servers, especially \f(CRdrftpd\fR, require this non-standard
command for directory listings and uploads or downloads in passive mode.
This option has no effect for active FTP transfers.
.TP 3
\fB-ftpcreatemissingdirs\fR
Controls whether TclCurl should attempt to create a remote directory when
the transfer requires that directory to exist, but a \f(CRCWD\fR command shows
that it does not yet exist or cannot yet be entered.
.IP
This setting also applies to SFTP connections. TclCurl attempts to create
the remote directory if it cannot obtain a handle to the target location.
Creation fails if a file with the same name already exists, or if
permissions do not allow directory creation.
.IP
Accepted values:
.RS
.TP 3
\f(CR1\fR
After a failed \f(CRCWD\fR, TclCurl attempts to create the missing remote
directory and then continues with the transfer.
.TP 3
\f(CR2\fR
After a failed \f(CRCWD\fR, TclCurl attempts to create the missing remote
directory. If the subsequent \f(CRMKD\fR command fails, TclCurl retries the
\f(CRCWD\fR command before giving up. This is useful when multiple
simultaneous connections target the same server and another connection
may have created the directory in the meantime.
.RE
.TP 3
\fB-ftpresponsetimeout\fR
Sets a timeout, in seconds, for how long the server may take to return a
response to an FTP command before the session is considered hung. While
TclCurl is waiting for such a response, this value overrides \fB-timeout\fR.
If both options are used, \fB-ftpresponsetimeout\fR should normally be set
to a value smaller than \fB-timeout\fR.
.TP 3
\fB-ftpalternativetouser\fR
Pass a string to use for authentication if the usual FTP \f(CRUSER user\fR and
\f(CRPASS password\fR negotiation fails. This is known to be required in some
cases when connecting to Tumbleweed Secure Transport FTPS servers that use
client-certificate authentication.
.TP 3
\fB-ftpskippasvip\fR
Set this option to \f(CR1\fR to make TclCurl ignore the IP address suggested by
the server in its \f(CR227\fR response to TclCurl\(cqs \f(CRPASV\fR command when opening
the data connection. TclCurl instead reuses the same IP address already in
use for the control connection, while still using the port number from the
\f(CR227\fR response.
.IP
This option has no effect if \f(CRPORT\fR, \f(CREPRT\fR, or \f(CREPSV\fR is used instead of
\f(CRPASV\fR.
.TP 3
\fB-ftpsslauth\fR
Selects how TclCurl issues \f(CRAUTH TLS\fR or \f(CRAUTH SSL\fR when FTP over SSL is
enabled with \fB-ftpssl\fR.
.IP
This option may be needed for servers such as BSDFTPD-SSL, which do not
handle \f(CRAUTH SSL\fR correctly and require \f(CRAUTH TLS\fR instead.
.IP
Accepted values:
.RS
.TP 3
\f(CRdefault\fR
Lets TclCurl choose.
.TP 3
\f(CRssl\fR
Tries \f(CRAUTH SSL\fR first, and tries \f(CRAUTH TLS\fR only if that fails.
.TP 3
\f(CRtls\fR
Tries \f(CRAUTH TLS\fR first, and tries \f(CRAUTH SSL\fR only if that fails.
.RE
.TP 3
\fB-ftpsslccc\fR
Controls use of CCC (Clear Command Channel). CCC shuts down the SSL/TLS
layer after authentication, so the remainder of the control channel is
unencrypted. This can allow NAT routers to inspect the FTP control
channel.
.IP
Accepted values are:
.RS
.TP 3
\f(CRnone\fR
Do not attempt to use CCC.
.TP 3
\f(CRpassive\fR
Do not initiate the shutdown. Wait for the server to do so, and do
not send a reply.
.TP 3
\f(CRactive\fR
Initiate the shutdown and wait for a reply.
.RE
.TP 3
\fB-ftpaccount\fR
Pass a string containing account data, or \f(CR\(dq\(dq\fR to disable it. If an FTP
server requests account data after the user name and password have been
provided, TclCurl sends this value with the \f(CRACCT\fR command.
.TP 3
\fB-ftpfilemethod\fR
Selects how TclCurl navigates FTP paths. Accepted values are:
.RS
.TP 3
\f(CRmulticwd\fR
The default. TclCurl performs one \f(CRCWD\fR operation for each path
component in the URL. For deep hierarchies this may require many
commands. This is the method described by RFC 1738.
.TP 3
\f(CRnocwd\fR
TclCurl does not perform \f(CRCWD\fR at all. Instead it sends commands such
as \f(CRSIZE\fR, \f(CRRETR\fR, and \f(CRSTOR\fR with the full path.
.TP 3
\f(CRsinglecwd\fR
TclCurl performs one \f(CRCWD\fR to the full target directory and then
operates on the file normally. This is somewhat more standards
compliant than \f(CRnocwd\fR, without the full overhead of \f(CRmulticwd\fR.
.RE
.SH PROTOCOL OPTIONS
.TP 3
\fB-transfertext\fR
Set this option to \f(CR1\fR to use ASCII mode for FTP transfers instead of the
default binary transfer mode. On Win32 systems, this does not set
\f(CRstdout\fR to binary mode. This option can be useful when transferring text
data between systems that treat characters such as newlines differently.
.IP
\fBNOTE:\fR TclCurl does not perform full ASCII conversion during ASCII FTP
transfers. It simply sets the transfer mode to ASCII and performs a normal
transfer.
.TP 3
\fB-proxytransfermode\fR
Set this option to \f(CR1\fR to make TclCurl set the transfer mode, binary or
ASCII, for FTP transfers performed through an HTTP proxy by appending
\f(CR;type=a\fR or \f(CR;type=i\fR to the URL. If this option is omitted or set to
\f(CR0\fR, \fB-transfertext\fR has no effect for FTP transfers performed through
an HTTP proxy. Not all proxies support this feature.
.TP 3
\fB-crlf\fR
Set this option to \f(CR1\fR to make TclCurl convert Unix newlines to CRLF
newlines during transfers. Set it to \f(CR0\fR to disable this behavior.
.TP 3
\fB-range\fR
Pass a string specifying the requested range. The format is \f(CRX-Y\fR, where
either \f(CRX\fR or \f(CRY\fR may be omitted. HTTP transfers also support multiple
ranges separated by commas, as in \f(CRX-Y,N-M\fR. When multiple ranges are
requested over HTTP, the server returns the response document in pieces
using standard MIME separation rules.
.IP
Range requests are supported only for HTTP, FTP, and FILE transfers.
.TP 3
\fB-resumefrom\fR
Pass the offset, in bytes, at which the transfer should start. Set this
option to \f(CR0\fR to start the transfer from the beginning, which disables
resume behavior.
.IP
For FTP, set this option to \f(CR-1\fR to start from the end of the target
file, which is useful when continuing an interrupted upload.
.IP
For FTP uploads, the resume position specifies where in the local source
file TclCurl should resume reading. The data read from that point is then
appended to the remote target file.
.TP 3
\fB-customrequest\fR
Pass a string containing the request method to use instead of the default
method, such as \f(CRGET\fR or \f(CRHEAD\fR, when making an HTTP request. This is
useful for methods such as \f(CRDELETE\fR and other less common HTTP requests.
Use this option only when the server is known to support the specified
method.
.IP
TclCurl still behaves internally according to the type of request it would
otherwise have used. As a result, changing the request method with this
option can produce inconsistent behavior if the corresponding request type
is not selected through the usual dedicated option. For example, to make a
proper \f(CRHEAD\fR request, use \fB-nobody\fR. To make a proper \f(CRPOST\fR request,
use \fB-post\fR or \fB-postfields\fR.
.TP 3
\fB-filetime\fR
Set this option to \f(CR1\fR to make TclCurl attempt to obtain the modification
time of the remote document during the transfer. This requires the remote
server either to send the time directly or to support a command for
querying it. After the transfer, the \f(CRfiletime\fR value can be retrieved
with the \f(CRgetinfo\fR procedure.
.IP
For FTP transfers, this typically means that the server must support a
command for querying the remote file modification time, such as \f(CRMDTM\fR.
If the server does not provide this information, the transfer can still
succeed, but the retrieved \f(CRfiletime\fR value remains unknown.
.TP 3
\fB-nobody\fR
Set this option to \f(CR1\fR to omit the body from the output. This is relevant
only for protocols that distinguish between a header part and a body part.
For HTTP and HTTPS, this causes TclCurl to issue a \f(CRHEAD\fR request.
.IP
To change the request back to \f(CRGET\fR, use \fB-httpget\fR. To switch to
\f(CRPOST\fR, use \fB-post\fR or a related option.
.TP 3
\fB-infilesize\fR
Use this option when uploading a file to specify the expected size of the
input file.
.IP
This option is mandatory for uploads performed with SCP.
.TP 3
\fB-upload\fR
Set this option to \f(CR1\fR to prepare for an upload. The \fB-infile\fR and
\fB-infilesize\fR options are also relevant for uploads. If the protocol
is HTTP, uploading means using the PUT request unless you tell TclCurl
otherwise.
.IP
Using PUT with HTTP 1.1 implies the use of a \(lqExpect: 100-continue\(rq header.
You can disable this header with \fB-httpheader\fR as usual.
.IP
If you use PUT to a HTTP 1.1 server, you can upload data without knowing
the size before starting the transfer if you use chunked encoding. You
enable this by adding a header like \(lqTransfer-Encoding: chunked\(rq with
\fB-httpheader\fR. With HTTP 1.0 or without chunked transfer, you must
specify the size.
.TP 3
-maxfilesize
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 error \(oqfilesize exceeded\(cq (63) will be returned.
.IP
NOTE: 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.
.TP 3
-timecondition
Defines how the \fBtimevalue\fR value is treated. Accepted values are
\f(CRifmodsince\fR and \f(CRifunmodsince\fR. This feature applies to HTTP, FTP, and
FILE.
.TP 3
-timevalue
This should be the time in seconds since 1 jan 1970, and the time will be
used in a condition as specified with \fBtimecondition\fR.
.SH CONNECTION OPTIONS
.TP 3
\fB-timeout\fR
Pass the maximum time, in seconds, that a TclCurl transfer operation may
take. Name resolution alone may take a noticeable amount of time, so
setting this value too low can abort otherwise normal operations.
.IP
This option may cause libcurl to use \f(CRSIGALRM\fR to interrupt blocking
system calls. On Unix-like systems, signals may therefore be used unless
\fB-nosignal\fR is enabled.
.TP 3
\fB-timeoutms\fR
Like \fB-timeout\fR, but takes a value in milliseconds. If libcurl is built
to use the standard system name resolver, name resolution still uses
full-second timeout granularity.
.TP 3
\fB-lowspeedlimit\fR
Pass the speed, in bytes per second, below which the transfer rate must
remain during \fB-lowspeedtime\fR seconds before TclCurl considers the
transfer too slow and aborts it.
.TP 3
\fB-lowspeedtime\fR
Pass the number of seconds during which the transfer speed must stay below
\fB-lowspeedlimit\fR before TclCurl considers the transfer too slow and
aborts it.
.TP 3
\fB-maxsendspeed\fR
Pass a speed in bytes per second. If an upload exceeds this average speed
during the transfer, TclCurl pauses the transfer as needed to keep the
average rate less than or equal to the specified value. The default is
unlimited speed.
.TP 3
\fB-maxrecvspeed\fR
Pass a speed in bytes per second. If a download exceeds this average speed
during the transfer, TclCurl pauses the transfer as needed to keep the
average rate less than or equal to the specified value. The default is
unlimited speed.
.TP 3
\fB-maxconnects\fR
Sets the size of the persistent connection cache for protocols that support
persistent connections. This value is the maximum number of simultaneous
connections TclCurl may cache in the easy handle. The default is \f(CR5\fR.
.IP
When the maximum is reached, TclCurl closes the oldest cached connection
to prevent the number of open connections from increasing further.
.IP
\fBNOTE:\fR If transfers have already been performed with this easy handle,
reducing \fB-maxconnects\fR may cause existing open connections to be closed
earlier than expected.
.IP
If this easy handle is added to a multi handle, this setting is ignored.
In that case, configure the corresponding \fBmaxconnects\fR option on the
multi handle instead.
.TP 3
\fB-connecttimeout\fR
Pass the maximum time, in seconds, that the connection phase may take.
This limits only the time required to establish the connection. Once the
connection has been established, this option no longer applies. Set it to
\f(CR0\fR to disable the connection timeout.
.IP
On Unix-like systems, signals may be used unless \fB-nosignal\fR is enabled.
.TP 3
\fB-connecttimeoutms\fR
Like \fB-connecttimeout\fR, but takes a value in milliseconds. If libcurl is
built to use the standard system name resolver, name resolution still uses
full-second timeout granularity.
.TP 3
\fB-ipresolve\fR
Selects which IP address families may be used when resolving host names.
This option is relevant only when a host name resolves to more than one IP
version.
.IP
Accepted values are:
.RS
.TP 3
\f(CRwhatever\fR
The default. Resolves addresses using all IP versions supported by the
system.
.TP 3
\f(CRv4\fR
Resolves only IPv4 addresses.
.TP 3
\f(CRv6\fR
Resolves only IPv6 addresses.
.RE
.TP 3
\fB-resolve\fR
Pass a list of host name resolution entries to use for requests made with
this handle.
.IP
Each entry must use the format \f(CRHOST:PORT:ADDRESS\fR, where \f(CRHOST\fR is the
name TclCurl tries to resolve, \f(CRPORT\fR is the destination service port, and
\f(CRADDRESS\fR is the numeric IP address to use. If libcurl supports IPv6,
\f(CRADDRESS\fR may be either an IPv4 or an IPv6 address.
.IP
This option effectively pre-populates the DNS cache with entries for a
given \f(CRHOST:PORT\fR pair, so redirects and other requests to the same
\f(CRHOST:PORT\fR use the supplied \f(CRADDRESS\fR.
.IP
To remove an entry from the DNS cache, include a string in the form
\f(CR-HOST:PORT\fR. The host name must be prefixed with a dash, and both the
host name and port must exactly match an entry added earlier.
.TP 3
\fB-usessl\fR
Selects the desired level of SSL or TLS use for the transfer. This option
is relevant for protocols such as FTP, SMTP, POP3, and IMAP.
.IP
You can also use \f(CRftps://\fR URLs to enable SSL/TLS explicitly for both the
control connection and the data connection.
.IP
Accepted values:
.RS
.TP 3
\f(CRnope\fR
Do not attempt to use SSL.
.TP 3
\f(CRtry\fR
Attempt to use SSL, but continue even if it cannot be negotiated.
.TP 3
\f(CRcontrol\fR
Use SSL for the control connection, or fail with \f(CRuse ssl failed\fR
(\f(CR64\fR).
.TP 3
\f(CRall\fR
Use SSL for all communication, or fail with \f(CRuse ssl failed\fR (\f(CR64\fR).
.RE
.SH SSL AND SECURITY OPTIONS
.TP 3
\fB-sslcert\fR
Pass a string containing the file name of the certificate to use. The
default format is \f(CRPEM\fR, and it can be changed with \fB-sslcerttype\fR.
.IP
When libcurl is built against NSS, this value is the nickname of the
certificate to use for authentication. To use a file in the current
directory in that case, prefix it with \f(CR./\fR to avoid confusion with a
nickname.
.TP 3
\fB-sslcerttype\fR
Pass a string specifying the format of the certificate given with
\fB-sslcert\fR.
.IP
Accepted values are:
.RS
.TP 3
\f(CRPEM\fR
PEM format.
.TP 3
\f(CRDER\fR
DER format.
.RE
.TP 3
\fB-sslkey\fR
Pass a string containing the file name of the private key to use. The
default format is \f(CRPEM\fR, and it can be changed with \fB-sslkeytype\fR.
.TP 3
\fB-sslkeytype\fR
Pass a string specifying the format of the private key given with
\fB-sslkey\fR.
.IP
Accepted values are:
.RS
.TP 3
\f(CRPEM\fR
PEM format.
.TP 3
\f(CRDER\fR
DER format.
.TP 3
\f(CRENG\fR
Uses a crypto engine. In this case \fB-sslkey\fR is interpreted as an
identifier passed to the engine, and \fB-sslengine\fR must also be set.
.RE
.IP
\fBNOTE:\fR The \f(CRDER\fR private-key format may not work with some OpenSSL
versions because of upstream limitations.
.TP 3
\fB-keypasswd\fR
Pass a string containing the passphrase required to use the private key
specified with \fB-sslkey\fR or \fB-sshprivatekeyfile\fR.
.IP
A passphrase is not needed to load a certificate itself, but it may be
needed to load the corresponding private key.
.IP
This option was formerly known as \fB-sslkeypasswd\fR and
\fB-sslcertpasswd\fR.
.TP 3
\fB-sslengine\fR
Pass a string containing the identifier of the crypto engine to use for
private-key operations.
.IP
\fBNOTE:\fR If the crypto engine cannot be loaded, TclCurl returns an error.
.TP 3
\fB-sslenginedefault\fR
Set this option to \f(CR1\fR to make the selected crypto engine the default for
asymmetric cryptographic operations.
.IP
\fBNOTE:\fR If the crypto engine cannot be made the default, TclCurl returns
an error.
.TP 3
\fB-sslversion\fR
Selects the SSL or TLS protocol version to use.
.IP
Accepted values are:
.RS
.TP 3
\f(CRdefault\fR
Uses the default behavior. TclCurl attempts to negotiate an
appropriate protocol version with the remote server.
.TP 3
\f(CRtlsv1\fR
Requires TLSv1 or later.
.TP 3
\f(CRsslv2\fR
Requires SSLv2.
.TP 3
\f(CRsslv3\fR
Requires SSLv3.
.TP 3
\f(CRtlsv1_0\fR
Requires TLSv1.0 or later.
.TP 3
\f(CRtlsv1_1\fR
Requires TLSv1.1 or later.
.TP 3
\f(CRtlsv1_2\fR
Requires TLSv1.2 or later.
.TP 3
\f(CRtlsv1_3\fR
Requires TLSv1.3 or later.
.TP 3
\f(CRmaxdefault\fR
Uses the maximum TLS version supported by libcurl or by the SSL
backend\(cqs default configuration.
.TP 3
\f(CRmaxtlsv1_0\fR
Sets the maximum supported TLS version to TLSv1.0.
.TP 3
\f(CRmaxtlsv1_1\fR
Sets the maximum supported TLS version to TLSv1.1.
.TP 3
\f(CRmaxtlsv1_2\fR
Sets the maximum supported TLS version to TLSv1.2.
.TP 3
\f(CRmaxtlsv1_3\fR
Sets the maximum supported TLS version to TLSv1.3.
.RE
.TP 3
\fB-sslverifypeer\fR
Controls whether TclCurl verifies the authenticity of the peer
certificate. Set this option to \f(CR1\fR to enable verification or to \f(CR0\fR to
disable it. The default is \f(CR1\fR.
.IP
During the SSL or TLS handshake, the server sends a certificate declaring
its identity. TclCurl verifies that certificate against a chain of trust
rooted in one or more certification authority (CA) certificates.
.IP
TclCurl uses the default CA bundle provided by libcurl, but you can
specify alternate certificates with \fB-cainfo\fR or \fB-capath\fR.
.IP
If \fB-sslverifypeer\fR is nonzero and verification fails, the connection
fails. If this option is \f(CR0\fR, peer-certificate verification is skipped.
.IP
Certificate verification alone does not confirm that the peer is the
specific host you intended to contact. Use \fB-sslverifyhost\fR to control
host-name verification.
.TP 3
\fB-cainfo\fR
Pass the name of a file containing one or more CA certificates used to
verify the peer certificate.
.IP
This option is meaningful primarily together with \fB-sslverifypeer\fR. If
peer verification is disabled, \fB-cainfo\fR does not need to name an
accessible file.
.IP
By default, this option is set to the system path of libcurl\(cqs CA bundle,
as determined when libcurl was built.
.IP
When libcurl is built against NSS, this value refers to the directory
containing the NSS certificate database.
.TP 3
\fB-issuercert\fR
Pass the name of a file containing a CA certificate in PEM format. If this
option is set, an additional check is performed to verify that the peer
certificate was issued by the CA certificate provided here.
.IP
This is useful in multi-level PKI environments where the peer certificate
must be constrained to a specific branch of the certificate hierarchy.
.IP
This option is meaningful only when used together with
\fB-sslverifypeer\fR. Otherwise, failure of this additional check is not
treated as a connection failure.
.TP 3
\fB-capath\fR
Pass the name of a directory containing multiple CA certificates to use
when verifying the peer certificate.
.IP
When libcurl is built against OpenSSL, this directory must be prepared
with the \f(CRopenssl c_rehash\fR utility. This option is meaningful primarily
together with \fB-sslverifypeer\fR. If peer verification is disabled,
\fB-capath\fR does not need to name an accessible directory.
.IP
This option is OpenSSL-specific and has no effect when libcurl is built
against GnuTLS. NSS-based libcurl provides it only for backward
compatibility.
.IP
On Windows, this option may not work because of OpenSSL limitations.
.TP 3
\fB-crlfile\fR
Pass the name of a file containing one or more certificate revocation
lists in PEM format to use during certificate validation.
.IP
When libcurl is built against NSS or GnuTLS, there is no supported way to
influence revocation checking with this option. When libcurl is built with
OpenSSL support, both \f(CRX509_V_FLAG_CRL_CHECK\fR and
\f(CRX509_V_FLAG_CRL_CHECK_ALL\fR are enabled if a CRL file is provided, so CRL
checking is applied throughout the certificate chain.
.IP
This option is meaningful only when used together with
\fB-sslverifypeer\fR.
.IP
If the CRL file cannot be loaded, the SSL exchange fails with the specific
error code \f(CRCURLE_SSL_CRL_BADFILE\fR. A certificate-verification failure
caused by revocation information in the CRL does not produce that specific
error code.
.TP 3
\fB-sslverifyhost\fR
Controls whether TclCurl verifies that the server certificate matches the
host name you intended to contact.
.IP
During the SSL or TLS handshake, the server sends a certificate declaring
its identity.
.IP
When \fB-sslverifyhost\fR is set to \f(CR2\fR, the certificate must identify the
intended server or the connection fails. TclCurl considers the server to
match when the Common Name field or a Subject Alternative Name field in
the certificate matches the host name in the URL.
.IP
When this option is set to \f(CR1\fR, the certificate must contain a Common Name
field, but the specific name is not checked. This setting is generally not
useful.
.IP
When this option is set to \f(CR0\fR, the connection succeeds regardless of the
names contained in the certificate.
.IP
The default value is \f(CR2\fR.
.IP
This option verifies the host identity claimed by the certificate. To
verify that the certificate itself is trusted, use \fB-sslverifypeer\fR. If
libcurl is built against NSS and \fB-sslverifypeer\fR is \f(CR0\fR,
\fB-sslverifyhost\fR is ignored.
.TP 3
\fB-certinfo\fR
Set this option to \f(CR1\fR to enable collection of certificate-chain
information. When enabled, TclCurl, if built against OpenSSL, extracts
certificate details from the chain used in the SSL connection.
.IP
That information can be retrieved after the transfer with the \fBgetinfo\fR
command and its \f(CRcertinfo\fR option.
.TP 3
\fB-randomfile\fR
Pass a file name. TclCurl uses this file as a source of randomness for the
SSL random engine. \fIThis option was deprecated in libcurl v7.84 and is
disabled by default in the TclCurl build. See \f(CIREADME.md\fI for instructions
on how to re-enable it.\fR
.TP 3
\fB-egdsocket\fR
Pass the path name of an Entropy Gathering Daemon socket. TclCurl uses it
as a source of randomness for the SSL random engine. \fIThis option was
deprecated in libcurl v7.84 and is disabled by default in the TclCurl
build. See \f(CIREADME.md\fI for instructions on how to re-enable it.\fR
.TP 3
\fB-sslcipherlist\fR
Pass a string containing the cipher list to use for the SSL or TLS
connection. The list consists of one or more cipher strings separated
normally by colons, although commas or spaces are also accepted. The
characters \f(CR!\fR, \f(CR-\fR, and \f(CR+\fR may also be used as operators.
.IP
With OpenSSL and GnuTLS, valid examples include \f(CRRC4-SHA\fR, \f(CRSHA1+DES\fR,
\f(CRTLSv1\fR, and \f(CRDEFAULT\fR. The default list is usually defined by the SSL
backend at build time.
.IP
With NSS, valid examples include \f(CRrsa_rc4_128_md5\fR and
\f(CRrsa_aes_128_sha\fR. NSS does not support incremental add or remove
semantics for ciphers. If this option is used, all known ciphers are
disabled and only the ciphers listed here are enabled.
.IP
For details about cipher-list syntax, see:
.UR http://www.openssl.org/docs/apps/ciphers.html
.UE
.IP
For NSS-specific cipher-list details, see:
.UR http://directory.fedora.redhat.com/docs/mod_nss.html
.UE
.TP 3
\fB-sslsessionidcache\fR
Set this option to \f(CR0\fR to disable TclCurl\(cqs use of SSL session-ID caching,
or to \f(CR1\fR to enable it. The default is \f(CR1\fR.
.IP
In normal circumstances, reusing SSL session IDs is harmless and may
improve performance. However, some broken SSL implementations may require
this option to be disabled.
.TP 3
\fB-krblevel\fR
Selects the Kerberos security level for FTP and thereby also enables
Kerberos awareness.
.IP
Accepted values are \f(CRclear\fR, \f(CRsafe\fR, \f(CRconfidential\fR, and \f(CRprivate\fR. If
the string does not match one of these values, \f(CRprivate\fR is used.
.IP
Set the string to \f(CRNULL\fR to disable Kerberos 4. Set it to \f(CR\(dq\(dq\fR to disable
Kerberos support for FTP.
.TP 3
\fB-gssapidelegation\fR
Selects the GSSAPI credential delegation mode.
.IP
Accepted values are:
.RS
.TP 3
\f(CRflag\fR
Allows unconditional delegation.
.TP 3
\f(CRpolicyflag\fR
Delegates only if the \f(CROK-AS-DELEGATE\fR flag is set in the service
ticket, provided that this feature is supported by the GSSAPI
implementation and that \f(CRGSS_C_DELEG_POLICY_FLAG\fR was available at
compile time.
.RE
.IP
Delegation is disabled by default since 7.21.7.
.SH SSH OPTIONS
.TP 3
\fB-sshauthtypes\fR
Selects the allowed SSH authentication types.
.IP
Accepted values are:
.RS
.TP 3
\f(CRpublickey\fR
Use public-key authentication.
.TP 3
\f(CRpassword\fR
Use password authentication.
.TP 3
\f(CRhost\fR
Use host-based authentication.
.TP 3
\f(CRkeyboard\fR
Use keyboard-interactive authentication.
.TP 3
\f(CRany\fR
Let TclCurl select an authentication method automatically.
.RE
.TP 3
\fB-sshhostpublickeymd5\fR
Pass a string containing 32 hexadecimal digits. The string must be the
128-bit MD5 checksum of the remote host public key. TclCurl rejects the
connection unless the checksum matches.
.IP
This option applies only to SCP and SFTP transfers.
.TP 3
\fB-sshpublickeyfile\fR
Pass the file name of the public key to use.
.IP
If this option is not used, TclCurl defaults to \f(CR$HOME/.ssh/id_dsa.pub\fR
when the \f(CRHOME\fR environment variable is set, and to \f(CRid_dsa.pub\fR in the
current directory otherwise.
.TP 3
\fB-sshprivatekeyfile\fR
Pass the file name of the private key to use.
.IP
If this option is not used, TclCurl defaults to \f(CR$HOME/.ssh/id_dsa\fR when
the \f(CRHOME\fR environment variable is set, and to \f(CRid_dsa\fR in the current
directory otherwise.
.IP
If the private key is passphrase-protected, use \fB-keypasswd\fR to specify
the passphrase.
.TP 3
\fB-sshknownhosts\fR
Pass a string containing the file name of the \f(CRknown_hosts\fR file to use.
The file must use the OpenSSH \f(CRknown_hosts\fR format supported by libssh2.
.IP
If this option is set, TclCurl accepts connections only to hosts that are
present in that file with a matching public key. Use \fB-sshkeyproc\fR to
override the default behavior for host and key matching.
.TP 3
\fB-sshkeyproc\fR
Pass the name of a callback procedure that TclCurl invokes after
\f(CRknown_hosts\fR matching has been performed, so that the application can
decide how the connection should proceed.
.IP
The callback is invoked only if \fB-sshknownhosts\fR is also set.
.IP
The callback receives a list with three elements:
.RS
.IP "1." 3
A list containing the key type from the \f(CRknown_hosts\fR file and the key
itself.
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "2." 3
A list containing the key type presented by the remote host and the key
itself.
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "3." 3
A value describing TclCurl\(cqs matching result.
.RE
.IP
Possible key-type values are \f(CRrsa\fR, \f(CRrsa1\fR, \f(CRdss\fR, and \f(CRunknown\fR.
.IP
Possible match-result values are \f(CRmatch\fR, \f(CRmismatch\fR, \f(CRmissing\fR, and
\f(CRerror\fR.
.IP
Return values:
.RS
.TP 3
\f(CR0\fR
Accept the host and key. TclCurl appends the host and key to the
\f(CRknown_hosts\fR file before continuing with the connection. If the host
and key are not already present in the in-memory known-hosts pool,
TclCurl also adds them there. Updating the file is done by replacing
it with a new copy, so the file permissions must allow that.
.TP 3
\f(CR1\fR
Accept the host and key, and continue with the connection. If the host
and key are not already present in the in-memory known-hosts pool,
TclCurl also adds them there.
.TP 3
\f(CR2\fR
Reject the host and key. TclCurl closes the connection.
.TP 3
\f(CR3\fR
Reject the host and key, but keep the SSH connection alive. This can
be useful if the application needs to inspect the host or key state and
then retry without incurring the full setup cost again.
.RE
.IP
Any other return value causes TclCurl to close the connection.
.SH OTHER OPTIONS
.TP 3
\fB-headervar\fR
Name of the Tcl array variable in which TclCurl stores the headers returned
by the server.
.TP 3
\fB-bodyvar\fR
Name of the Tcl variable in which TclCurl stores the requested file
contents. The stored data may be either text or binary data.
.TP 3
\fB-canceltransvarname\fR
Name of a Tcl variable used together with \fB-progressproc\fR. If the
progress callback sets this variable to \f(CR1\fR, the transfer is canceled.
.TP 3
\fB-command\fR
Executes the given command after the transfer has completed.
.IP
This option works only with blocking transfers and therefore has limited
practical use.
.TP 3
\fB-share\fR
Pass a share handle. The share handle must have been created previously by
calling \fBcurl::shareinit\fR.
.IP
Setting this option causes the easy handle to use data from the shared
handle instead of keeping its own separate copy. See \fItclcurl_share\fR for
details.
.TP 3
\fB-newfileperms\fR
Pass a numeric value specifying the permissions assigned to newly created
files on the remote server. The default value is \f(CR0644\fR, but any valid
value may be used.
.IP
This option applies only to \f(CRsftp://\fR, \f(CRscp://\fR, and \f(CRfile://\fR transfers.
.TP 3
\fB-newdirectoryperms\fR
Pass a numeric value specifying the permissions assigned to newly created
directories on the remote server. The default value is \f(CR0755\fR, but any
valid value may be used.
.IP
This option applies only to \f(CRsftp://\fR, \f(CRscp://\fR, and \f(CRfile://\fR transfers.
.SH TELNET OPTIONS
.TP 3
-telnetoptions
Pass a list with variables to pass to the telnet negotiations. The
variables should be in the format . TclCurl supports the
options \(oqTTYPE\(cq, \(oqXDISPLOC\(cq and \(oqNEW_ENV\(cq. See the TELNET standard for
details.
.SH NOT SUPPORTED
.LP
Some of the options libcurl offers are not supported, I don\(cqt think them worth
supporting in TclCurl but if you need one of them don\(cqt forget to complain:
.PP
\fBCURLOPT\f(BIFRESH\fBCONNECT, CURLOPT\f(BIFORBID\fBREUSE, CURLOPT_PRIVATE,\fR
.PP
\fBCURLOPT\f(BISSL\fBCTX\f(BIFUNCTION, CURLOPT\fBSSL\f(BICTX\fBDATA, CURLOPT\f(BISSL\fBCTX_FUNCTION and\fR
.PP
\fBCURLOPT\f(BICONNECT\fBONLY, CURLOPT\f(BIOPENSOCKETFUNCTION, CURLOPT\fBOPENSOCKETDATA.\fR
.SH curlHandle perform
.LP
This procedure is called after the
.PP
\fBinit\fR
.PP
and all the
.PP
\fBconfigure\fR
.PP
calls are made, and will perform the transfer as described in the options.
.PP
It must be called with the same \fIcurlHandle\fR \fBcurl::init\fR call returned. You
can do any amount of calls to perform while using the same handle. If you
intend to transfer more than one file, you are even encouraged to do so.
TclCurl will then attempt to re-use the same connection for the following
transfers, thus making the operations faster, less CPU intense and using less
network resources. Just note that you will have to use configure between the
invokes to set options for the following perform.
.PP
You must never call this procedure simultaneously from two places using the
same handle. Let it return first before invoking it another time. If you want
parallel transfers, you must use several curl handles.
.TP 3
RETURN VALUE
\f(CR0\fR if all went well, non-zero if it didn\(cqt. In case of error, if the
errorbuffer was set with configure there will be a readable error message.
The error codes are:
.RS
.TP 3
\fB1\fR
Unsupported protocol. This build of TclCurl has no support for this
protocol.
.TP 3
\fB2\fR
Very early initialization code failed. This is likely to be and
internal error or a resource problem where something fundamental couldn\(cqt
get done at init time.
.TP 3
\fB3\fR
URL malformat. The syntax was not correct.
.TP 3
\fB4\fR
A requested feature, protocol or option was not found built-in in
this libcurl due to a build-time decision. This means that a feature or
option was not enabled or explicitly disabled when libcurl was built and in
order to get it to function you have to get a rebuilt libcurl.
.TP 3
\fB5\fR
Couldn\(cqt resolve proxy. The given proxy host could not be resolved.
.TP 3
\fB6\fR
Couldn\(cqt resolve host. The given remote host was not resolved.
.TP 3
\fB7\fR
Failed to connect to host or proxy.
.TP 3
\fB8\fR
FTP weird server reply. The server sent data TclCurl couldn\(cqt parse.
The given remote server is probably not an OK FTP server.
.TP 3
\fB9\fR
We were denied access to the resource given in the URL. For FTP, this
occurs while trying to change to the remote directory.
.TP 3
\fB11\fR
FTP weird PASS reply. TclCurl couldn\(cqt parse the reply sent to the
PASS request.
.TP 3
\fB13\fR
FTP weird PASV reply, TclCurl couldn\(cqt parse the reply sent to the
PASV or EPSV request.
.TP 3
\fB14\fR
FTP weird 227 format. TclCurl couldn\(cqt parse the 227-line the server
sent.
.TP 3
\fB15\fR
FTP can\(cqt get host. Couldn\(cqt resolve the host IP we got in the
227-line.
.TP 3
\fB17\fR
FTP couldn\(cqt set type. Couldn\(cqt change transfer method to either
binary or ascii.
.TP 3
\fB18\fR
Partial file. Only a part of the file was transferred, this happens
when the server first reports an expected transfer size and then delivers
data that doesn\(cqt match the given size.
.TP 3
\fB19\fR
FTP couldn\(cqt RETR file, we either got a weird reply to a \(oqRETR\(cq
command or a zero byte transfer.
.TP 3
\fB21\fR
Quote error. A custom \(oqQUOTE\(cq returned error code 400 or higher (for
FTP) or otherwise indicated unsuccessful completion of the command.
.TP 3
\fB22\fR
HTTP returned error. This return code only appears if
\fB-failonerror\fR is used and the HTTP server returns an error code that is
400 or higher.
.TP 3
\fB23\fR
Write error. TclCurl couldn\(cqt write data to a local filesystem or an
error was returned from a write callback.
.TP 3
\fB25\fR
Failed upload failed. For FTP, the server typcially denied the STOR
command. The error buffer usually contains the server\(cqs explanation to
this.
.TP 3
\fB26\fR
Read error. There was a problem reading from a local file or an
error was returned from the read callback.
.TP 3
\fB27\fR
Out of memory. A memory allocation request failed. This should never
happen unless something weird is going on in your computer.
.TP 3
\fB28\fR
Operation timeout. The specified time-out period was reached
according to the conditions.
.TP 3
\fB30\fR
The FTP PORT command failed, not all FTP servers support the PORT
command, try  doing a transfer using PASV instead!.
.TP 3
\fB31\fR
FTP couldn\(cqt use REST. This command is used for resumed FTP
transfers.
.TP 3
\fB33\fR
Range error. The server doesn\(cqt support or accept range requests.
.TP 3
\fB34\fR
HTTP post error. Internal post-request generation error.
.TP 3
\fB35\fR
SSL connect error. The SSL handshaking failed, the error buffer may
have a clue to the reason, could be certificates, passwords, \[u2026]
.TP 3
\fB36\fR
The download could not be resumed because the specified offset was
out of the file boundary.
.TP 3
\fB37\fR
A file given with FILE:// couldn\(cqt be read. Did you checked the
permissions?
.TP 3
\fB38\fR
LDAP cannot bind. LDAP bind operation failed.
.TP 3
\fB39\fR
LDAP search failed.
.TP 3
\fB41\fR
A required zlib function was not found.
.TP 3
\fB42\fR
Aborted by callback. An application told TclCurl to abort the
operation.
.TP 3
\fB43\fR
Internal error. A function was called with a bad parameter.
.TP 3
\fB45\fR
Interface error. A specified outgoing interface could not be used.
.TP 3
\fB47\fR
Too many redirects. When following redirects, TclCurl hit the
maximum amount, set your limit with \(enmaxredirs
.TP 3
\fB48\fR
An option passed to TclCurl is not recognized/known. Refer to the
appropriate documentation. This is most likely a problem in the program
that uses TclCurl. The error buffer might contain more specific information
about which exact option it concerns.
.TP 3
\fB49\fR
A telnet option string was illegally formatted.
.TP 3
\fB51\fR
The remote peer\(cqs SSL certificate or SSH md5 fingerprint wasn\(cqt ok
.TP 3
\fB52\fR
The server didn\(cqt reply anything, which here is considered an error.
.TP 3
\fB53\fR
The specified crypto engine wasn\(cqt found.
.TP 3
\fB54\fR
Failed setting the selected SSL crypto engine as default!
.TP 3
\fB55\fR
Failed sending network data.
.TP 3
\fB56\fR
Failure with receiving network data.
.TP 3
\fB58\fR
Problem with the local client certificate.
.TP 3
\fB59\fR
Couldn\(cqt use specified SSL cipher.
.TP 3
\fB60\fR
Peer certificate cannot be authenticated with known CA certificates.
.TP 3
\fB61\fR
Unrecognized transfer encoding.
.TP 3
\fB62\fR
Invalid LDAP URL.
.TP 3
\fB63\fR
Maximum file size exceeded.
.TP 3
\fB64\fR
SSL use failed.
.TP 3
\fB65\fR
Sending the data requires a rewind that failed, since TclCurl should
take care of it for you, it means you found a bug.
.TP 3
\fB66\fR
Failed to initialise ssl engine.
.TP 3
\fB67\fR
Failed to login, user password or similar was not accepted.
.TP 3
\fB68\fR
File not found on TFTP server.
.TP 3
\fB69\fR
There is a permission problem with the TFTP request.
.TP 3
\fB70\fR
The remote server has run out of space.
.TP 3
\fB71\fR
Illegal TFTP operation.
.TP 3
\fB72\fR
Unknown transfer ID.
.TP 3
\fB73\fR
TFTP file already exists and will not be overwritten.
.TP 3
\fB74\fR
No such user in the TFTP server and good behaving TFTP servers
should never return this.
.TP 3
\fB75\fR
Character conversion failed.
.TP 3
\fB77\fR
Problem with reading the SSL CA cert (path? access rights?).
.TP 3
\fB78\fR
Remote file not found
.TP 3
\fB79\fR
Error from the SSH layer
.TP 3
\fB80\fR
Failed to shut down the SSL connection
.TP 3
\fB82\fR
Failed to load CRL file
.TP 3
\fB83\fR
Issuer check failed
.TP 3
\fB84\fR
The FTP server does not understand the PRET command at all or does
not support the given argument. Be careful when using \fB-customrequest\fR, a
custom LIST command will be sent with PRET CMD before PASV as well.
.TP 3
\fB85\fR
Mismatch of RTSP CSeq numbers.
.TP 3
\fB86\fR
Mismatch of RTSP Session Identifiers.
.TP 3
\fB87\fR
Unable to parse FTP file list (during FTP wildcard downloading).
.TP 3
\fB88\fR
Chunk callback reported error.
.RE
.SH curlHandle getinfo OPTION
.LP
Request internal information from the curl session with this procedure. This
procedure is intended to get used \fIAFTER\fR a performed transfer, and can be
relied upon only if the \fBperform\fR returns 0.  Use this function AFTER a
performed transfer if you want to get transfer-oriented data.
.PP
The following information can be extracted:
.TP 3
effectiveurl
Returns the last used effective URL.
.TP 3
responsecode
Returns the last received HTTP or FTP code. This will be zero if no server
response code has been received. Note that a proxy\(cqs CONNECT response
should be read with \fBhttpconnectcode\fR and not this.
.TP 3
httpconnectcode
Returns the last received proxy response code to a CONNECT request.
.TP 3
filetime
Returns the remote time of the retrieved document (in number of seconds
since 1 jan 1970 in the GMT/UTC time zone). If you get -1, it can be
because of many reasons (unknown, the server hides it or the server doesn\(cqt
support the command that tells document time etc) and the time of the
document is unknown.
.IP
In order for this to work you have to set the \fB-filetime\fR option before
the transfer.
.TP 3
namelookuptime
Returns the time, in seconds, it took from the start until the name
resolving was completed.
.TP 3
connecttime
Returns the time, in seconds, it took from the start until the connect to
the remote host (or proxy) was completed.
.TP 3
appconnecttime
Returns the time, in seconds, it took from the start until the SSL/SSH
connect/handshake to the remote host was completed. This time is most often
very near to the PRETRANSFER time, except for cases such as HTTP
pippelining where the pretransfer time can be delayed due to waits in line
for the pipeline and more.
.TP 3
pretransfertime
Returns the time, in seconds, it took from the start until the file
transfer is just about to begin. This includes all pre-transfer commands
and negotiations that are specific to the particular protocol(s) involved.
.TP 3
starttransfertime
Returns the time, in seconds, it took from the start until the first byte
is just about to be transferred. This includes the \fBpretransfertime\fR, and
also the time the server needs to calculate the result.
.TP 3
totaltime
Returns the total transaction time, in seconds, for the previous transfer,
including name resolving, TCP connect etc.
.TP 3
redirecturl
Returns the URL a redirect would take you to if you enable
\fBfollowlocation\fR. This can come very handy if you think using the
built-in libcurl redirect logic isn\(cqt good enough for you but you would
still prefer to avoid implementing all the magic of figuring out the new
URL.
.TP 3
redirecttime
Returns the total time, in seconds, it took for all redirection steps
including name lookup, connect, pretransfer and transfer before the final
transaction was started, it returns the complete execution time for
multiple redirections, so it returns zero if no redirections were needed.
.TP 3
redirectcount
Returns the total number of redirections that were actually followed.
.TP 3
numconnects
Returns how many new connections TclCurl had to create to achieve the
previous transfer (only the successful connects are counted). Combined with
\fBredirectcount\fR you are able to know how many times TclCurl successfully
reused existing connection(s) or not. See the Connection Options of
\fBsetopt\fR to see how TclCurl tries to make persistent connections to save
time.
.TP 3
primaryip
Returns the IP address of the most recent connection done with this handle.
This string may be IPv6 if that\(cqs enabled.
.TP 3
primaryport
Returns the destination port of the most recent connection done with this
handle.
.TP 3
localip
Returns the local (source) IP address of the most recent connection done
with this handle. This string may be IPv6 if that\(cqs enabled.
.TP 3
localport
Returns the local (source) port of the most recent connection done with
this handle.
.TP 3
sizeupload
Returns the total amount of bytes that were uploaded.
.TP 3
sizedownload
Returns the total amount of bytes that were downloaded. The amount is only
for the latest transfer and will be reset again for each new transfer.
.TP 3
speeddownload
Returns the average download speed, measured in bytes/second, for the
complete download.
.TP 3
speedupload
Returns the average upload speed, measured in bytes/second, for the
complete upload.
.TP 3
headersize
Returns the total size in bytes of all the headers received.
.TP 3
requestsize
Returns the total size of the issued requests. This is so far only for HTTP
requests. Note that this may be more than one request if followLocation is
true.
.TP 3
sslverifyresult
Returns the result of the certification verification that was requested
(using the -sslverifypeer option to configure).
.TP 3
sslengines
Returns a \fBlist\fR of the OpenSSL crypto-engines supported. Note that
engines are normally implemented in separate dynamic libraries. Hence not
all the returned engines may be available at run-time.
.TP 3
contentlengthdownload
Returns the content-length of the download. This is the value read from the
\fBContent-Length:\fR field. If the size isn\(cqt known, it returns -1.
.TP 3
contentlengthupload
Returns the specified size of the upload.
.TP 3
contenttype
Returns the content-type of the downloaded object. This is the value read
from the Content-Type: field. If you get an empty string, it  means the
server didn\(cqt send a valid Content-Type header or that the protocol used
doesn\(cqt support this.
.TP 3
httpauthavail
Returns a list with the authentication method(s) available.
.TP 3
proxyauthavail
Returns a list with the authentication method(s) available for your proxy
athentication.
.TP 3
oserrno
Returns the errno value from a connect failure. This value is only set on
failure, it is no reset after a successful operation.
.TP 3
cookielist
Returns a list of all cookies TclCurl knows (expired ones, too). If there
are no cookies (cookies for the handle have not been enabled or simply none
have been received) the list will be empty.
.TP 3
ftpentrypath
Returns a string holding the path of the entry path. That is the initial
path TclCurl ended up in when logging on to the remote FTP server. Returns
an empty string if something is wrong.
.TP 3
certinfo
Returns list with information about the certificate chain, assuming you had
the \fB-certinfo\fR option enabled when the previous request was done. The
list first item reports how many certs it found and then you can extract
info for each of those certs by following the list. The info chain is
provided in a series of data in the format \(lqname:content\(rq where the content
is for the specific named data.
.IP
NOTE: this option is only available in libcurl built with OpenSSL support.
.TP 3
conditionunmet
Returns the number 1 if the condition provided in the previous request
didn\(cqt match (see \fItimecondition\fR), you will get a zero if the condition
instead was met.
.SH curlHandle cleanup
.LP
This procedure must be the last one to call for a curl session. It is the
opposite of the curl::init procedure and must be called with the same
curlhandle as input as the curl::init call returned. This will effectively
close all connections TclCurl has used and possibly has kept open until now.
Don\(cqt call this procedure if you intend to transfer more files.
.SH curlHandle reset
.LP
Re-initializes all options previously set on a specified handle to the default
values.
.PP
This puts back the handle to the same state as it was in when it was just
created with curl::init.
.PP
It does not change the following information kept in the handle: live
connections, the Session ID cache, the DNS cache, the cookies and shares.
.SH curlHandle duphandle
.LP
This procedure will return a new curl handle, a duplicate, using all the
options previously set in the input curl handle. Both handles can subsequently
be used independently and they must both be freed with \fBcleanup\fR.
.PP
The new handle will not inherit any state information, connections, SSL
sessions or cookies.
.TP 3
RETURN VALUE
A new curl handle or an error message if the copy fails.
.SH curlHandle pause
.LP
You can use this command from within a progress callback procedure to pause the
transfer.
.SH curlHandle resume
.LP
Resumes a transfer paused with \fBcurlhandle pause\fR
.SH curl::transfer
.LP
In case you do not want to use persistent connections you can use this command,
it takes the same arguments as the \fIcurlHandle\fR \fBconfigure\fR and will init,
configure, perform and cleanup a connection for you.
.PP
You can also get the \fIgetinfo\fR information by using \fI-infooption variable\fR
pairs, after the transfer \fIvariable\fR will contain the value that would have
been returned by \fI$curlHandle getinfo option\fR.
.TP 3
RETURN VALUE
The same error code \fBperform\fR would return.
.SH curl::version
.LP
Returns a string with the version number of tclcurl, libcurl and some of its
important components (like OpenSSL version).
.TP 3
RETURN VALUE
The string with the version info.
.SH curl::escape URL
.LP
This procedure will convert the given input string to an URL encoded string and
return that. All input characters that are not a-z, A-Z or 0-9 will be
converted to their \(lqURL escaped\(rq version (%NN where NN is a two-digit
hexadecimal number)
.TP 3
RETURN VALUE
The converted string.
.SH curl::unescape URL
.LP
This procedure will convert the given URL encoded input string to a \(lqplain
string\(rq and return that. All input characters that are URL encoded (%XX where
XX is a two-digit hexadecimal number) will be converted to their plain text
versions.
.TP 3
RETURN VALUE
The string unencoded.
.SH curl::curlConfig OPTION
.LP
Returns some information about how you have \fBcURL\fR installed.
.TP 3
-prefix
Returns the directory root where you installed \fBcURL\fR.
.TP 3
-feature
Returns a list containing particular main features the installed
\fBlibcurl\fR was built with. The list may include SSL, KRB4 or IPv6, do not
assume any particular order.
.TP 3
-vernum
Outputs  version  information  about  the installed libcurl, in numerical
mode.  This outputs the  version  number,  in hexadecimal, with 8 bits for
each part; major, minor, patch. So  that  libcurl 7.7.4 would appear as
070704 and libcurl 12.13.14 would appear as 0c0d0e\[u2026]
.SH curl::versioninfo OPTION
.LP
Returns information about various run-time features in TclCurl.
.PP
Applications should use this information to judge if things are possible to do
or not, instead of using compile-time checks, as dynamic/DLL libraries can be
changed independent of applications.
.TP 3
-version
Returns the version of libcurl we are using.
.TP 3
-versionnum
Returns the version of libcurl we are using in hexadecimal with 8 bits for
each part; major, minor, patch. So  that  libcurl 7.7.4 would appear as
070704 and libcurl 12.13.14 would appear as 0c0d0e\[u2026] Note that the initial
zero might be omitted.
.TP 3
-host
Returns a string with the host information as discovered by a configure
script or set by the build environment.
.TP 3
-features
Returns a list with the features compiled into libcurl, the possible
elements are:
.TP 3
ASYNCHDNS
Libcurl was built with support for asynchronous name lookups, which allows
more exact timeouts (even on Windows) and less blocking when using the
multi interface.
.TP 3
CONV
Libcurl was built with support for character conversions.
.TP 3
DEBUG
Libcurl was built with extra debug capabilities built-in. This is mainly of
interest for libcurl hackers.
.TP 3
GSSNEGOTIATE
Supports HTTP GSS-Negotiate.
.TP 3
IDN
Supports IDNA, domain names with international letters.
.TP 3
IPV6
Supports IPv6.
.TP 3
KERBEROS4
Supports kerberos4 (when using FTP).
.TP 3
LARGEFILE
Libcurl was built with support for large files.
.TP 3
LIBZ
Supports HTTP deflate using libz.
.TP 3
NTML
Supports HTTP NTLM
.TP 3
SPNEGO
Libcurl was built with support for SPNEGO authentication (Simple and
Protected GSS-API Negotiation Mechanism, defined in RFC 2478)
.TP 3
SSL
Supports SSL (HTTPS/FTPS)
.TP 3
SSPI
Libcurl was built with support for SSPI. This is only available on Windows
and makes libcurl use Windows-provided functions for NTLM authentication.
It also allows libcurl to use the current user and the current user\(cqs
password without the app having to pass them on.
.TP 3
TLSAUTH_SRP
Libcurl was built with support for TLS-SRP.
.IP
\fBNTLM_WB\fR
.IP
Libcurl was built with support for NTLM delegation to a winbind helper.
.IP
Do not assume any particular order.
.TP 3
-sslversion
Returns a string with the OpenSSL version used, like OpenSSL/0.9.6b.
.TP 3
-sslversionnum
Returns the numerical OpenSSL version value as defined by the OpenSSL
project. If libcurl has no SSL support, this is 0.
.TP 3
-libzversion
Returns a string, there is no numerical  version, for example: 1.1.3.
.TP 3
-protocols
Lists what particular protocols the installed TclCurl was built to support.
At the time of writing, this list may include HTTP, HTTPS, FTP, FTPS, FILE,
TELNET, LDAP, DICT. Do not assume any particular order. The protocols will
be listed using uppercase. There may be none, one or several protocols in
the list.
.SH curl::easystrerror errorCode
.LP
This procedure returns a string describing the error code passed in the
argument.
.SH EXAMPLES
.LP
The examples in this section assume you are running from the root of the
TclCurl source tree.
.PP
To start the local HTTP test server used in the examples, run:
.LP
.EX
tclsh testservers/testserver.tcl
.EE
.PP
By default, this starts an HTTP server on \f(CRhttp://127.0.0.1:8990/\fR.
.PP
The path \f(CRhttp://127.0.0.1:8990/tclcurl-man\fR returns the HTML version of this
manual page from \f(CRdoc/tclcurl.html\fR, which makes it a convenient target for a
basic \f(CRGET\fR example.
.SH BASIC HTTP GET
.LP
The file \f(CRexamples/http_get.tcl\fR contains a minimal HTTP \f(CRGET\fR example. It
performs a simple request, stores the response body in a Tcl variable, and
prints both the HTTP response code and the size of the returned document.
.PP
If the request succeeds, \f(CRrc\fR is \f(CR0\fR, \f(CRresponsecode\fR is \f(CR200\fR, and \f(CRbody\fR
contains the HTML document returned by the server.
.SH AUTHORS
.LP
Andres Garcia Garcia
.PP
Massimo Manghi
.SH SEE ALSO
.LP
curl, The art of HTTP scripting (at \c
.UR http://curl.haxx.se)
.UE \c
, RFC 2396,
