Provided by: tclcurl_7.22.0+hg20151017-1_amd64 
NAME
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.
SYNOPSIS
curl::init
curlHandle configure ?options?
curlHandle perform
curlHandle getinfo curlinfo_option
curlhandle cleanup
curlhandle reset
curlHandle duphandle
curlHandle pause
curlHandle resume
curl::transfer ?options?
curl::version
curl::escape url
curl::unescape url
curl::curlConfig option
curl::versioninfo option
curl::easystrerror errorCode
DESCRIPTION
The TclCurl extension gives Tcl programmers access to the libcurl library written by
Daniel Stenberg, with it you can download urls, upload them and many other neat tricks,
for more information check http://curl.haxx.se
curl::init
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.
RETURN VALUE
curlHandle to use.
curlHandle configure ?options?
configure 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 option followed by a parameter.
Notes: the options set with this procedure are valid for the forthcoming data transfers
that are performed when you invoke perform
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 curlHandle reset.
curlHandle is the return code from the curl::init call.
OPTIONS
Behaviour options
-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.
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 -debugproc
-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).
-noprogress
A 1 tells the extension to turn on the progress meter completely. It will also
prevent the progessproc from getting called.
-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.
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.
Setting nosignal 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 ntlm_Wb authentication could cause a SIGCHLD signal to
be raised.
-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 -url option, using an
fnmatch-like pattern (Shell Pattern Matching) in the last part of URL (file name).
By default, TClCurl uses its internal wildcard matching implementation. You can
provide your own matching function by the -fnmatchproc option.
This feature is only supported by the FTP download for now.
A brief introduction of its syntax follows:
* - ASTERISK
ftp://example.com/some/path/*.txt (for all txt's from the root directory)
? - QUESTION MARK
Question mark matches any (exactly one) character.
ftp://example.com/some/path/photo?.jpeg
[ - BRACKET EXPRESSION
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:
[a-zA-Z0-9] or [f-gF-G] - character interval
[abc] - character enumeration
[^abc] or [!abc] - negation
[[:name:]] class expression. Supported classes are alnum,lower, space,
alpha, digit, print, upper, blank, graph, xdigit.
[][-!^] - special case - matches only '-', ']', '[', '!' or '^'. These
characters have no special purpose.
[\[\]\\] - escape syntax. Matches '[', ']' or '\'.
Using the rules above, a file name pattern can be constructed:
ftp://example.com/some/path/[a-z[:upper:]\\].jpeg
Callback options
-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.
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.
-file File in which the transfered data will be saved.
-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 '0' if you want to stop the transfer.
If you stop the current transfer by returning 0 "pre-maturely" (i.e before the
server expected it, like when you've said you will upload N bytes and you upload
less than N bytes), you may experience that the server "hangs" waiting for the rest
of the data that won't come.
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.
-infile
File from which the data will be transfered.
-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:
proc ProgressCallback {dltotal dlnow ultotal ulnow}
In order to this option to work you have to set the noprogress option to '0'.
Setting this option to the empty string will restore the original progress
function.
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.
You can pause and resume a transfer from within this procedure using the pause and
resume commands.
-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.
See also the headervar option to get the headers into an array.
-debugproc
Name of the procedure that will receive the debug data produced by the -verbose
option, it should match the following prototype:
debugProc {infoType data}
where infoType 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).
-chunkbgnproc
Name of the procedure that will be called before a file will be transfered by ftp,
it should match the following prototype:
ChunkBgnProc {remains}
Where remains is the number of files left to be transfered (or skipped)
This callback makes sense only when using the -wildcard option.
-chunkbgnvar
Name of the variable in the global scope that will contain the data of the file
about to be transfered. If you don't use this option '::fileData' will be used.
The available data is: filename, filetype (file, directory, symlink, device block,
device char, named pipe, socket, door or error if it couldn't be identified), time,
perm, uid, gid, size, hardlinks and flags.
-chunkendproc
Name of the procedure that will be called after a file is transfered (or skipped)
by ftp, it should match the following prototype:
ChunkEndProc {}
It should return '0' if everyhting is fine and '1' if some error occurred.
-fnmatchProc
Name of the procedure that will be called instead of the internal wildcard matching
function, it should match the following prototype:
FnMatchProc {pattern string}
Returns '0' if it matches, '1' if it doesn't.
Error Options
-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.
-stderr
Pass a file name as parameter. This is the stream to use internally instead of
stderr when reporting errors.
-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.
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).
You might get some amounts of headers transferred before this situation is
detected, like for when a "100-continue" is received as a response to a POST/PUT
and a 401 or 407 is received immediately afterwards.
Network options
-url The actual URL to deal with.
If the given URL lacks the protocol part ("http://" or "ftp://" etc), it will
attempt to guess which protocol to use based on the given host name. If the given
protocol of the set URL is not supported, TclCurl will return the unsupported
protocol error when you call perform. Use curl::versioninfo for detailed info on
which protocols are supported.
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.
NOTE: this is the one option required to be set before perform is called.
-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.
Accepted protocols are 'http', 'https', 'ftp', 'ftps', 'scp', 'sftp', 'telnet',
'ldap', 'ldaps', 'dict', 'file','tftp', 'imap', 'imaps', 'pop', 'pop3', 'smtp',
'smtps', 'gopher' and 'all'.
-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 -followlocation is enabled.
This allows you to limit specific transfers to only be allowed to use a subset of
protocols in redirections.
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.
-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.
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 quote and similar FTP
specifics that will not work unless you tunnel through the HTTP proxy. Such
tunneling is activated with proxytunnel
TclCurl respects the environment variables http_proxy, ftp_proxy, all_proxy etc, if
any of those are set. The use of this option does however override any possibly set
environment variables.
Setting the proxy string to "" (an empty string) will explicitly disable the use of
a proxy, even if there is an environment variable set for it.
The proxy host string can be specified the exact same way as the proxy environment
variables, include protocol prefix (http://) and embedded user + password.
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.
-proxyport
Use this option to set the proxy port to use unless it is specified in the proxy
string by -proxy. If not specified, TclCurl will default to using port 1080 for
proxies.
-proxytype
Pass the type of the proxy. Available options are 'http', 'http1.0', 'socks4',
'socks4a', 'socks5' and 'socks5h', with the HTTP one being the default.
If you set it to http1.0, it will only affect how libcurl speaks to a proxy when
CONNECT is used. The HTTP version used for "regular" HTTP requests is instead
controled with httpversion.
-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 www.local.com, but not www.notlocal.com.
-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't know what this means, you probably
don't want this tunnel option.
-socks5gssapiservice
Pass thee name of the service. The default service name for a SOCKS5 server is
rcmd/server-fqdn. This option allows you to change it.
-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.
-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.
-localport
This sets the local port number of the socket used for connection. This can be used
in combination with -interface and you are recommended to use localportrange as
well when this is set. Valid port numbers are 1 - 65535.
-localportrange
This is the number of attempts TclCurl should do to find a working local port
number. It starts with the given -localport 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.
-dnscachetimeout
Pass the timeout in seconds. Name resolves will be kept in memory for this number
of seconds. Set to '0' to completely disable caching, or '-1' to make the cached
entries remain forever. By default, TclCurl caches this info for 60 seconds.
The name resolve functions of various libc implementations don't re-read name
server information unless explicitly told so (for example, by calling
res_init(3)). 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.
-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.
WARNING: this option is considered obsolete. Stop using it. Switch over to using
the share interface instead! See tclcurl_share.
-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.
-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.
-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.
Setting this option will disable TCP's Nagle algorithm. The purpose of this
algorithm is to try to minimize the number of small packets on the network (where
"small packets" means TCP segments less than the Maximum Segment Size (MSS) for the
network).
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.
-addressscope
Pass a number specifying the scope_id value to use when connecting to IPv6 link-
local or site-local addresses.
Names and Passwords options
-netrc A 1 parameter tells the extension to scan your ~/.netrc 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).
You can set it to the following values:
optional
The use of your ~/.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.
Undefined values of the option will have this effect.
ignored
The extension will ignore the file and use only the information in the URL.
This is the default.
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.
-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 netrc option to required. If this
option is omitted, and netrc is set, TclCurl will attempt to find the a .netrc file
in the current user's home directory.
-userpwd
Pass a string as parameter, which should be [username]:[password] to use for the
connection. Use -httpauth to decide authentication method.
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 (\). Like this:
"domain/user:password" or "domain\user:password". Some HTTP servers (on Windows)
support this style even for Basic authentication.
When using HTTP and -followlocation, 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 -unrestrictedauth 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.
-proxyuserpwd
Pass a string as parameter, which should be [username]:[password] to use for the
connection to the HTTP proxy.
-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) -userpwd option.
In order to specify the password to be used in conjunction with the user name use
the -password option.
-password
Pass a string with the password to use for the transfer.
It should be used in conjunction with the -username option.
-proxyusername
Pass a string with the user name to use for the transfer while connecting to Proxy.
It should be used in same way as the -proxyuserpwd is used, except that it allows
the username to contain a colon, like in the following example:
"sip:user@example.com".
Note the -proxyusername option is an alternative way to set the user name while
connecting to Proxy. It doesn't make sense to use them together.
-proxypassword
Pass a string with the password to use for the transfer while connecting to Proxy.
It is meant to use together with -proxyusername.
-httpauth
Set to the authentication method you want, the available ones are:
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.
digest
HTTP Digest authentication. Digest authentication is a more secure way to do
authentication over public networks than the regular old-fashioned Basic
method.
digestie
HTTP Digest authentication with an IE flavor. TclCurl will use a special
"quirk" that IE is known to have used before version 7 and that some servers
require the client to use.
gssnegotiate
HTTP GSS-Negotiate authentication. The GSS-Negotiate method, also known as
plain "Negotiate",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.
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.
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's compile time but is typically /usr/bin/ntlm_auth.
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 -nosignal is set). This behavior is subject to
change in future versions of libcurl.
any TclCurl will automatically select the one it finds most secure.
anysafe
It may use anything but basic, TclCurl will automatically select the one it
finds most secure.
-tlsauthtype
Use it to tell TclCurl which authentication method(s) you want it to use for TLS
authentication.
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 -tlsauthusername and
-tlsauthpassword options.
You need to build libcurl with GnuTLS or OpenSSL with TLS-SRP support for this
to work.
-tlsauthusername
Pass a string with the username to use for the TLS authentication method specified
with the -tlsauthtype option. Requires that the -tlsauthpassword option also be
set.
-tlsauthpassword
Pass a string with the password to use for the TLS authentication method specified
with the -tlsauthtype option. Requires that the -tlsauthusername option also be
set.
-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 proxyuserpwd option.
The methods are those listed above for the httpauth option. As of this writing,
only Basic and NTLM work.
HTTP options
-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.
-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: identity, which does nothing, deflate which requests the
server to compress its response using the zlib algorithm, and gzip which requests
the gzip algorithm. Use all to send an Accept-Encoding: header containing all
supported encodings.
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.
-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 resonse sent
using a compressed Transfer-Encoding that will be automatically uncompressed by
TclCurl on receival.
Transfer-Encoding differs slightly from the Content-Encoding you ask for with
-encoding 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.
-followlocation
An 1 tells the library to follow any Location: header that the server sends as part
of a HTTP header.
This means that the extension will re-send the same request on the new location
and follow new Location: headers all the way until no more such headers are
returned. -maxredirs can be used to limit the number of redirects TclCurl will
follow.
Since 7.19.4, TclCurl can limit what protocols it will automatically follow. The
accepted protocols are set with -redirprotocols and it excludes the FILE protocol
by default.
-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 -followlocation.
-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 -followlocation
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)
-post301
Controls how TclCurl acts on redirects after POSTs that get a 301 or 302 response
back. A "301" as parameter tells the TclCurl to respect RFC 2616/10.3.2 and not
convert POST requests into GET requests when following a 301 redirection. Passing a
"302" makes TclCurl maintain the request method after a 302 redirect. "all" is a
convenience string that activates both behaviours.
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.
This option is meaningful only when setting -followlocation
The option used to be known as -post301, which should still work but is know
deprecated.
-put An 1 parameter tells the extension to use HTTP PUT a file. The file to put must be
set with -infile and -infilesize.
This option is deprecated starting with version 0.12.1, you should use -upload.
This option does not limit how much data TclCurl will actually send, as that is
controlled entirely by what the read callback returns.
-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 -postfields option for how to specify the data to post and
-postfieldsize about how to set the data size.
Use the -postfields option to specify what data to post and -postfieldsize to set
the data size. Optionally, you can provide data to POST using the -readproc
options.
You can override the default POST Content-Type: header by setting your own with
-httpheader.
Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header. You
can disable this header with -httpheader as usual.
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 "Transfer-Encoding: chunked" with -httpheader. With HTTP 1.0 or
without chunked transfer, you must specify the size in the request.
When setting post to an 1 value, it will automatically set nobody to 0.
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 -nobody or -httpget or similar.
-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.
This is a normal application/x-www-form-urlencoded kind, which is the most
commonly used one by HTML forms.
If you want to do a zero-byte POST, you need to set -postfieldsize explicitly to
zero, as simply setting -postfields to NULL or "" just effectively disables the
sending of the specified string. TclCurl will instead assume that the POST data
will be send using the read callback!
Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header. You
can disable this header with -httpheader as usual.
Note: to make multipart/formdata posts (aka rfc1867-posts), check out -httppost
option.
-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.
-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 Tcl list.
This is the only case where the data is reset after a transfer.
First, there are some basics you need to understand about multipart/formdata posts.
Each part consists of at least a NAME and a CONTENTS part. If the part is made for
file upload, there are also a stored CONTENT-TYPE and a FILENAME. Below, we'll
discuss on what options you use to set these properties in the parts you want to
add to your post.
The list must contain a 'name' 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:
'value' followed by a string with the data to post, 'file' followed by the name of
the file to post and 'contenttype' with the type of the data (text/plain,
image/jpg, ...), you can also indicate a false file name with 'filename', this is
useful in case the server checks if the given file name is valid, for example, by
testing if it starts with 'c:\' 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 'bufferName' and 'buffer' or use
'filecontent' followed by a file name to read that file and use the contents as
data.
Should you need to specify extra headers for the form POST section, use
'contentheader' followed by a list with the headers to post.
Please see 'httpPost.tcl' and 'httpBufferPost.tcl' for examples.
If TclCurl can't set the data to post an error will be returned:
1 If the memory allocation fails.
2 If one option is given twice for one form.
3 If an empty string was given.
4 If an unknown option was used.
5 If the some form info is not complete (or error)
6 If an illegal option is used in an array.
7 TclCurl has no http support.
-referer
Pass a string as parameter. It will be used to set the referer 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 -httpheader.
-useragent
Pass a string as parameter. It will be used to set the user-agent: 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 -httpheader.
-httpheader
Pass a list 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 'Accept:', the
internally used header will just get disabled. Thus, using this option you can add
new headers, replace and remove internal headers.
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.
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.
NOTE:The most commonly replaced headers have "shortcuts" in the options: cookie,
useragent, and referer.
-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 "ICY 200 OK". By including this string in your list of aliases, the response
will be treated as a valid HTTP header line such as "HTTP/1.0 200 OK".
NOTE:The alias itself is not parsed for any version strings. Before version 7.16.3,
TclCurl used the value set by option httpversion, but starting with 7.16.3 the
protocol is assumed to match HTTP 1.0 when an alias matched.
-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 '[NAME]=[CONTENTS];'. Where NAME is the cookie
name and CONTENTS is what the cookie should contain.
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: "name1=content1; name2=content2;" etc.
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.
Using this option multiple times will only make the latest string override the
previous ones.
-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.
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.
If you use this option multiple times, you add more files to read.
-cookiejar
Pass a file name in which TclCurl will dump all internally known cookies when
curlHandle cleanup is called. If no cookies are known, no file will be created.
Specify "-" to have the cookies written to stdout.
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.
TclCurl will not and cannot report an error for this. Using 'verbose' will get a
warning to display, but that is the only visible feedback you get about this
possibly lethal situation.
-cookiesession
Pass an 1 to mark this as a new cookie "session". It will force TclCurl to ignore
all cookies it is about to load that are "session cookies" 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 "session" only.
-cookielist
Pass a string with a cookie. The cookie can be either in Netscape / Mozilla format
or just regular HTTP-style header (Set-Cookie: ...) format. If the cookie engine
was not enabled it will be enabled. Passing a magic string "ALL" will erase all
known cookies while "FLUSH" will write all cookies known by TclCurl to the file
specified by -cookiejar.
-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.
When setting httpget to 1, nobody will automatically be set to 0.
-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.
none We do not care about what version the library uses. TclCurl will use whatever
it thinks fit.
1.0 Enforce HTTP 1.0 requests.
1.1 Enforce HTTP 1.1 requests.
-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.
-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 encoding for
that.
-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.
SMTP options
-mailfrom
Pass a string to specify the sender address in a mail when sending an SMTP mail
with TclCurl.
-mailrcpt
Pass a list of recipients to pass to the server in your SMTP mail request.
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.
TFTP option
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.
FTP options
-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 '-' to let the library use your
systems default IP address. Default FTP operations are passive, and thus will not
use PORT.
The address can be followed by a ':' to specify a port, optionally followed by a
'-' 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_FTP_PORT_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.
Examples with specified ports:
eth0:0 192.168.1.2:32000-33000 curl.se:32123 [::1]:1234-4567
You disable PORT again and go back to using the passive version by setting this
option to an empty string.
-quote Pass a list 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 nobody to '1'
and header to '0'.
Prefix the command with an asterisk (*) to make TclCurl continue even if the
command fails as by default TclCurl will stop.
Disable this operation again by setting an empty string to this option.
Keep in mind the commands to send must be 'raw' ftp commands, for example, to
create a directory you need to send mkd Test, not mkdir Test.
Valid SFTP commands are: chgrp, chmod, chown, ln, mkdir, pwd, rename, rm, rmdir and
symlink.
-postquote
Pass a list with the FTP commands to pass to the server after your ftp transfer
request. If you do not want to transfer any files, set nobody to '1' and header to
'0'.
-prequote
Pass a list of FTP or SFTP commands to pass to the server after the transfer type
is set.
-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.
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.
Setting this option to 1 also implies a directory listing even if the URL doesn't
end with a slash, which otherwise is necessary.
Do NOT use this option if you also use -wildcardmatch as it will effectively break
that feature.
-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.
-ftpusepret
Set to 1 to tell TclCurl to use the EPRT (and LPRT) command when doing active FTP
downloads (which is enabled by 'ftpport'). 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.
-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.
-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.
-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.
This setting also applies to SFTP-connections. TclCurl will attempt to create the
remote directory if it can't obtain a handle to the target-location. The creation
will fail if a file of the same name as the directory to create already exists or
lack of permissions prevents creation.
If set to 2, TclCurl will retry the CWD command again if the subsequent MKD command
fails. This is especially useful if you're 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
-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 timeout. It is recommended that if used in
conjunction with timeout, you set it to a value smaller than timeout.
-ftpalternativetouser
Pass a string which will be used to authenticate if the usual FTP "USER user" and
"PASS password" negotiation fails. This is currently only known to be required when
connecting to Tumbleweed's Secure Transport FTPS server using client certificates
for authentication.
-ftpskippasvip
If set to 1, it instructs TclCurl not to use the IP address the server suggests in
its 227-response to TclCurl's 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.
This option has no effect if PORT, EPRT or EPSV is used instead of PASV.
-ftpsslauth
Pass TclCurl one of the values from below, to alter how TclCurl issues "AUTH TLS"
or "AUTH SSL" when FTP over SSL is activated (see -ftpssl).
You may need this option because of servers like BSDFTPD-SSL from http://bsdftpd-
ssl.sc.ru/ "which won't work properly when "AUTH SSL" is issued (although the
server responds fine and everything) but requires "AUTH TLS" instead.
default
Allows TclCurl to decide.
ssl Try "AUTH SSL" first, and only if that fails try "AUTH TLS".
tls Try "AUTH TLS" first, and only if that fails try "AUTH SSL".
-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:
none Do not attempt to use CCC.
passive
Do not initiate the shutdown, wait for the server to do it. Do not send a
reply.
active
Initiate the shutdown and wait for a reply.
-ftpaccount
Pass string (or "" to disable). When an FTP server asks for "account data" after
user name and password has been provided, this data is sent off using the ACCT
command.
-ftpfilemethod
It allows three values:
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.
nocwd
No CWD at all is done, TclCurl will do SIZE, RETR, STOR, etc and give a full
path to the server.
singlecwd
Make one CWD with the full target directory and then operate on the file
"normally". This is somewhat more standards compliant than 'nocwd' but
without the full penalty of 'multicwd'.
Protocol options
-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.
NOTE: 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.
-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, -transfertext has no effect when doing
FTP via a proxy. Beware that not all proxies support this feature.
-crlf If set to '1', TclCurl converts Unix newlines to CRLF newlines on transfers.
Disable this option again by setting the value to '0'.
-range Pass a string as parameter, which should contain the specified range you want. It
should be in the format X-Y , where X or Y may be left out. HTTP transfers also
support several intervals, separated with commas as in X-Y,N-M Using this kind of
multiple intervals will cause the HTTP server to send the response document in
pieces (using standard MIME separation techniques).
Ranges only work on HTTP, FTP and FILE transfers.
-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).
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).
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.
-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.
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 -nobody, to switch to a proper POST, use
-post or -postfields and so on.
-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).
-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.
To change request to GET, you should use httpget. Change request to POST with post
etc.
-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.
This option is mandatory for uploading using SCP.
-upload
A 1 tells the library to prepare for an upload. The -infile and -infilesize options
are also interesting for uploads. If the protocol is HTTP, uploading means using
the PUT request unless you tell TclCurl otherwise.
Using PUT with HTTP 1.1 implies the use of a "Expect: 100-continue" header. You
can disable this header with -httpheader as usual.
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 "Transfer-Encoding: chunked" with -httpheader. With HTTP 1.0 or
without chunked transfer, you must specify the size.
-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
'filesize exceeded' (63) will be returned.
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.
-timecondition
This defines how the timevalue value is treated. You can set this parameter to
ifmodsince or ifunmodsince. This feature applies to HTTP, FTP and FILE.
-timevalue
This should be the time in seconds since 1 jan 1970, and the time will be used in a
condition as specified with timecondition.
Connection options
-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.
In unix-like systems, this might cause signals to be used unless -nosignal is used.
-timeoutms
Like timeout 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.
-lowspeedlimit
Pass the speed in bytes per second that the transfer should be below during
lowspeedtime seconds for the extension to consider it too slow and abort.
-lowspeedtime
Pass the time in seconds that the transfer should be below the lowspeedlimit for
the extension to consider it too slow and abort.
-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.
-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.
-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't much point in changing this value unless you are perfectly aware of how this
work and changes TclCurl's behaviour.
When reaching the maximum limit, TclCurl closes the oldest connection in the cache
to prevent the number of open connections to increase.
Note: if you have already performed transfers with this curl handle, setting a
smaller maxconnects than before may cause open connections to unnecessarily get
closed.
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 maxconnects
option.
-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).
In unix-like systems, this might cause signals to be used unless -nosignal is set.
-connecttimeoutms
Like connecttimeout 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.
-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:
whatever
Default, resolves addresses to all IP versions that your system allows.
v4 Resolve to ipv4 addresses.
v6 Resolve to ipv6 addresses.
-resolve
Pass a list of strings with host name resolve information to use for requests with
this handle.
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.
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.
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
"-HOST:PORT". The host name must be prefixed with a dash, and the host name and
port number must exactly match what was already added previously.
-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.
You can use ftps:// URLs to explicitly switch on SSL/TSL for the control connection
and the data connection.
Alternatively you can set the option to one of these values:
nope Do not attempt to use SSL
try Try using SSL, proceed anyway otherwise.
control
Use SSL for the control conecction or fail with "use ssl failed" (64).
all Use SSL for all communication or fail with "use ssl failed" (64).
SSL and security options
-sslcert
Pass a string as parameter. The string should be the file name of your certificate.
The default format is "PEM" and can be changed with -sslcerttype.
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 "./"
prefix, in order to avoid confusion with a nickname.
-sslcerttype
Pass a string as parameter. The string should be the format of your certificate.
Supported formats are "PEM" and "DER".
-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 "PEM" and can be changed with
-sslkeytype.
-sslkeytype
Pass a pointer to a zero terminated string as parameter. The string should be the
format of your private key. Supported formats are "PEM", "DER" and "ENG"
NOTE:The format "ENG" enables you to load the private key from a crypto engine. in
this case -sslkey is used as an identifier passed to the engine. You have to set
the crypto engine with -sslengine. The "DER" format key file currently does not
work because of a bug in OpenSSL.
-keypasswd
Pass a string as parameter. It will be used as the password required to use the
-sslkey or -sshprivatekeyfile private key.
You never need a pass phrase to load a certificate but you need one to load you
private key.
This option used to be known as -sslkeypasswd and -sslcertpasswd.
-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.
NOTE:If the crypto device cannot be loaded, an error will be returned.
-sslenginedefault
Pass a 1 to set the actual crypto engine as the default for (asymmetric) crypto
operations.
NOTE:If the crypto device cannot be set, an error will be returned.
-sslversion
Use it to set what version of SSL/TLS to use. The available options are:
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).
tlsv1
Force TLSv1
sslv2
Force SSLv2
sslv3
Force SSLv3
tlsv1_0
Force TLSv1.0
tlsv1_1
Force TLSv1.1
tlsv1_2
Force TLSv1.2
-sslverifypeer
This option determines whether TclCurl verifies the authenticity of the peer's
certificate. A 1 means it verifies; zero means it doesn't. The default is 1.
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.
TclCurl uses a default bundle of CA certificates that comes with libcurl but you
can specify alternate certificates with the -cainfo or the -capath options.
When -sslverifypeer 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.
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 -sslverifyhost to control that. The check
that the host name in the certificate is valid for the host name you're connecting
to is done independently of this option.
-cainfo
Pass a file naming holding the certificate to verify the peer with. This only makes
sense when used in combination with the -sslverifypeer option, if it is set to zero
-cainfo need not even indicate an accessible file.
This option is by default set to the system path where libcurl's cacert bundle is
assumed to be stored, as established at build time.
When built against NSS this is the directory that the NSS certificate database
resides in.
-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.
This option makes sense only when used in combination with the -sslverifypeer
option. Otherwise, the result of the check is not considered as failure.
-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 -sslverifypeer option, if it is set to zero, -capath need not even indicate an
accessible path.
This option apparently does not work in Windows due to some limitation in openssl.
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.
-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.
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_V_FLAG_CRL_CHECK and X509_V_FLAG_CRL_CHECK_ALL are both set, requiring CRL
check against all the elements of the certificate chain if a CRL file is passed.
This option makes sense only when used in combination with the -sslverifypeer
option.
A specific error code (CURLE_SSL_CRL_BADFILE) is defined with the option. It is
returned when the SSL exchange fails because the CRL file cannot be loaded. A
failure in certificate verification due to a revocation information found in the
CRL does not trigger this specific error.
-sslverifyhost
This option determines whether TclCurl verifies that the server claims to be who
you want it to be.
When negotiating an SSL connection, the server sends a certificate indicating its
identity.
When -sslverifyhost is set to 2, that certificate must indicate that the server is
the server to which you meant to connect, or the connection fails.
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.
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).
When the value is 0, the connection succeeds regardless of the names in the
certificate.
The default value for this option is 2.
This option controls the identity that the server claims. The server could be
lying. To control lying, see -sslverifypeer. If libcurl is built against NSS and
-verifypeer is zero, -verifyhost is ignored.
-certinfo
Set to '1' to enable TclCurl's 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 getinfo command and its option
certinfo.
-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.
-egdsocket
Pass a path name to the Entropy Gathering Daemon socket. It will be used to seed
the random engine for SSL.
-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 + can be used as
operators.
For OpenSSL and GnuTLS valid examples of cipher lists include 'RC4-SHA',
'SHA1+DES', 'TLSv1' and 'DEFAULT'. The default list is normally set when you
compile OpenSSL.
You will find more details about cipher lists on this URL:
http://www.openssl.org/docs/apps/ciphers.html
For NSS valid examples of cipher lists include 'rsa_rc4_128_md5',
'rsa_aes_128_sha', etc. With NSS you don't add/remove ciphers. If you use this
option then all known ciphers are disabled and only those passed in are enabled.
You'll find more details about the NSS cipher lists on this URL:
<http://directory.fedora.redhat.com/docs/mod_nss.html>
-sslsessionidcache
Pass a 0 to disable TclCurl's 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.
-krblevel
Set the kerberos security level for FTP, this also enables kerberos awareness.
This is a string, 'clear', 'safe', 'confidential' or 'private'. If the string is
set but does not match one of these, 'private' will be used. Set the string to NULL
to disable kerberos4. Set the string to "" to disable kerberos support for FTP.
-gssapidelegation
Set the option to 'flag' to allow unconditional GSSAPI credential delegation. The
delegation is disabled by default since 7.21.7. Set the parameter to 'policyflag'
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_C_DELEG_POLICY_FLAG was available at compile-time.
SSH options
-sshauthtypes
The allowed types are:
publickey
password
host
keyboard
any To let TclCurl pick one
-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.
-publickeyfile
Pass the file name for your public key. If not used, TclCurl defaults to using
$HOME/.ssh/id_dsa.pub. HOME environment variable is set, and just id_dsa in the
current directory if not.
-privatekeyfile
Pass the file name for your private key. If not used, TclCurl defaults to using
$HOME/.ssh/id_dsa.pub. HOME environment variable is set, and just id_dsa in the
current directory if not. If the file is password-protected, set the password with
-keypasswd.
-sshknownhosts
Pass a string holding the file name of the known_host file to use. The known_hosts
file should use the OpenSSH file format as supported by libssh2. If this file is
specified, TclCurl will only accept connections with hosts that are known and
present in that file, with a matching public key. Use -sshkeyproc to alter the
default behavior on host and key (mis)matching.
-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 -knownhosts is also set.
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.
The known key types are: "rsa", "rsa1" and "dss", in any other case "unknown" is
given.
TclCurl opinion about how they match may be: "match", "mismatch", "missing" or
"error".
The procedure must return:
0 The host+key is accepted and TclCurl will append it to the known_hosts file
before continuing with the connection. This will also add the host+key combo
to the known_host pool kept in memory if it wasn't already present there. The
adding of data to the file is done by completely replacing the file with a new
copy, so the permissions of the file must allow this.
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't
already present there.
2 The host+key is rejected. TclCurl will close the connection.
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.
Any other value will cause the connection to be closed.
Other options
-headervar
Name of the Tcl array variable where TclCurl will store the headers returned by the
server.
-bodyvar
Name of the Tcl variable where TclCurl will store the file requested, the file may
contain text or binary data.
-canceltransvar
Name of a Tcl variable, in case you have defined a procedure to call with
-progressproc setting this variable to '1' will cancel the transfer.
-command
Executes the given command after the transfer is done, since it only works with
blocking transfers, it is pretty much useless.
-share Pass a share handle as a parameter. The share handle must have been created by a
previous call to curl::shareinit. Setting this option, will make this handle use
the data from the shared handle instead of keeping the data to itself. See
tclcurl_share for details.
-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://.
-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://.
Telnet options
-telnetoptions
Pass a list with variables to pass to the telnet negotiations. The variables should
be in the format <option=value>. TclCurl supports the options 'TTYPE', 'XDISPLOC'
and 'NEW_ENV'. See the TELNET standard for details.
NOT SUPPORTED
Some of the options libcurl offers are not supported, I don't think them worth supporting
in TclCurl but if you need one of them don't forget to complain:
CURLOPT_FRESH_CONNECT, CURLOPT_FORBID_REUSE, CURLOPT_PRIVATE, CURLOPT_SSL_CTX_FUNCTION,
CURLOPT_SSL_CTX_DATA, CURLOPT_SSL_CTX_FUNCTION and CURLOPT_CONNECT_ONLY,
CURLOPT_OPENSOCKETFUNCTION, CURLOPT_OPENSOCKETDATA.
curlHandle perform
This procedure is called after the init and all the configure calls are made, and will
perform the transfer as described in the options.
It must be called with the same curlHandle curl::init 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.
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.
RETURN VALUE
'0' if all went well, non-zero if it didn't. In case of error, if the errorbuffer
was set with configure there will be a readable error message. The error codes
are:
1 Unsupported protocol. This build of TclCurl has no support for this protocol.
2 Very early initialization code failed. This is likely to be and internal error or a
resource problem where something fundamental couldn't get done at init time.
3 URL malformat. The syntax was not correct.
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.
5 Couldn't resolve proxy. The given proxy host could not be resolved.
6 Couldn't resolve host. The given remote host was not resolved.
7 Failed to connect to host or proxy.
8 FTP weird server reply. The server sent data TclCurl couldn't parse. The given
remote server is probably not an OK FTP server.
9 We were denied access to the resource given in the URL. For FTP, this occurs while
trying to change to the remote directory.
11 FTP weird PASS reply. TclCurl couldn't parse the reply sent to the PASS request.
13 FTP weird PASV reply, TclCurl couldn't parse the reply sent to the PASV or EPSV
request.
14 FTP weird 227 format. TclCurl couldn't parse the 227-line the server sent.
15 FTP can't get host. Couldn't resolve the host IP we got in the 227-line.
17 FTP couldn't set type. Couldn't change transfer method to either binary or ascii.
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't match
the given size.
19 FTP couldn't RETR file, we either got a weird reply to a 'RETR' command or a zero
byte transfer.
21 Quote error. A custom 'QUOTE' returned error code 400 or higher (for FTP) or
otherwise indicated unsuccessful completion of the command.
22 HTTP returned error. This return code only appears if -failonerror is used and the
HTTP server returns an error code that is 400 or higher.
23 Write error. TclCurl couldn't write data to a local filesystem or an error was
returned from a write callback.
25 Failed upload failed. For FTP, the server typcially denied the STOR command. The
error buffer usually contains the server's explanation to this.
26 Read error. There was a problem reading from a local file or an error was returned
from the read callback.
27 Out of memory. A memory allocation request failed. This should never happen unless
something weird is going on in your computer.
28 Operation timeout. The specified time-out period was reached according to the
conditions.
30 The FTP PORT command failed, not all FTP servers support the PORT command, try
doing a transfer using PASV instead!.
31 FTP couldn't use REST. This command is used for resumed FTP transfers.
33 Range error. The server doesn't support or accept range requests.
34 HTTP post error. Internal post-request generation error.
35 SSL connect error. The SSL handshaking failed, the error buffer may have a clue to
the reason, could be certificates, passwords, ...
36 The download could not be resumed because the specified offset was out of the file
boundary.
37 A file given with FILE:// couldn't be read. Did you checked the permissions?
38 LDAP cannot bind. LDAP bind operation failed.
39 LDAP search failed.
41 A required zlib function was not found.
42 Aborted by callback. An application told TclCurl to abort the operation.
43 Internal error. A function was called with a bad parameter.
45 Interface error. A specified outgoing interface could not be used.
47 Too many redirects. When following redirects, TclCurl hit the maximum amount, set
your limit with --maxredirs
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.
49 A telnet option string was illegally formatted.
51 The remote peer's SSL certificate or SSH md5 fingerprint wasn't ok
52 The server didn't reply anything, which here is considered an error.
53 The specified crypto engine wasn't found.
54 Failed setting the selected SSL crypto engine as default!
55 Failed sending network data.
56 Failure with receiving network data.
58 Problem with the local client certificate.
59 Couldn't use specified SSL cipher.
60 Peer certificate cannot be authenticated with known CA certificates.
61 Unrecognized transfer encoding.
62 Invalid LDAP URL.
63 Maximum file size exceeded.
64 SSL use failed.
65 Sending the data requires a rewind that failed, since TclCurl should take care of
it for you, it means you found a bug.
66 Failed to initialise ssl engine.
67 Failed to login, user password or similar was not accepted.
68 File not found on TFTP server.
69 There is a permission problem with the TFTP request.
70 The remote server has run out of space.
71 Illegal TFTP operation.
72 Unknown transfer ID.
73 TFTP file already exists and will not be overwritten.
74 No such user in the TFTP server and good behaving TFTP servers should never return
this.
75 Character conversion failed.
77 Problem with reading the SSL CA cert (path? access rights?).
78 Remote file not found
79 Error from the SSH layer
80 Failed to shut down the SSL connection
82 Failed to load CRL file
83 Issuer check failed
84 The FTP server does not understand the PRET command at all or does not support the
given argument. Be careful when using -customrequest, a custom LIST command will be
sent with PRET CMD before PASV as well.
85 Mismatch of RTSP CSeq numbers.
86 Mismatch of RTSP Session Identifiers.
87 Unable to parse FTP file list (during FTP wildcard downloading).
88 Chunk callback reported error.
curlHandle getinfo option
Request internal information from the curl session with this procedure. This procedure is
intended to get used *AFTER* a performed transfer, and can be relied upon only if the
perform returns 0. Use this function AFTER a performed transfer if you want to get
transfer-oriented data.
The following information can be extracted:
effectiveurl
Returns the last used effective URL.
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's CONNECT response should be read with
httpconnectcode and not this.
httpconnectcode
Returns the last received proxy response code to a CONNECT request.
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't support the command that tells
document time etc) and the time of the document is unknown.
In order for this to work you have to set the -filetime option before the transfer.
namelookuptime
Returns the time, in seconds, it took from the start until the name resolving was
completed.
connecttime
Returns the time, in seconds, it took from the start until the connect to the
remote host (or proxy) was completed.
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.
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.
starttransfertime
Returns the time, in seconds, it took from the start until the first byte is just
about to be transfered. This includes the pretransfertime, and also the time the
server needs to calculate the result.
totaltime
Returns the total transaction time, in seconds, for the previous transfer,
including name resolving, TCP connect etc.
redirecturl
Returns the URL a redirect would take you to if you enable followlocation. This
can come very handy if you think using the built-in libcurl redirect logic isn't
good enough for you but you would still prefer to avoid implementing all the magic
of figuring out the new URL.
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.
redirectcount
Returns the total number of redirections that were actually followed.
numconnects
Returns how many new connections TclCurl had to create to achieve the previous
transfer (only the successful connects are counted). Combined with redirectcount
you are able to know how many times TclCurl successfully reused existing
connection(s) or not. See the Connection Options of setopt to see how TclCurl tries
to make persistent connections to save time.
primaryip
Returns the IP address of the most recent connection done with this handle. This
string may be IPv6 if that's enabled.
primaryport
Returns the destination port of the most recent connection done with this handle.
localip
Returns the local (source) IP address of the most recent connection done with this
handle. This string may be IPv6 if that's enabled.
localport
Returns the local (source) port of the most recent connection done with this
handle.
sizeupload
Returns the total amount of bytes that were uploaded.
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.
speeddownload
Returns the average download speed, measured in bytes/second, for the complete
download.
speedupload
Returns the average upload speed, measured in bytes/second, for the complete
upload.
headersize
Returns the total size in bytes of all the headers received.
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.
sslverifyresult
Returns the result of the certification verification that was requested (using the
-sslverifypeer option to configure).
sslengines
Returns a list 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.
contentlengthdownload
Returns the content-length of the download. This is the value read from the
Content-Length: field. If the size isn't known, it returns -1.
contentlengthupload
Returns the specified size of the upload.
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't send a
valid Content-Type header or that the protocol used doesn't support this.
httpauthavail
Returns a list with the authentication method(s) available.
proxyauthavail
Returns a list with the authentication method(s) available for your proxy
athentication.
oserrno
Returns the errno value from a connect failure. This value is only set on failure,
it is no reset after a successfull operation.
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.
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.
certinfo
Returns list with information about the certificate chain, assuming you had the
-certinfo 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 "name:content" where the content is for the specific named data.
NOTE: this option is only available in libcurl built with OpenSSL support.
conditionunmet
Returns the number 1 if the condition provided in the previous request didn't match
(see timecondition), you will get a zero if the condition instead was met.
curlHandle cleanup
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't call this procedure if you intend to transfer
more files.
curlHandle reset
Re-initializes all options previously set on a specified handle to the default values.
This puts back the handle to the same state as it was in when it was just created with
curl::init.
It does not change the following information kept in the handle: live connections, the
Session ID cache, the DNS cache, the cookies and shares.
curlHandle duphandle
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 cleanup. The new handle will not inherit
any state information, connections, SSL sessions or cookies.
RETURN VALUE
A new curl handle or an error message if the copy fails.
curlHandle pause
You can use this command from within a progress callback procedure to pause the transfer.
curlHandle resume
Resumes a transfer paused with curlhandle pause
curl::transfer
In case you do not want to use persistent connections you can use this command, it takes
the same arguments as the curlHandle configure and will init, configure, perform and
cleanup a connection for you.
You can also get the getinfo information by using -infooption variable pairs, after the
transfer variable will contain the value that would have been returned by $curlHandle
getinfo option.
RETURN VALUE
The same error code perform would return.
curl::version
Returns a string with the version number of tclcurl, libcurl and some of its important
components (like OpenSSL version).
RETURN VALUE
The string with the version info.
curl::escape url
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 "URL
escaped" version (%NN where NN is a two-digit hexadecimal number)
RETURN VALUE
The converted string.
curl::unescape url
This procedure will convert the given URL encoded input string to a "plain string" 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.
RETURN VALUE
The string unencoded.
curl::curlConfig option
Returns some information about how you have cURL installed.
-prefix
Returns the directory root where you installed cURL
-feature
Returns a list containing particular main features the installed libcurl was built
with. The list may include SSL, KRB4 or IPv6, do not assume any particular order.
-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...
curl::versioninfo option
Returns information about various run-time features in TclCurl.
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.
-version
Returns the version of libcurl we are using.
-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... Note that the initial zero might be
omitted.
-host Returns a string with the host information as discovered by a configure script or
set by the build environment.
-features
Returns a list with the features compiled into libcurl, the possible elements are:
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.
CONV Libcurl was built with support for character conversions.
DEBUG
Libcurl was built with extra debug capabilities built-in. This is mainly of
interest for libcurl hackers.
GSSNEGOTIATE
Supports HTTP GSS-Negotiate.
IDN Supports IDNA, domain names with international letters.
IPV6 Supports IPv6.
KERBEROS4
Supports kerberos4 (when using FTP).
LARGEFILE
Libcurl was built with support for large files.
LIBZ Supports HTTP deflate using libz.
NTML Supports HTTP NTLM
SPNEGO
Libcurl was built with support for SPNEGO authentication (Simple and Protected
GSS-API Negotiation Mechanism, defined in RFC 2478)
SSL Supports SSL (HTTPS/FTPS)
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's password without
the app having to pass them on.
TLSAUTH_SRP
Libcurl was built with support for TLS-SRP. NTLM_WB Libcurl was built with
support for NTLM delegation to a winbind helper.
Do not assume any particular order.
-sslversion
Returns a string with the OpenSSL version used, like OpenSSL/0.9.6b.
-sslversionnum
Returns the numerical OpenSSL version value as defined by the OpenSSL project. If
libcurl has no SSL support, this is 0.
-libzversion
Returns a string, there is no numerical version, for example: 1.1.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.
curl::easystrerror errorCode
This procedure returns a string describing the error code passed in the argument.
SEE ALSO
curl, The art of HTTP scripting (at http://curl.haxx.se), RFC 2396,