.\" -*- mode: troff; coding: utf-8 -*-
.TH "TclCurl" "n" "12 April 2026" "TclCurl 8.0.1" "TclCurl Easy Interface"
.SH NAME
.LP
TclCurl: - get  a  URL with FTP, FTPS, HTTP, HTTPS, SCP, SFTP, TFTP, TELNET,
DICT, FILE, LDAP, LDAPS, IMAP, IMAPS, POP, POP3, SMTP, SMTPS and gopher syntax.
.SH SYNOPSIS
.LP
.EX
curl::init
.EE
.LP
.EX
curlHandle  configure  ?options?
.EE
.LP
.EX
curlHandle  perform
.EE
.LP
.EX
curlHandle  getinfo  curlinfo_option
.EE
.LP
.EX
curlhandle  cleanup
.EE
.LP
.EX
curlhandle  reset
.EE
.LP
.EX
curlHandle  duphandle
.EE
.LP
.EX
curlHandle  pause
.EE
.LP
.EX
curlHandle  resume
.EE
.LP
.EX
curl::transfer  ?options?
.EE
.LP
.EX
curl::version
.EE
.LP
.EX
curl::escape  url
.EE
.LP
.EX
curl::unescape  url
.EE
.LP
.EX
curl::curlConfig  option
.EE
.LP
.EX
curl::versioninfo  option
.EE
.LP
.EX
curl::easystrerror  errorCode
.EE
.SH DESCRIPTION
.LP
The TclCurl extension gives Tcl programmers access to the libcurl library
written by \fBDaniel Stenberg\fR, with it you can download urls, upload them and
many other neat tricks, for more information check \c
.UR http://curl.haxx.se
.UE
.SH curl::init
.LP
This procedure must be the first one to call, it returns a curlHandle that you
need to use to invoke TclCurl procedures. The init calls intializes curl and
this call MUST have a corresponding call to cleanup when the operation is
completed. You should perform all your sequential file transfers using the same
curlHandle. This enables TclCurl to use persistent connections when possible.
.PP
\fBRETURN VALUE\fR
.PP
curlHandle to use.
.SH curlHandle configure ?options?
.LP
\fBconfigure\fR
.PP
is called to set the options for the transfer. Most operations in TclCurl have
default actions, and by using the appropriate options you can make them behave
differently (as documented). All options are set with the \fIoption\fR followed by
a parameter.
.PP
\fBNotes:\fR
.PP
the options set with this procedure are valid for the forthcoming data
transfers that are performed when you invoke perform
.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 return code from the \f(CRcurl::init\fR call.
.PP
\fBOPTIONS\fR
.SH Behaviour options
.TP 3
-verbose
Set the parameter to 1 to get the library to display a lot of verbose
information about its operations. Very useful for libcurl and/or protocol
debugging and understanding.
.IP
You hardly ever want this set in production use, you will almost always
want this when you debug/report problems. Another neat option for debugging
is
.IP
\fB-debugproc\fR
.TP 3
-header
A 1 tells the extension to include the headers in the body output. This is
only relevant for protocols that actually have headers preceding the data
(like HTTP).
.TP 3
-noprogress
A 1 tells the extension to turn on the progress meter completely. It will
also prevent the \fIprogessproc\fR from getting called.
.TP 3
-nosignal
A 1 tells TclCurl not use any functions that install signal handlers or any
functions that cause signals to be sent to the process. This option is
mainly here to allow multi-threaded unix applications to still set/use all
timeout options etc, without risking getting signals.
.IP
If this option is set and libcurl has been built with the standard name
resolver, timeouts will not occur while the name resolve takes place.
Consider building libcurl with c-ares support to enable asynchronous DNS
lookups, which enables nice timeouts for name resolves without signals.
.IP
Setting \fInosignal\fR to 1 makes libcurl NOT ask the system to ignore SIGPIPE
signals, which otherwise are sent by the system when trying to send data to
a socket which is closed in the other end. libcurl makes an effort to never
cause such SIGPIPEs to trigger, but some operating systems have no way to
avoid them and even on those that have there are some corner cases when
they may still happen, contrary to our desire. In addition, using \fIntlm_Wb\fR
authentication could cause a SIGCHLD signal to be raised.
.TP 3
-wildcard
Set this option to 1 if you want to transfer multiple files according to a
file name pattern. The pattern can be specified as part of the \fB-url\fR
option, using an fnmatch-like pattern (Shell Pattern Matching) in the last
part of URL (file name).
.IP
By default, TclCurl uses its internal wildcard matching implementation. You
can provide your own matching function by the \fB-fnmatchproc\fR option.
.IP
This feature is only supported by the FTP download for now.
.IP
A brief introduction of its syntax follows:
.RS
.IP "\(bu" 3
* - ASTERISK
.RE
.IP
.UR ftp://example.com/some/path/***.txt**
.UE
(for all txt\(cqs from the root
directory)
- ? - QUESTION MARK
.IP
Question mark matches any (exactly one) character.
.IP
.UR ftp://example.com/some/path/**photo?.jpeg**
.UE
- [ - 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
.UR ftp://example.com/some/path/**[a-z[:upper:]%5C%5C%5C%5C].jpeg**
.UE
.SH Callback options
.TP 3
-writeproc
Use it to set a Tcl procedure that will be invoked by TclCurl as soon as
there is received data that needs to be saved. The procedure will receive a
single parameter with the data to be saved.
.IP
NOTE: you will be passed as much data as possible in all invokes, but you
cannot possibly make any assumptions. It may be nothing if the file is
empty or it may be thousands of bytes.
.TP 3
-file
File in which the transfered data will be saved.
.TP 3
-readproc
Sets a Tcl procedure to be called by TclCurl as soon as it needs to read
data in order to send it to the peer. The procedure has to take one
parameter, which will contain the maximun numbers of bytes to read. It
should return the actual number of bytes read, or \(oq0\(cq if you want to stop
the transfer.
.IP
If you stop the current transfer by returning 0 \(lqpre-maturely\(rq (i.e before
the server expected it, like when you\(cqve said you will upload N bytes and
you upload less than N bytes), you may experience that the server \(lqhangs\(rq
waiting for the rest of the data that won\(cqt come.
.IP
Bugs: when doing TFTP uploads, you must return the exact amount of data
that the callback wants, or it will be considered the final packet by the
server end and the transfer will end there.
.TP 3
-infile
File from which the data will be transfered.
.TP 3
-progressproc
Name of the Tcl procedure that will invoked by TclCurl  with a frequent
interval during operation (roughly once per second or sooner), no matter if
data is being transfered or not.  Unknown/unused argument values passed to
the callback will be set to zero (like if you only download data, the
upload size will remain 0), the prototype of the procedure must be:
.IP
\fBproc ProgressCallback {dltotal dlnow ultotal ulnow}\fR
.IP
In order to this option to work you have to set the \fBnoprogress\fR option
to \(oq0\(cq. Setting this option to the empty string will restore 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
-writeheader
Pass a the file name to be used to write the header part of the received
data to. The headers are guaranteed to be written one-by-one to this file
and only complete lines are written. Parsing headers should be easy enough
using this.
.IP
See also the \fB-headervar\fR option to get the headers into an array.
.TP 3
-debugproc
Name of the procedure that will receive the debug data produced by the
\fB-verbose\fR option, it should match the following prototype:
.IP
\fBdebugProc {infoType data}\fR
.IP
where \fBinfoType\fR specifies what kind of information it is (0 text, 1
incoming header, 2 outgoing header, 3 incoming data, 4 outgoing data, 5
incoming SSL data, 6 outgoing SSL data).
.TP 3
-chunkbgnproc
Name of the procedure that will be called before a file will be transfered
by ftp, it should match the following prototype:
.IP
\fBChunkBgnProc {remains}\fR
.IP
Where remains is the number of files left to be transfered (or skipped)
.IP
This callback makes sense only when using the \fB-wildcard\fR option.
.TP 3
-chunkbgnvar
Name of the variable in the global scope that will contain the data of the
file about to be transfered. If you don\(cqt use this option \(oq::fileData\(cq will
be used.
.IP
The available data is: filename, filetype (file, directory, symlink, device
block, device char, named pipe, socket, door or error if it couldn\(cqt be
identified), time, perm, uid, gid, size, hardlinks and flags.
.TP 3
-chunkendproc
Name of the procedure that will be called after a file is transfered (or
skipped) by ftp, it should match the following prototype:
.IP
\fBChunkEndProc {}\fR
.IP
It should return \(oq0\(cq if everyhting is fine and \(oq1\(cq if some error occurred.
.TP 3
-fnmatchProc
Name of the procedure that will be called instead of the internal wildcard
matching function, it should match the following prototype:
.IP
\fBFnMatchProc {pattern string}\fR
.IP
Returns \(oq0\(cq if it matches, \(oq1\(cq if it doesn\(cqt.
.SH Error Options
.TP 3
-errorbuffer
Pass a variable name where TclCurl may store human readable error messages
in. This may be more helpful than just the return code from the command.
.TP 3
-stderr
Pass a file name as parameter. This is the stream to use internally instead
of stderr when reporting errors.
.TP 3
-failonerror
A 1 parameter tells the extension to fail silently if the HTTP code
returned is equal or larger than 400. The default action would be to return
the page normally, ignoring that code.
.IP
This method is not fail-safe and there are occasions where non-successful
response codes will slip through, especially when authentication is
involved (response codes 401 and 407).
.IP
You might get some amounts of headers transferred before this situation is
detected, like for when a \(lq100-continue\(rq is received as a response to a
POST/PUT and a 401 or 407 is received immediately afterwards.
.SH Network options
.TP 3
-url
The actual URL to deal with.
.IP
If the given URL lacks the protocol part (\(lq or \(lqftp://\(rq etc), it
will attempt to guess which protocol to use based on the given host name.
If the given protocol of the set URL is not supported, TclCurl will return
the \fBunsupported protocol\fR error when you call \fBperform\fR. Use
\fBcurl::versioninfo\fR for detailed info on which protocols are supported.
.IP
Starting with version 7.22.0, the fragment part of the URI will not be send
as part of the path, which was the case previously.
.IP
\fBNOTE\fR: this is the one option required to be set before \fBperform\fR is
called.
.TP 3
-protocols
Pass a list in lowecase of protocols to limit what protocols TclCurl may
use in the transfer. This allows you to have a TclCurl built to support a
wide range of protocols but still limit specific transfers to only be
allowed to use a subset of them.
.IP
Accepted protocols are \(oqhttp\(cq, \(oqhttps\(cq, \(oqftp\(cq, \(oqftps\(cq, \(oqscp\(cq, \(oqsftp\(cq,
\(oqtelnet\(cq, \(oqldap\(cq, \(oqldaps\(cq, \(oqdict\(cq, \(oqfile\(cq,\(cqtftp\(cq, \(oqimap\(cq, \(oqimaps\(cq, \(oqpop\(cq,
\(oqpop3\(cq, \(oqsmtp\(cq, \(oqsmtps\(cq, \(oqgopher\(cq and \(oqall\(cq.
.TP 3
-redirprotocols
Pass a list in lowercase of accepted protocols to limit what protocols
TclCurl may use in a transfer that it follows to in a redirect when
\fB-followlocation\fR is enabled. This allows you to limit specific transfers
to only be allowed to use a subset of protocols in redirections.
.IP
By default TclCurl will allow all protocols except for FILE and SCP. This
is a difference compared to pre-7.19.4 versions which unconditionally would
follow to all protocols supported.
.TP 3
-proxy
If you need to use a http proxy to access the outside world, set the proxy
string with this option. To specify port number in this string, append
:[port] to the end of the host name. The proxy string may be prefixed with
[protocol]:// since any such prefix will be ignored.
.IP
When you tell the extension to use a HTTP proxy, TclCurl will transparently
convert operations to HTTP even if you specify a FTP URL etc. This may have
an impact on what other features of the library you can use, such as
\fBquote\fR and similar FTP specifics that will not work unless you tunnel
through the HTTP proxy. Such tunneling is activated with \fBproxytunnel\fR.
.IP
TclCurl respects the environment variables http\fIproxy, ftp\fRproxy, all_proxy
etc, if any of those are set. The use of this option does however override
any possibly set environment variables.
.IP
Setting the proxy string to \(lq\(lq (an empty string) will explicitly disable
the use of a proxy, even if there is an environment variable set for it.
.IP
The proxy host string can be specified the exact same way as the proxy
environment variables, include protocol prefix (\c
.UR http://)
.UE
and embedded
user + password.
.IP
Since 7.22.0, the proxy string may be specified with a protocol:// prefix
to specify alternative proxy protocols. Use socks4://, socks4a://,
socks5:// or socks5h:// (the last one to enable socks5 and asking the proxy
to do the resolving) to request the specific SOCKS version to be used. No
protocol specified, http:// and all others will be treated as HTTP proxies.
.TP 3
-proxyport
Use this option to set the proxy port to use unless it is specified in the
proxy string by \fB-proxy\fR. If not specified, TclCurl will default to using
port 1080 for proxies.
.TP 3
-proxytype
Pass the type of  the  proxy. Available options are \(oqhttp\(cq, \(oqhttp1.0\(cq,
\(oqsocks4\(cq, \(oqsocks4a\(cq, \(oqsocks5\(cq and \(oqsocks5h\(cq, with the HTTP one being the
default.
.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 \(lqregular\(rq HTTP
requests is instead controled with \fIhttpversion\fR.
.TP 3
-noproxy
Pass a string, a comma-separated list of hosts which do not use a proxy, if
one is specified. The only wildcard is a single * character, which matches
all hosts, and effectively disables the proxy. Each name in this list is
matched as either a domain which contains the hostname, or the hostname
itself. For example, local.com would match local.com, local.com:80, and
.UR http://www.local.com
.UE \c
, but not \c
.UR http://www.notlocal.com
.UE \c
\&.
.TP 3
-httpproxytunnel
Set the parameter to 1 to get the extension to tunnel all non-HTTP
operations through the given HTTP proxy. Do note that there is a big
difference between using a proxy and tunneling through it. If you don\(cqt
know what this means, you probably don\(cqt want this tunnel option.
.TP 3
-socks5gssapiservice
Pass the name of the service. The default service name for a SOCKS5 server
is rcmd/server-fqdn. This option allows you to change it.
.TP 3
-socks5gssapinec
Pass a 1 to enable or 0 to disable. As part of the gssapi negotiation a
protection mode is negotiated. The rfc1961 says in section 4.3/4.4 it
should be protected, but the NEC reference implementation does not. If
enabled, this option allows the unprotected exchange of the protection mode
negotiation.
.TP 3
-interface
Pass the interface name to use as outgoing network interface. The name can
be an interface name, an IP address or a host name.
.TP 3
-localport
This sets the local port number of the socket used for connection. This can
be used in combination with \fB-interface\fR and you are recommended to use
\fBlocalportrange\fR as well when this is set. Valid port numbers are 1 -
65535.
.TP 3
-localportrange
This is the number of attempts TclCurl should do to find a working local
port number. It starts with the given \fB-localport\fR and adds one to the
number for each retry. Setting this value to 1 or below will make TclCurl
do only one try for each port number. Port numbers by nature are a scarce
resource that will be busy at times so setting this value to something too
low might cause unnecessary connection setup failures.
.TP 3
-dnscachetimeout
Pass the timeout in seconds. Name resolves will be kept in memory for this
number of seconds. Set to \(oq0\(cq to completely disable caching, or \(oq-1\(cq to
make the cached entries remain forever. By default, TclCurl caches this
info for 60 seconds.
.IP
The name resolve functions of various libc implementations don\(cqt re-read
name server information unless explicitly told so (for example, by calling
\fIres_init(3)\fR). This may cause TclCurl to keep using the older server even
if DHCP has updated the server info, and this may look like a DNS cache
issue.
.TP 3
-dnsuseglobalcache
If the value passed is 1, it tells TclCurl to use a global DNS cache that
will survive between curl handles creations and deletions. This is not
thread-safe as it uses a global varible. \fIThis option was deprecated in
libcurl v7.11.1 and removed by default in tclcurl build. See README.md
for instructions on how to re-enable this option\fR
.IP
\fBWARNING:\fR this option is considered obsolete. Stop using it. Switch over
to using the share interface instead! See \fItclcurl_share\fR.
.TP 3
-buffersize
Pass your preferred size for the receive buffer in TclCurl. The main point
of this would be that the write callback gets called more often and with
smaller chunks. This is just treated as a request, not an order. You cannot
be guaranteed to actually get the given size.
.TP 3
-port
Pass the number specifying what remote port to connect to, instead of the
one specified in the URL or the default port for the used protocol.
.TP 3
-tcpnodelay
Pass a number to specify whether the TCP_NODELAY option should be set or
cleared (1 = set, 0 = clear). The option is cleared by default. This will
have 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
-addressscope
Pass a number specifying the scope_id value to use when connecting to IPv6
link-local or site-local addresses.
.SH Names and Passwords options
.TP 3
-netrc
A 1 parameter tells the extension to scan your \fB\(ti/.netrc\fR file to find
user name and password for the remote site you are about to access. Do note
that TclCurl does not verify that the file has the correct properties set
(as the standard unix ftp client does), and that only machine name, user
name and password is taken into account (init macros and similar things are
not supported).
.IP
You can set it to the following values:
.RS
.TP 3
optional
The use of your \(ti/.netrc file is optional, and information in
the URL is to be preferred. The file will be scanned with the host and user
name (to find the password only) or with the host only, to find the first
user name and password after that machine, which ever information is not
specified in the URL.
.RE
.IP
Undefined values of the option will have this effect.
.RS
.TP 3
ignored
The extension will ignore the file and use only the information
in the URL. This is the default.
.TP 3
required
This value tells the library that use of the file is required,
to ignore the information in the URL, and to search the file with the host
only.
.RE
.TP 3
-netrcfile
Pass a string containing the full path name to the file you want to use as
\&.netrc file. For the option to work, you have to set the \fBnetrc\fR option
to \fBrequired\fR. If this option is omitted, and \fBnetrc\fR is set, TclCurl
will attempt to find the a .netrc file in the current user\(cqs home
directory.
.TP 3
-userpwd
Pass a string as parameter, which should be [username]:[password] to use
for the connection. Use \fB-httpauth\fR to decide authentication method.
.IP
When using NTLM, you can set domain by prepending it to the user name and
separating the domain and name with a forward (/) or backward slash (\e).
Like this: \(lqdomain/user:password\(rq or \(lqdomain\euser:password\(rq. Some HTTP
servers (on Windows) support this style even 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
-proxyuserpwd
Pass a string as parameter, which should be [username]:[password] to use
for the connection to the HTTP proxy.
.TP 3
-username
Pass a string with the user name to use for the transfer. It sets the user
name to be used in protocol authentication. You should not use this option
together with the (older) \fB-userpwd\fR option.
.IP
In order to specify the password to be used in conjunction with the user
name use the \fB-password\fR option.
.TP 3
-password
Pass a string with the password to use for the transfer.
.IP
It should be used in conjunction with the \fB-username\fR option.
.TP 3
-proxyusername
Pass a string with the user name to use for the transfer while connecting
to Proxy.
.IP
It should be used in same way as the \fB-proxyuserpwd\fR is used, except that
it allows the username to contain a colon, like in the following example:
\(lqsip:\c
.MT user@example.com
.ME \c
\(rq.
.IP
Note the \fB-proxyusername\fR option is an alternative way to set the user
name while connecting to Proxy. It doesn\(cqt make sense to use them together.
.TP 3
-proxypassword
Pass a string with the password to use for the transfer while connecting to
Proxy. It is meant to use together with \fB-proxyusername\fR.
.TP 3
-httpauth
Set to the authentication method you want, the available ones are:
.RS
.TP 3
basic
HTTP Basic authentication. This is the default choice, and the
only method that is in widespread use and supported virtually everywhere.
It sends the user name and password over the network in plain text, easily
captured by others.
.TP 3
digest
HTTP Digest authentication. Digest authentication is a more
secure way to do authentication over public networks than the regular
old-fashioned Basic method.
.TP 3
digestie
HTTP Digest authentication with an IE flavor. TclCurl will use
a special \(lqquirk\(rq that IE is known to have used before version 7 and that
some servers require the client to use.
.TP 3
gssnegotiate
HTTP GSS-Negotiate authentication. The GSS-Negotiate
method, also known as plain \(lqNegotiate\(rq,was designed by Microsoft and is
used in their web applications. It is primarily meant as a support for
Kerberos5 authentication but may be also used along with another
authentication methods.
.TP 3
ntlm
HTTP NTLM authentication. A proprietary protocol invented and used
by Microsoft. It uses a challenge-response and hash concept similar to
Digest, to prevent the password from being eavesdropped.
.TP 3
ntlmwb
NTLM delegating to winbind helper. Authentication is performed
by a separate binary application that is executed when needed. The name of
the application is specified at libcurl\(cqs compile time but is typically
/usr/bin/ntlm_auth.
.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
any
TclCurl will automatically select the one it finds most secure.
.TP 3
anysafe
It may use anything but basic, TclCurl will automatically
select the one it finds most secure.
.RE
.TP 3
-tlsauthtype
Use it to tell TclCurl which authentication method(s) you want it to use
for TLS authentication.
.RS
.TP 3
tlsauthsrp
TLS-SRP authentication. Secure Remote Password
authentication for TLS is defined in RFC 5054 and provides mutual
authentication if both sides have a shared secret. To use TLS-SRP, you must
also set the \fB-tlsauthusername\fR and \fB-tlsauthpassword\fR options.
.RE
.IP
You need to build libcurl with GnuTLS or OpenSSL with TLS-SRP support for
this to work.
.TP 3
-tlsauthusername
Pass a string with the username to use for the TLS authentication method
specified with the \fB-tlsauthtype\fR option. Requires that the
\fB-tlsauthpassword\fR option also be set.
.TP 3
-tlsauthpassword
Pass a string with the password to use for the TLS authentication method
specified with the \fB-tlsauthtype\fR option. Requires that the
\fB-tlsauthusername\fR option also be set.
.TP 3
-proxyauth
Use it to tell TclCurl which authentication method(s) you want it to use
for your proxy authentication. Note that for some methods, this will induce
an extra network round-trip. Set the actual name and password with the
\fBproxyuserpwd\fR option.
.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
-autoreferer
Pass an 1 parameter to enable this. When enabled, TclCurl will
automatically set the Referer: field in requests where it follows a
Location: redirect.
.TP 3
-encoding
Sets the contents of the Accept-Encoding: header sent in an HTTP request,
and enables decoding of a response when a Content-Encoding: header is
received.  Three encodings are supported: \fIidentity\fR, which does nothing,
\fIdeflate\fR which requests the server to compress its response using the zlib
algorithm, and \fIgzip\fR which requests the gzip algorithm.  Use \fIall\fR to send
an Accept-Encoding: header containing all supported encodings.
.IP
This is a request, not an order; the server may or may not do it.  This
option must be set or else any unsolicited encoding done by the server is
ignored. See the special file lib/README.encoding in libcurl docs for
details.
.TP 3
-transferencoding
Adds a request for compressed Transfer Encoding in the outgoing HTTP
request. If the server supports this and so desires, it can respond with
the HTTP response sent using a compressed Transfer-Encoding that will be
automatically uncompressed by TclCurl on receival.
.IP
Transfer-Encoding differs slightly from the Content-Encoding you ask for
with \fB-encoding\fR in that a Transfer-Encoding is strictly meant to be for
the transfer and thus MUST be decoded before the data arrives in the
client. Traditionally, Transfer-Encoding has been much less used and
supported by both HTTP clients and HTTP servers.
.TP 3
-followlocation
An 1 tells the library to follow any
.IP
\fBLocation: header\fR
.IP
that the server sends as part of a HTTP header.
.IP
This means that the extension will re-send the  same request on the new
location and follow new \fBLocation: headers\fR all the way until no more
such headers are returned. \fB-maxredirs\fR can be used to limit the number
of redirects TclCurl will follow.
.IP
Since 7.19.4, TclCurl can limit what protocols it will automatically
follow. The accepted protocols are set with \fB-redirprotocols\fR and it
excludes the FILE protocol by default.
.TP 3
-unrestrictedauth
An 1 parameter tells the extension it can continue to  send authentication
(user+password) when following locations, even when hostname changed. Note
that  this is  meaningful  only  when setting \fB-followlocation\fR.
.TP 3
-maxredirs
Sets the redirection limit. If that many redirections have been followed,
the next redirect will cause an error. This option only makes sense if the
\fB-followlocation\fR option is used at the same time. Setting the limit to 0
will make libcurl refuse any redirect. Set it to -1 for an infinite number
of redirects (which is the default)
.TP 3
-postredir
Controls how TclCurl acts on redirects after POSTs that get a 301, 302 or
303 response back. A \(lq301\(rq parameter tells TclCurl to keep POST requests as
POST when following a 301 redirect. Passing a \(lq302\(rq makes TclCurl maintain
the request method after a 302 redirect, while \(lq303\(rq does the same for a
303 redirect. \(lqall\(rq is a convenience string that activates all three
behaviours.
.IP
The non-RFC behaviour is ubiquitous in web browsers, so the extension does
the 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 setting \fB-followlocation\fR
.IP
The legacy alias \fB-post301\fR is accepted for compatibility and uses the
same values.
.TP 3
-put
An 1 parameter tells the extension to use HTTP PUT a file. The file to put
must be set with \fB-infile\fR and \fB-infilesize\fR.
.IP
This option is deprecated starting with version 0.12.1, you should 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
-post
An 1 parameter tells the library to do a regular HTTP post. This is a
normal application/x-www-form-urlencoded kind, which is the most commonly
used one by HTML forms. See the \fB-postfields\fR option for how to specify
the data to post and \fB-postfieldsize\fR about how to set the data 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 provide data
to POST using the \fB-readproc\fR options.
.IP
You can override the default POST Content-Type: header by setting your own
with \fB-httpheader\fR.
.IP
Using POST 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 POST to a HTTP 1.1 server, you can send data without knowing the
size before starting the POST 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 in the
request.
.IP
When setting \fBpost\fR to an 1 value, it will automatically set \fBnobody\fR
to 0.
.IP
NOTE: if you have issued a POST request and want to make a HEAD or GET
instead, you must explicitly pick the new request type using \fB-nobody\fR or
\fB-httpget\fR or similar.
.TP 3
-postfields
Pass a string as parameter, which should be the full data to post in a HTTP
POST operation. You must make sure that the data is formatted the way you
want the server to receive it. TclCurl will not convert or encode it for
you. Most web servers will assume this data to be url-encoded.
.IP
This is a normal application/x-www-form-urlencoded  kind, 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, as simply setting \fB-postfields\fR to NULL or \(lq\(lq just
effectively disables the sending of the specified string. TclCurl will
instead assume that the POST data will be sent using the read callback!
.IP
Using POST 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
\fBNote\fR: to make multipart/formdata posts (aka rfc1867-posts), check out
\fB-httppost\fR option.
.TP 3
-postfieldsize
If you want to post data to the server without letting TclCurl do a
strlen() to measure the data size, this option must be used. Also, when
this option is used, you can post fully binary data which otherwise is
likely to fail. If this size is set to zero, the library will use strlen()
to get the data size.
.TP 3
-httppost
Tells TclCurl you want a multipart/formdata HTTP POST to be made and you
instruct what data to pass on to the server through a \fBTcl list\fR.
.IP
\fBThis is the only case where the data is reset after a transfer.\fR
.IP
First, there are some basics you need to understand about
multipart/formdata posts. Each part consists of at least a \fBNAME\fR and a
\fBCONTENTS\fR part. If the part is made for file upload, there are also a
stored \fBCONTENT-TYPE\fR and a \fBFILENAME\fR. Below, we\(cqll discuss which
options set these properties in the parts you want to add to your post.
.IP
The list must contain a \fB\(oqname\(cq\fR tag with the name of the section
followed by a string with the name, there are three tags to indicate the
value of the section: \fB\(oqvalue\(cq\fR followed by a string with the data to
post, \fB\(oqfile\(cq\fR followed by the name of the file to post and
\fB\(oqcontenttype\(cq\fR with the type of the data (text/plain, image/jpg, \[u2026]),
you can also indicate a \fIfalse\fR file name with \fB\(oqfilename\(cq\fR, this is
useful in case the server checks if the given file name is valid, for
example, by testing if it starts with \(oqc:\e\(cq as any real file name does or
if you want to include the full path of the file to post. You can also post
the content of a variable as if it were a file with the options
\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 the contents as data.
.IP
Should you need to specify extra headers for the form POST section, use
\fB\(oqcontentheader\fR\(cq followed by a list with the headers to post.
.IP
Please see \(oqhttpPost.tcl\(cq and \(oqhttpBufferPost.tcl\(cq for examples.
.IP
If TclCurl can\(cqt set the data to post an error will be returned:
.RS
.TP 3
1
If the memory allocation fails.
.TP 3
2
If one option is given twice for one form.
.TP 3
3
If an empty string was given.
.TP 3
4
If an unknown option was used.
.TP 3
5
If the some form info is not complete (or error)
.TP 3
6
If an illegal option is used in an array.
.TP 3
7
TclCurl has no http support.
.RE
.TP 3
-referer
Pass a string as parameter. It will be used to set the \fBreferer\fR header
in the http request sent to the remote server. This can be used to fool
servers or scripts. You can also set any custom header with
\fB-httpheader\fR.
.TP 3
-useragent
Pass a string as parameter. It will be used to set the \fBuser-agent:\fR
header in the http request sent to the remote server. This can be used to
fool servers or scripts. You can also set any custom header with
\fB-httpheader\fR.
.TP 3
-httpheader
Pass a \fBlist\fR with the HTTP headers to pass to the server in your
request. If you add a header that is otherwise generated and used by
TclCurl internally, your added one will be used instead. If you add a
header with no contents as in \(oqAccept:\(cq, the internally used header will
just get disabled. Thus, using this option you can add new headers, replace
and remove internal headers.
.IP
The headers included in the linked list must not be CRLF-terminated,
because TclCurl adds CRLF after each header item. Failure to comply with
this will result in strange bugs because the server will most likely ignore
part of the headers you specified.
.IP
The first line in a request (containing the method, usually a GET or POST)
is not a header and cannot be replaced using this option. Only the lines
following the request-line are headers. Adding this method line in this
list of headers will only cause your request to send an invalid header.
.IP
\fBNOTE\fR: The most commonly replaced headers have \(lqshortcuts\(rq in the
options: \fBcookie\fR, \fBuseragent\fR, and \fBreferer\fR.
.TP 3
-http200aliases
Pass a list of aliases to be treated as valid HTTP 200 responses. Some
servers respond with a custom header response line. For example, IceCast
servers respond with \(lqICY 200 OK\(rq. By including this string in your list of
aliases, the response will be treated as a valid HTTP header line such as
\(lqHTTP/1.0 200 OK\(rq.
.IP
\fBNOTE\fR:The alias itself is not parsed for any version strings. Before
version 7.16.3, TclCurl used the value set by option \fBhttpversion\fR, but
starting with 7.16.3 the protocol is assumed to match HTTP 1.0 when an
alias matched.
.TP 3
-cookie
Pass a string as parameter. It will be used to set a cookie in the http
request. The format of the string should be \(oq[NAME]=[CONTENTS];\(cq. Where
NAME is the cookie name and  CONTENTS is what the cookie should contain.
.IP
If  you  need  to  set mulitple cookies, you need to set them all using a
single option and thus you need to concatenate them all in one single
string. Set multiple cookies in one string like this: \(lqname1=content1;
name2=content2;\(rq etc.
.IP
This option sets the cookie header explicitly in the outgoing request(s).
If multiple requests are done due to authentication, followed redirections
or similar, they will all get this cookie passed on.
.IP
Using this option multiple times will only make the latest string override
the previous ones.
.TP 3
-cookiefile
Pass a string as parameter. It should contain the name of your file holding
cookie data. The cookie data may be in netscape cookie data format or just
regular HTTP-style headers dumped to a file.
.IP
Given an empty or non-existing file, this option will enable cookies for
this curl handle, making it understand and parse received cookies and then
use matching cookies in future requests.
.IP
If you use this option multiple times, you add more files to read.
.TP 3
-cookiejar
Pass a file name in which TclCurl will dump all internally known cookies
when \fBcurlHandle cleanup\fR is called. If no cookies are known, no file
will be created. Specify \(lq-\(rq to have the cookies written to stdout.
.IP
Using this option also enables cookies for this session, so if you, for
example, follow a location it will make matching cookies get sent
accordingly.
.IP
TclCurl will not and cannot report an error for  this. Using  \(oq\fBverbose\fR\(cq
will get a warning to display, but that is the only visible feedback you
get about this possibly lethal situation.
.TP 3
-cookiesession
Pass an 1 to mark this as a new cookie \(lqsession\(rq. It will force TclCurl to
ignore all cookies it is about to load that are \(lqsession cookies\(rq from the
previous session. By default, TclCurl always stores and loads all cookies,
independent of whether they are session cookies are not. Session cookies
are cookies without expiry date and they are meant to be alive and existing
for this \(lqsession\(rq only.
.TP 3
-cookielist
Pass a string with a cookie. The cookie can be either in Netscape / Mozilla
format or just regular HTTP-style header (Set-Cookie: \[u2026]) format. If the
cookie engine was not enabled it will be enabled.  Passing a magic string
\(lqALL\(rq will erase all known cookies while \(lqFLUSH\(rq will write all cookies
known by TclCurl to the file specified by \fB-cookiejar\fR.
.TP 3
-httpget
If set to 1 forces the HTTP request to get back to GET, usable if POST, PUT
or a custom request have been used previously with the same handle.
.IP
When setting \fBhttpget\fR to 1, \fBnobody\fR will automatically be set to 0.
.TP 3
-httpversion
Set to one of the values decribed below, they force TclCurl to use the
specific http versions. It should only be used if you really MUST do that
because of a silly remote server.
.RS
.TP 3
none
We do not care about what version the library uses. TclCurl will
use whatever it thinks fit.
.TP 3
1.0
Enforce HTTP 1.0 requests.
.TP 3
1.1
Enforce HTTP 1.1 requests.
.TP 3
2.0
Enforce HTTP version 2 requests.
.TP 3
2TLS
Enforce version 2 requests for HTTPS, version 1.1 for HTTP.
.TP 3
2\fIPRIOR\fRKNOWLEDGE
Enforce HTTP 2 requests without performing HTTP/1.1
Upgrade first.
.RE
.TP 3
-ignorecontentlength
Ignore the Content-Length header. This is useful for Apache 1.x (and
similar servers) which will report incorrect content length for files over
2 gigabytes. If this option is used, TclCurl will not be able to accurately
report progress, and will simply stop the download when the server ends the
connection.
.TP 3
-httpcontentdecoding
Set to zero to disable content decoding. If set to 1 it is enabled. Note
however that TclCurl has no default content decoding but requires you to
use \fBencoding\fR for that.
.TP 3
-httptransferencoding
Set to zero to disable transfer decoding, if set to 1 it is enabled
(default). TclCurl does chunked transfer decoding by default unless this
option is set to zero.
.SH SMTP options
.TP 3
-mailfrom
Pass a string to specify the sender address in a mail when sending an SMTP
mail with TclCurl.
.TP 3
-mailrcpt
Pass a list of recipients to pass to the server in your SMTP mail request.
.IP
Each recipient in SMTP lingo is specified with angle brackets (<>), but
should you not use an angle bracket as first letter, TclCurl will assume
you provide a single email address only and enclose that with angle
brackets for you.
.SH TFTP option
.TP 3
tftpblksize
Specify the block size to use for TFTP data transmission. Valid range as
per RFC 2348 is 8-65464 bytes. The default of 512 bytes will be used if
this option is not specified. The specified block size will only be used
pending support by the remote server. If the server does not return an
option acknowledgement or returns an option acknowledgement with no
blksize, the default of 512 bytes will be used.
.SH FTP options
.TP 3
-ftpport
Pass a string as parameter. It will be used to get the IP address to use
for the ftp PORT instruction. The PORT instruction tells the remote server
to connect to our specified IP address. The string may be a plain IP
address, a host name, a network interface name (under unix) or just a \(oq-\(cq
to let the library use your systems default IP address. Default FTP
operations are passive, and thus will not use PORT.
.IP
The address can be followed by a \(oq:\(cq to specify a port, optionally followed
by a \(oq-\(cq o specify a port range. If the port specified is 0, the operating
system will pick a free port. If a range is provided and all ports in the
range are not available, libcurl will report CURLE\fIFTP\fRPORT_FAILED for the
handle. Invalid port/range settings are ignored. IPv6 addresses followed by
a port or portrange have to be in brackets. IPv6 addresses without
port/range specifier can be in brackets.
.IP
Examples with specified ports:
.IP
eth0:0   192.168.1.2:32000-33000   curl.se:32123   [::1]:1234-4567
.IP
You disable PORT again and go back to using the passive version by setting
this option to an empty string.
.TP 3
-quote
Pass a \fBlist\fR list with the FTP or SFTP commands to pass to the server
prior to your ftp request. This will be done before any other FTP commands
are issued (even before the CWD command).If you do not want to transfer any
files, set \fBnobody\fR to \(oq1\(cq and \fBheader\fR to \(oq0\(cq.
.IP
Prefix the command with an asterisk (*) to make TclCurl continue even if
the command fails as by default TclCurl will stop.
.IP
Disable this operation again by setting an empty string to this option.
.IP
Keep in mind the commands to send must be \(oqraw\(cq ftp commands, for example,
to create a directory you need to send \fBmkd Test\fR, not \fBmkdir Test\fR.
.IP
Valid SFTP commands are: chgrp, chmod, chown, ln, mkdir, pwd, rename, rm,
rmdir and symlink.
.TP 3
-postquote
Pass a \fBlist\fR with the FTP commands to pass to the server after your ftp
transfer request. If you do not want to transfer any files, set \fBnobody\fR
to \(oq1\(cq and \fBheader\fR to \(oq0\(cq.
.TP 3
-prequote
Pass a \fBlist\fR of FTP or SFTP commands to pass to the server after the
transfer type is set.
.TP 3
-dirlistonly
A 1 tells the library to just list the names of files in a directory,
instead of doing a full directory listing that would include file sizes,
dates etc. It works with both FTP and SFTP urls.
.IP
This causes an FTP NLST command to be sent. Beware that some FTP servers
list only files in their response to NLST, they might not include
subdirectories and symbolic links.
.IP
Setting this option to 1 also implies a directory listing even if the URL
doesn\(cqt end with a slash, which otherwise is necessary.
.IP
Do NOT use this option if you also use \fB-wildcardmatch\fR as it will
effectively break that feature.
.TP 3
-append
A 1 parameter tells the extension to append to the remote file instead of
overwriting it. This is only useful when uploading to a ftp site.
.TP 3
-ftpusepret
Set to 1 to tell TclCurl to use the EPRT (and LPRT) command when doing
active FTP downloads (which is enabled by \(oq\fBftpport\fR\(cq). Using EPRT means
that it will first attempt to use EPRT and then LPRT before using PORT, if
you pass zero to this option, it will not try using EPRT or LPRT, only
plain PORT.
.TP 3
-ftpuseepvs
Set to one to tell TclCurl to use the EPSV command when doing passive FTP
downloads (which it always does by default). Using EPSV means that it will
first attempt to use EPSV before using PASV, but if you pass a zero to this
option, it will not try using EPSV, only plain PASV.
.TP 3
-ftpusepret
Set to one to tell TclCurl to send a PRET command before PASV (and EPSV).
Certain FTP servers, mainly drftpd, require this non-standard command for
directory listings as well as up and downloads in PASV mode. Has no effect
when using the active FTP transfers mode.
.TP 3
-ftpcreatemissingdirs
If set to 1, TclCurl will attempt to create any remote directory that it
fails to CWD into. CWD is the command that changes working directory.
.IP
This setting also applies to SFTP-connections. TclCurl will attempt to
create the remote directory if it can\(cqt obtain a handle to the
target-location. The creation will fail if a file of the same name as the
directory to create already exists or lack of permissions prevents
creation.
.IP
If set to 2, TclCurl will retry the CWD command again if the subsequent MKD
command fails. This is especially useful if you\(cqre doing many simultanoeus
connections against the same server and they all have this option enabled,
as then CWD may first fail but then another connection does MKD before this
connection and thus MKD fails but trying CWD works
.TP 3
-ftpresponsetimeout
Causes TclCurl to set a timeout period (in seconds) on the amount of time
that the server is allowed to take in order to generate a response message
for a command before the session is considered hung. Note that while
TclCurl is waiting for a response, this value overrides \fBtimeout\fR. It is
recommended that if used in conjunction with \fBtimeout\fR, you set it to a
value smaller than \fBtimeout\fR.
.TP 3
-ftpalternativetouser
Pass a string which will be used to authenticate if the usual FTP \(lqUSER
user\(rq and \(lqPASS password\(rq negotiation fails. This is currently only known
to be required when connecting to Tumbleweed\(cqs Secure Transport FTPS server
using client certificates for authentication.
.TP 3
-ftpskippasvip
If set to 1, it instructs TclCurl not to use the IP address the server
suggests in its 227-response to TclCurl\(cqs PASV command when TclCurl
connects the data connection. Instead TclCurl will re-use the same IP
address it already uses for the control connection. But it will use the
port number from the 227-response.
.IP
This option has no effect if PORT, EPRT or EPSV is used instead of PASV.
.TP 3
-ftpsslauth
Pass TclCurl one of the values from below, to alter how TclCurl issues
\(lqAUTH TLS\(rq or \(lqAUTH SSL\(rq when FTP over SSL is activated (see \fB-ftpssl\fR).
.IP
You may need this option because of servers like BSDFTPD-SSL from
.UR http://bsdftpd-ssl.sc.ru/
.UE
\(lqwhich won\(cqt work properly  when \(lqAUTH SSL\(rq is
issued (although the server responds fine and everything) but requires
\(lqAUTH TLS\(rq instead.
.RS
.TP 3
default
Allows TclCurl to decide.
.TP 3
ssl
Try \(lqAUTH SSL\(rq first, and only if that fails try \(lqAUTH TLS\(rq.
.TP 3
tls
Try \(lqAUTH TLS\(rq first, and only if that fails try \(lqAUTH SSL\(rq.
.RE
.TP 3
-ftpsslccc
Set it to make TclCurl use CCC (Clear Command Channel). It shuts down the
SSL/TLS layer after authenticating. The rest of the control channel
communication will be unencrypted. This allows NAT routers to follow the
FTP transaction. Possible values are:
.RS
.TP 3
none
Do not attempt to use CCC.
.TP 3
passive
Do not initiate the shutdown, wait for the server to do it. Do
not send a reply.
.TP 3
active
Initiate the shutdown and wait for a reply.
.RE
.TP 3
-ftpaccount
Pass string (or \(lq\(lq to disable). When an FTP server asks for \(lqaccount data\(rq
after user name and password has been provided, this data is sent off using
the ACCT command.
.TP 3
-ftpfilemethod
It allows three values:
.RS
.TP 3
multicwd
The default, TclCurl will do a single CWD operation for each
path part in the given URL. For deep hierarchies this means very many
commands. This is how RFC1738 says it should be done.
.TP 3
nocwd
No CWD at all is done, TclCurl will do SIZE, RETR, STOR, etc and
give a full path to the server.
.TP 3
singlecwd
Make one CWD with the full target directory and then operate
on the file \(lqnormally\(rq. This is somewhat more standards compliant than
\(oqnocwd\(cq but without the full penalty of \(oqmulticwd\(cq.
.RE
.SH Protocol options
.TP 3
-transfertext
A 1 tells the extension to use ASCII mode for ftp transfers, instead of the
default binary transfer. For win32 systems it does not set the stdout to
binary mode. This option can be usable when transferring text data between
systems with different views on certain characters, such as newlines or
similar.
.IP
\fBNOTE:\fR TclCurl does not do a complete ASCII conversion when doing ASCII
transfers over FTP. This is a known limitation/flaw that nobody has
rectified. TclCurl simply sets the mode to ascii and performs a standard
transfer.
.TP 3
-proxytransfermode
If set to 1, TclCurl sets the transfer mode (binary or ASCII) for FTP
transfers done via an HTTP proxy, by appending ;type=a or ;type=i to the
URL. Without this setting, or it being set to 0, the default,
\fB-transfertext\fR has no effect when doing FTP via a proxy. Beware that not
all proxies support this feature.
.TP 3
-crlf
If set to \(oq1\(cq, TclCurl converts Unix newlines to CRLF newlines on
transfers. Disable this option again by setting the value to \(oq0\(cq.
.TP 3
-range
Pass a string as parameter, which should contain the specified range you
want. It should be in the format \(lqX-Y\(rq , where X or Y may be left out. HTTP
transfers also support several intervals, separated with commas as in
\(lqX-Y,N-M\(rq Using this kind of multiple intervals will cause the HTTP server
to send the response document in pieces (using standard MIME separation
techniques).
.IP
Ranges only work on HTTP, FTP and FILE transfers.
.TP 3
-resumefrom
Pass the offset in number of bytes that you want the transfer to start
from. Set this option to 0 to make the transfer start from the beginning
(effectively disabling resume).
.IP
For FTP, set this option to -1 to make the transfer start from the end of
the target file (useful to continue an interrupted upload).
.IP
When doing uploads with FTP, the resume position is where in the
local/source file TclCurl should try to resume the upload from and it will
then append the source file to the remote target file.
.TP 3
-customrequest
Pass a string as parameter. It will be used instead of GET or HEAD when
doing the HTTP request. This is useful for doing DELETE or other more
obscure HTTP requests. Do not do this at will, make sure your server
supports the command first.
.IP
Note that TclCurl will still act and assume the keyword it would use if you
do not set your custom and it will act according to that. Thus, changing
this to a HEAD when TclCurl otherwise would do a GET might cause TclCurl to
act funny, and similar. To switch to a proper HEAD, use \fB-nobody\fR, to
switch to a proper POST, use \fB-post\fR or \fB-postfields\fR and so on.
.TP 3
-filetime
If you pass a 1, TclCurl will attempt to get the modification date of the
remote document in this operation. This requires that the remote server
sends the time or replies to a time querying command. The getinfo procedure
with the filetime argument can be used after a transfer to extract the
received time (if any).
.TP 3
-nobody
A 1 tells the library not to include the body-part in the output. This is
only relevant for protocols that have a separate header and body part. On
HTTP(S) servers, this will make TclCurl do a HEAD request.
.IP
To change request to GET, you should use \fBhttpget\fR. Change request to
POST with \fBpost\fR etc.
.TP 3
-infilesize
When uploading a file to a remote site, this option should be used to tell
TclCurl what the expected size of the infile is.
.IP
This option is mandatory for uploading using SCP.
.TP 3
-upload
A 1 tells the library to prepare for an upload. The \fB-infile\fR and
\fB-infilesize\fR options are also interesting 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
This defines how the \fBtimevalue\fR value is treated. You can set this
parameter to \fBifmodsince\fR or \fBifunmodsince\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
-timeout
Pass the maximum time in seconds that you allow the TclCurl transfer
operation to take. Do note that normally, name lookups may take a
considerable time and that limiting the operation to less than a few
minutes risks aborting perfectly normal operations. This option will cause
libcurl to use the SIGALRM to enable time-outing system calls.
.IP
In unix-like systems, this might cause signals to be used unless
\fB-nosignal\fR is used.
.TP 3
-timeoutms
Like \fBtimeout\fR but takes a number of milliseconds instead. If libcurl is
built to use the standard system name resolver, that part will still use
full-second resolution for timeouts.
.TP 3
-lowspeedlimit
Pass the speed in bytes per second that the transfer should be below during
\fBlowspeedtime\fR seconds for the extension to consider it too slow and
abort.
.TP 3
-lowspeedtime
Pass the time in seconds that the transfer should be below the
\fBlowspeedlimit\fR for the extension to consider it too slow and abort.
.TP 3
-maxsendspeed
Pass a speed in bytes per seconds. If an upload exceeds this speed on
cumulative average during the transfer, the transfer will pause to keep the
average rate less than or equal to the parameter value.  Defaults to
unlimited speed.
.TP 3
-maxrecvspeed
Pass a speed in bytes per second. If a download exceeds this speed on
cumulative average during the transfer, the transfer will pause to keep the
average rate less than or equal to the parameter value. Defaults to
unlimited speed.
.TP 3
-maxconnects
Sets the persistent connection cache size in all the protocols that support
persistent conecctions. The set amount will be the maximum amount of
simultaneous connections that TclCurl may cache in this easy handle.
Default is 5, and there isn\(cqt much point in changing this value unless you
are perfectly aware of how this work and changes TclCurl\(cqs behaviour.
.IP
When reaching the maximum limit, TclCurl closes the oldest connection in
the cache to prevent the number of open connections to increase.
.IP
\fBNote\fR: if you have already performed transfers with this curl handle,
setting a smaller \fBmaxconnects\fR than before may cause open connections to
unnecessarily get closed.
.IP
If you add this easy handle to a multi handle, this setting is not being
acknowledged, instead you must configure the multi handle its own
\fBmaxconnects\fR option.
.TP 3
-connecttimeout
Maximum time in seconds that you allow the connection to the server to
take.  This only limits the connection phase, once it has connected, this
option is of no more use. Set to zero to disable connection timeout (it
will then only timeout on the internal timeouts).
.IP
In unix-like systems, this might cause signals to be used unless
\fB-nosignal\fR is set.
.TP 3
-connecttimeoutms
Like \fBconnecttimeout\fR but takes a number of milliseconds instead. If
libcurl is built to use the standard system name resolver, that part will
still use full-second resolution for timeouts.
.TP 3
-ipresolve
Allows an application to select what kind of IP addresses to use when
resolving host names. This is only interesting when using host names that
resolve addresses using more than one version of IP. The allowed values
are:
.TP 3
whatever
Default, resolves addresses to all IP versions that your system allows.
.TP 3
v4
Resolve to ipv4 addresses.
.TP 3
v6
Resolve to ipv6 addresses.
.TP 3
-resolve
Pass a list of strings with host name resolve information to use for
requests with this handle.
.IP
Each single name resolve string should be written using the format
HOST:PORT:ADDRESS where HOST is the name TclCurl will try to resolve, PORT
is the port number of the service where TclCurl wants to connect to the
HOST and ADDRESS is the numerical IP address. If libcurl is built to
support IPv6, ADDRESS can be either IPv4 or IPv6 style addressing.
.IP
This option effectively pre-populates the DNS cache with entries for the
host+port pair so redirects and everything that operations against the
HOST+PORT will instead use your provided ADDRESS.
.IP
You can remove names from the DNS cache again, to stop providing these fake
resolves, by including a string in the linked list that uses the format
\(lq-HOST:PORT\(rq. The host name must be prefixed with a dash, and the host name
and port number must exactly match what was already added previously.
.TP 3
-usessl
Pass a one of the values from below to make TclCurl use your desired level
of SSL for the transfer. This is for enabling SSL/TLS when you use FTP,
SMTP, POP3, IMAP etc.
.IP
You can use ftps:// URLs to explicitly switch on SSL/TSL for the control
connection and the data connection.
.IP
Alternatively you can set the option to one of these values:
.TP 3
nope
Do not attempt to use SSL
.TP 3
try
Try using SSL, proceed anyway otherwise.
.TP 3
control
Use SSL for the control conecction or fail with \(lquse ssl failed\(rq (64).
.TP 3
all
Use SSL for all communication or fail with \(lquse ssl failed\(rq (64).
.SH SSL and security options
.TP 3
-sslcert
Pass a string as parameter. The string should be the file name of your
certificate. The default format is \(lqPEM\(rq and can be changed with
\fB-sslcerttype\fR.
.IP
With NSS this is the nickname of the certificate you wish to authenticate
with. If you want to use a file from the current directory, please precede
it with the \(lq./\(rq prefix, in order to avoid confusion with a nickname.
.TP 3
-sslcerttype
Pass a string as parameter. The string should be the format of your
certificate. Supported formats are \(lqPEM\(rq and \(lqDER\(rq.
.TP 3
-sslkey
Pass a pointer to a zero terminated string as parameter. The string should
be the file name of your private key. The default format is \(lqPEM\(rq and can
be changed with \fB-sslkeytype\fR.
.TP 3
-sslkeytype
Pass a pointer to a zero terminated string as parameter. The string should
be the format of your private key. Supported formats are \(lqPEM\(rq, \(lqDER\(rq and
\(lqENG\(rq
.IP
\fBNOTE:\fRThe format \(lqENG\(rq enables you to load the private key from a crypto
engine. in this case \fB-sslkey\fR is used as an identifier passed to the
engine. You have to set the crypto engine with \fB-sslengine\fR. The \(lqDER\(rq
format key file currently does not work because of a bug in OpenSSL.
.TP 3
-keypasswd
Pass a string as parameter. It will be used as the password required to use
the \fB-sslkey\fR or \fB-sshprivatekeyfile\fR private key.
.IP
You never need a pass phrase to load a certificate but you need one to load
you private key.
.IP
This option used to be known as \fB-sslkeypasswd\fR and \fB-sslcertpasswd\fR.
.TP 3
-sslengine
Pass a string as parameter. It will be used as the identifier for the
crypto engine you want to use for your private key.
.IP
\fBNOTE:\fRIf the crypto device cannot be loaded, an error will be returned.
.TP 3
-sslenginedefault
Pass a 1 to set the actual crypto engine as the default for (asymmetric)
crypto operations.
.IP
\fBNOTE:\fRIf the crypto device cannot be set, an error will be returned.
.TP 3
-sslversion
Use it to set what version of SSL/TLS to use. The available options are:
.TP 3
default
The default action. This will attempt to figure out the remote SSL protocol
version, i.e. either SSLv3 or TLSv1 (but not SSLv2, which became disabled
by default with 7.18.1).
.TP 3
tlsv1
Force TLSv1 or later
.TP 3
sslv2
Force SSLv2
.TP 3
sslv3
Force SSLv3
.TP 3
tlsv1_0
Force TLSv1.0 or later
.TP 3
tlsv1_1
Force TLSv1.1 or later
.TP 3
tlsv1_2
Force TLSv1.2 or later
.TP 3
tlsv1_3
Force TLSv1.3 or later
.TP 3
maxdefault
Use the maximum supported TLS version by libcurl or the default value from
the SSL library.
.TP 3
maxtlsv1_0
Define maximum supported TLS version as TLSv1.0
.TP 3
maxtlsv1_1
Define maximum supported TLS version as TLSv1.1
.TP 3
maxtlsv1_2
Define maximum supported TLS version as TLSv1.2
.TP 3
maxtlsv1_3
Define maximum supported TLS version as TLSv1.3
.TP 3
-sslverifypeer
This option determines whether TclCurl verifies the authenticity of the
peer\(cqs certificate. A 1 means it verifies; zero means it doesn\(cqt. The
default is 1.
.IP
When negotiating an SSL connection, the server sends a certificate
indicating its identity. TclCurl verifies whether the certificate is
authentic, i.e. that you can trust that the server is who the certificate
says it is. This trust is based on a chain of digital signatures, rooted in
certification authority (CA) certificates you supply.
.IP
TclCurl uses a default bundle of CA certificates that comes with libcurl
but you can specify alternate certificates with the \fB-cainfo\fR or the
\fB-capath\fR options.
.IP
When \fB-sslverifypeer\fR is nonzero, and the verification fails to prove
that the certificate is authentic, the connection fails. When the option is
zero, the peer certificate verification succeeds regardless.
.IP
Authenticating the certificate is not by itself very useful. You typically
want to ensure that the server, as authentically identified by its
certificate, is the server you mean to be talking to, use
\fB-sslverifyhost\fR to control that. The check that the host name in the
certificate is valid for the host name you\(cqre connecting to is done
independently of this option.
.TP 3
-cainfo
Pass a file naming holding the certificate to verify the peer with. This
only makes sense when used in combination with the \fB-sslverifypeer\fR
option, if it is set to zero \fB-cainfo\fR need not even indicate an
accessible file.
.IP
This option is by default set to the system path where libcurl\(cqs cacert
bundle is assumed to be stored, as established at build time.
.IP
When built against NSS this is the directory that the NSS certificate
database resides in.
.TP 3
-issuercert
Pass a string naming a file holding a CA certificate in PEM format. If the
option is set, an additional check against the peer certificate is
performed to verify the issuer is indeed the one associated with the
certificate provided by the option. This additional check is useful in
multi-level PKI where one need to enforce the peer certificate is from a
specific branch of the tree.
.IP
This option makes sense only when used in combination with the
\fB-sslverifypeer\fR option. Otherwise, the result of the check is not
considered as failure.
.TP 3
-capath
Pass the directory holding multiple CA certificates to verify the peer
with. If libcurl is built against OpenSSL, the certificate directory must
be prepared using the openssl c_rehash utility. This only makes sense when
used in combination with the  \fB-sslverifypeer\fR option, if it is set to
zero, \fB-capath\fR need not even indicate an accessible path.
.IP
This option apparently does not work in Windows due to some limitation in
openssl.
.IP
This option is OpenSSL-specific and does nothing if libcurl is built to use
GnuTLS. NSS-powered libcurl provides the option only for backward
compatibility.
.TP 3
-crlfile
Pass a string naming a file with the concatenation of CRL (in PEM format)
to use in the certificate validation that occurs during the SSL exchange.
.IP
When libcurl is built to use NSS or GnuTLS, there is no way to influence
the use of CRL passed to help in the verification process. When built with
OpenSSL support, X509\fIV\fRFLAG\fICRL\fRCHECK and X509\fIV\fRFLAG\fICRL\fRCHECK_ALL are
both set, requiring CRL check against all the elements of the certificate
chain if a CRL file is passed.
.IP
This option makes sense only when used in combination with the
\fB-sslverifypeer\fR option.
.IP
A specific error code (CURLE\fISSL\fRCRL_BADFILE) is defined with the option.
It is returned when the SSL exchange fails because the CRL file cannot be
loaded. A failure in certificate verification due to a revocation
information found in the CRL does not trigger this specific error.
.TP 3
-sslverifyhost
This option determines whether TclCurl verifies that the server claims to
be who you want it to be.
.IP
When negotiating an SSL connection, the server sends a certificate
indicating its identity.
.IP
When \fB-sslverifyhost\fR is set to 2, that certificate must indicate that
the server is the server to which you meant to connect, or the connection
fails.
.IP
TclCurl considers the server the intended one when the Common Name field or
a Subject Alternate Name field in the certificate matches the host name in
the URL to which you told Curl to connect.
.IP
When set to 1, the certificate must contain a Common Name field, but it
does not matter what name it says. (This is not ordinarily a useful
setting).
.IP
When the value is 0, the connection succeeds regardless of the names in the
certificate.
.IP
The default value for this option is 2.
.IP
This option controls the identity that the server \fIclaims\fR. The server
could be lying. To control lying, see \fB-sslverifypeer\fR. If libcurl is
built against NSS and \fB-verifypeer\fR is zero, \fB-verifyhost\fR is ignored.
.TP 3
-certinfo
Set to \(oq1\(cq to enable TclCurl\(cqs certificate chain info gatherer. With this
enabled, TclCurl (if built with OpenSSL) will extract lots of information
and data about the certificates in the certificate chain used in the SSL
connection. This data can then be to extracted after a transfer using the
\fBgetinfo\fR command and its option \fBcertinfo\fR.
.TP 3
-randomfile
Pass a file name. The file will be used to read from to seed the random
engine for SSL. The more random the specified file is, the more secure the
SSL connection becomes. \fIThis option was deprecated in libcurl v7.84 and
removed by default in tclcurl build. See README.md for instructions on
how to re-enable this option\fR
.TP 3
-egdsocket
Pass a path name to the Entropy Gathering Daemon socket. It will be used to
seed the random engine for SSL. \fIThis option was deprecated in libcurl v7.84
and removed by default in tclcurl build. See README.md for instructions on
how to re-enable this option\fR
.TP 3
-sslcypherlist
Pass a string holding the ciphers to use for the SSL connection. The list
must consists of one or more cipher strings separated by colons. Commas or
spaces are also acceptable separators but colons are normally used, , - and
.RS
.IP "\(bu" 3
can be used as operators.
.RE
.IP
For OpenSSL and GnuTLS valid examples of cipher lists include \(oqRC4-SHA\(cq,
\(oqSHA1+DES\(cq, \(oqTLSv1\(cq and \(oqDEFAULT\(cq. The default list is normally set when
you compile OpenSSL.
.IP
You will find more details about cipher lists on this URL:
.UR http://www.openssl.org/docs/apps/ciphers.html
.UE
.IP
For NSS valid examples of cipher lists include \(oqrsa\fIrc4\fR128\fImd5\(cq,
\(oqrsa\fRaes\fI128\fRsha\(cq, etc. With NSS you don\(cqt add/remove ciphers. If you use
this option then all known ciphers are disabled and only those passed in
are enabled.
.IP
You\(cqll find more details about the NSS cipher lists on this URL:
<\c
.UR http://directory.fedora.redhat.com/docs/mod_nss.html
.UE \c
>
.TP 3
-sslsessionidcache
Pass a 0 to disable TclCurl\(cqs use of SSL session-ID caching or a 1 to
enable it. By default all transfers are done using the cache. While nothing
ever should get hurt by attempting to reuse SSL session-IDs, there seem to
be broken SSL implementations in the wild that may require you to disable
this in order for you to succeed.
.TP 3
-krblevel
Set the kerberos security level for FTP, this also enables kerberos
awareness. This is a string, \(oqclear\(cq, \(oqsafe\(cq, \(oqconfidential\(cq or \(oqprivate\(cq.
If the string is set but does not match one of these, \(oqprivate\(cq will be
used. Set the string to NULL to disable kerberos4. Set the string to \(lq\(lq to
disable kerberos support for FTP.
.TP 3
-gssapidelegation
Set the option to \(oqflag\(cq to allow unconditional GSSAPI credential
delegation. The delegation is disabled by default since 7.21.7. Set the
parameter to \(oqpolicyflag\(cq to delegate only if the OK-AS-DELEGATE flag is
set in the service ticket in case this feature is supported by the GSSAPI
implementation and the definition of GSS\fIC\fRDELEG\fIPOLICY\fRFLAG was available
at compile-time.
.SH SSH options
.TP 3
-sshauthtypes
The allowed types are:
.RS
.TP 3
publickey
Use public key authentication.
.TP 3
password
Use password authentication.
.TP 3
host
Use host-based authentication.
.TP 3
keyboard
Use keyboard-interactive authentication.
.TP 3
any
To let TclCurl pick one
.RE
.TP 3
-sshhostpublickeymd5
Pass a string containing 32 hexadecimal digits. The string should be the
128 bit MD5 cheksum of the remote host public key, and TclCurl will reject
the connection to the host unless the md5sums match. This option is only
for SCP and SFTP transfers.
.TP 3
-publickeyfile
Pass the file name for your public key. If not used, TclCurl defaults to
using \fB$HOME/.ssh/id_dsa.pub\fR. HOME environment variable is set, and just
\fBid_dsa\fR in the current directory if not.
.TP 3
-privatekeyfile
Pass the file name for your private key. If not used, TclCurl defaults to
using \fB$HOME/.ssh/id_dsa.pub\fR. HOME environment variable is set, and just
\fBid_dsa\fR in the current directory if not. If the file is
password-protected, set the password with \fB-keypasswd\fR.
.TP 3
-sshknownhosts
Pass a string holding the file name of the known\fIhost file to use. The
known\fRhosts file should use the OpenSSH file format as supported by
libssh2. If this file is specified, TclCurl will only accept connections
with hosts that are known and present in that file, with a matching public
key. Use \fB-sshkeyproc\fR to alter the default behavior on host and key
(mis)matching.
.TP 3
-sshkeyproc
Pass a the name of the procedure that will be called when the known_host
matching has been done, to allow the application to act and decide for
TclCurl how to proceed. The callback will only be called if \fB-knownhosts\fR
is also set.
.IP
It gets passed a list with three elements, the first one is a list with the
type of the key from the known_hosts file and the key itself, the second is
another list with the type of the key from the remote site and the key
itslef, the third tells you what TclCurl thinks about the matching status.
.IP
The known key types are: \(lqrsa\(rq, \(lqrsa1\(rq and \(lqdss\(rq, in any other case
\(lqunknown\(rq is given.
.IP
TclCurl opinion about how they match may be: \(lqmatch\(rq, \(lqmismatch\(rq, \(lqmissing\(rq
or \(lqerror\(rq.
.IP
The procedure must return:
.RS
.TP 3
0
The host+key is accepted and TclCurl will append it to the
known\fIhosts file before continuing with the connection. This will also add
the host+key combo to the known\fRhost pool kept in memory if it wasn\(cqt
already present there. The adding of data to the file is done by completely
replacing the file with a new copy, so the permissions of the file must
allow this.
.TP 3
1
The host+key is accepted, TclCurl will continue with the connection.
This will also add the host+key combo to the known_host pool kept in memory
if it wasn\(cqt already present there.
.TP 3
2
The host+key is rejected. TclCurl will close the connection.
.TP 3
3
The host+key is rejected, but the SSH connection is asked to be kept
alive. This feature could be used when the app wants to somehow return back
and act on the host+key situation and then retry without needing the
overhead of setting it up from scratch again.
.RE
.IP
Any other value will cause the connection to be closed.
.SH Other options
.TP 3
-headervar
Name of the Tcl array variable where TclCurl will store the headers
returned by the server.
.TP 3
-bodyvar
Name of the Tcl variable where TclCurl will store the file requested, the
file may contain text or binary data.
.TP 3
-canceltransvar
Name of a Tcl variable, in case you have defined a procedure to call with
\fB-progressproc\fR setting this variable to \(oq1\(cq will cancel the transfer.
.TP 3
-command
Executes the given command after the transfer is done, since it only works
with blocking transfers, it is pretty much useless.
.TP 3
-share
Pass a share handle as a parameter. The share handle must have been created
by a previous call to \fBcurl::shareinit\fR. Setting this option, will make
this handle use the data from the shared handle instead of keeping the data
to itself. See \fItclcurl_share\fR for details.
.TP 3
-newfileperms
Pass a number as a parameter, containing the value of the permissions that
will be assigned to newly created files on the remote server. The default
value is 0644, but any valid value can be used. The only protocols that can
use this are sftp://, scp:// and file://.
.TP 3
-newdirectoryperms
Pass a number as a parameter, containing the value of the permissions that
will be assigned to newly created directories on the remote server. The
default value is 0755, but any valid value can be used. The only protocols
that can use this are sftp://, scp:// and file://.
.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
1
Unsupported protocol. This build of TclCurl has no support for this
protocol.
.TP 3
2
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
3
URL malformat. The syntax was not correct.
.TP 3
4
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
5
Couldn\(cqt resolve proxy. The given proxy host could not be resolved.
.TP 3
6
Couldn\(cqt resolve host. The given remote host was not resolved.
.TP 3
7
Failed to connect to host or proxy.
.TP 3
8
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
9
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
11
FTP weird PASS reply. TclCurl couldn\(cqt parse the reply sent to the
PASS request.
.TP 3
13
FTP weird PASV reply, TclCurl couldn\(cqt parse the reply sent to the
PASV or EPSV request.
.TP 3
14
FTP weird 227 format. TclCurl couldn\(cqt parse the 227-line the server
sent.
.TP 3
15
FTP can\(cqt get host. Couldn\(cqt resolve the host IP we got in the
227-line.
.TP 3
17
FTP couldn\(cqt set type. Couldn\(cqt change transfer method to either
binary or ascii.
.TP 3
18
Partial file. Only a part of the file was transfered, this happens
when the server first reports an expected transfer size and then delivers
data that doesn\(cqt match the given size.
.TP 3
19
FTP couldn\(cqt RETR file, we either got a weird reply to a \(oqRETR\(cq
command or a zero byte transfer.
.TP 3
21
Quote error. A custom \(oqQUOTE\(cq returned error code 400 or higher (for
FTP) or otherwise indicated unsuccessful completion of the command.
.TP 3
22
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
23
Write error. TclCurl couldn\(cqt write data to a local filesystem or an
error was returned from a write callback.
.TP 3
25
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
26
Read error. There was a problem reading from a local file or an
error was returned from the read callback.
.TP 3
27
Out of memory. A memory allocation request failed. This should never
happen unless something weird is going on in your computer.
.TP 3
28
Operation timeout. The specified time-out period was reached
according to the conditions.
.TP 3
30
The FTP PORT command failed, not all FTP servers support the PORT
command, try  doing a transfer using PASV instead!.
.TP 3
31
FTP couldn\(cqt use REST. This command is used for resumed FTP
transfers.
.TP 3
33
Range error. The server doesn\(cqt support or accept range requests.
.TP 3
34
HTTP post error. Internal post-request generation error.
.TP 3
35
SSL connect error. The SSL handshaking failed, the error buffer may
have a clue to the reason, could be certificates, passwords, \[u2026]
.TP 3
36
The download could not be resumed because the specified offset was
out of the file boundary.
.TP 3
37
A file given with FILE:// couldn\(cqt be read. Did you checked the
permissions?
.TP 3
38
LDAP cannot bind. LDAP bind operation failed.
.TP 3
39
LDAP search failed.
.TP 3
41
A required zlib function was not found.
.TP 3
42
Aborted by callback. An application told TclCurl to abort the
operation.
.TP 3
43
Internal error. A function was called with a bad parameter.
.TP 3
45
Interface error. A specified outgoing interface could not be used.
.TP 3
47
Too many redirects. When following redirects, TclCurl hit the
maximum amount, set your limit with \(enmaxredirs
.TP 3
48
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
49
A telnet option string was illegally formatted.
.TP 3
51
The remote peer\(cqs SSL certificate or SSH md5 fingerprint wasn\(cqt ok
.TP 3
52
The server didn\(cqt reply anything, which here is considered an error.
.TP 3
53
The specified crypto engine wasn\(cqt found.
.TP 3
54
Failed setting the selected SSL crypto engine as default!
.TP 3
55
Failed sending network data.
.TP 3
56
Failure with receiving network data.
.TP 3
58
Problem with the local client certificate.
.TP 3
59
Couldn\(cqt use specified SSL cipher.
.TP 3
60
Peer certificate cannot be authenticated with known CA certificates.
.TP 3
61
Unrecognized transfer encoding.
.TP 3
62
Invalid LDAP URL.
.TP 3
63
Maximum file size exceeded.
.TP 3
64
SSL use failed.
.TP 3
65
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
66
Failed to initialise ssl engine.
.TP 3
67
Failed to login, user password or similar was not accepted.
.TP 3
68
File not found on TFTP server.
.TP 3
69
There is a permission problem with the TFTP request.
.TP 3
70
The remote server has run out of space.
.TP 3
71
Illegal TFTP operation.
.TP 3
72
Unknown transfer ID.
.TP 3
73
TFTP file already exists and will not be overwritten.
.TP 3
74
No such user in the TFTP server and good behaving TFTP servers
should never return this.
.TP 3
75
Character conversion failed.
.TP 3
77
Problem with reading the SSL CA cert (path? access rights?).
.TP 3
78
Remote file not found
.TP 3
79
Error from the SSH layer
.TP 3
80
Failed to shut down the SSL connection
.TP 3
82
Failed to load CRL file
.TP 3
83
Issuer check failed
.TP 3
84
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
85
Mismatch of RTSP CSeq numbers.
.TP 3
86
Mismatch of RTSP Session Identifiers.
.TP 3
87
Unable to parse FTP file list (during FTP wildcard downloading).
.TP 3
88
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 transfered. 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 successfull 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
Retuns 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 SEE ALSO
.LP
curl, The art of HTTP scripting (at \c
.UR http://curl.haxx.se)
.UE \c
, RFC 2396,
