TclCurl(3)

📦
version 7.22.1 · 2 versions
, in debian trixie, ubuntu questing

okay so TclCurl(3) — the TclCurl manual page, bestie 💖 and this is part 1, so buckle up.

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. That's a whole buffet of protocols, periodt. 💅

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 — go look, it's giving documentation realness. 📚✨

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 call initializes 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. Slay. 🔥

RETURN VALUE

curlHandle to use. That's it, that's the whole vibe. 🫶

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 progressproc 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 💖

Ok bestie, these are the ones that tell you what went wrong when stuff goes sideways. Super underrated tbh. 🫶

  • -errorbuffer — hand it a variable name and TclCurl will stash human-readable error messages in there. Like, actually useful words instead of just a sad little return code. The way that this is more helpful than just the code… chef's kiss. ✨
  • -stderr — give it a file name as the parameter. That's the stream it'll use internally instead of stderr when it's reporting errors. So you get to redirect the drama. 🎀
  • -failonerror — set this to 1 and the extension fails silently if the HTTP code that came back is equal to or larger than 400. Default behaviour? It just returns the page normally and pretends that code doesn't exist. Ignorance is bliss ig. 🙈
Heads up bestie: this method is not fail-safe. There are occasions where non-successful response codes will slip through, especially when authentication is involved (looking at you, response codes 401 and 407). 😭

Also, you might get some amounts of headers transferred before this situation is detected — like when a "100-continue" is received as a response to a POST/PUT and then a 401 or 407 shows up immediately afterwards. Sneaky. 💀

🌐 Network options 🌐

The whole point of the thing, honestly. Let's get into it. 💅

  • -url — the actual URL to deal with. The main character. 👑

If the URL you give it is missing the protocol part ("http://" or "ftp://" etc), it'll attempt to guess which protocol to use based on the given host name. And if the protocol of the set URL isn't supported? TclCurl returns 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 sent as part of the path — which was the case previously. Glow-up era. ✨

NOTE: this is the one option required to be set before perform is called. No url, no vibes. Periodt. 💅
  • -protocols — pass a list in lowercase of protocols to limit what protocols TclCurl may use in the transfer. This lets you 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. Boundaries, we love to see it. 🦋

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. So you can let a transfer only use a subset of protocols in redirections. Very "you can sit with us but only if…" energy. 🎀

By default TclCurl will allow all protocols except for FILE and SCP. That's a difference compared to pre-7.19.4 versions, which unconditionally would follow to all protocols supported. Chaotic era, honestly.

  • -proxy — if you need a http proxy to access the outside world, set the proxy string with this option. To specify the port number in the 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. That 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's an environment variable set for it. Boundary set, slay. 💅

The proxy host string can be specified the exact same way as the proxy environment variables, including 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's 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 controlled with httpversion. Not the same thing, don't mix them up bestie. 🙈

  • -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. The receipts are right there. 🧾
  • -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. Fr fr, trust. 💀
  • -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. Cute little customization moment. 🎀
  • -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 the outgoing network interface. The name can be an interface name, an IP address or a host name. Versatile icon. ✨
  • -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. Don't do that to yourself bestie. 😭
  • -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. 💖

Also, 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. It's giving "not me, it's the libc". 🙈

  • -dnsuseglobalcache — if the value passed is 1, it tells TclCurl to use a global DNS cache that will survive between curl handle creations and deletions. This is not thread-safe as it uses a global variable.
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. Manifesting it isn't the same as getting it. 🦋
  • -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. Override era. 👑
  • -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. Balance, bestie. ⚖️

  • -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 💖

okay bestie, this is the section where you tell TclCurl who you are and how to prove it 🔐✨ identity crisis? not today.

  • -netrc — pass a 1 and TclCurl will go rummaging through your ~/.netrc file to hunt down the user name and password for the remote site you're about to access. but listen, big caveat incoming: TclCurl does not verify that the file has the correct properties set (unlike what the standard unix ftp client does), and only the machine name, user name and password get taken into account — init macros and similar things are not supported. 🙈

you can set it to the following values:

  • optional — using your ~/.netrc file is optional, and the info in the URL is 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 — whichever information is not specified in the URL.

Undefined values of the option will have this effect. (iykyk, the default-default vibe.)

  • ignored — the extension will straight up 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 holding the full path name to the file you want to use as your .netrc file. 🗂️ for the option to actually work, you have to set the netrc option to required. If this option is omitted, and netrc is set, TclCurl will attempt to find a .netrc file in the current user's home directory.
  • -userpwd — pass a string as the parameter, which should be [username]:[password], to use for the connection. use -httpauth to decide the authentication method.

When using NTLM, you can set the 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 on purpose to prevent accidental information leakage. 🛡️ protective king behaviour, we love to see it.

  • -proxyuserpwd — pass a string as the 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 the 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. pick a lane bestie 💅

  • -proxypassword — pass a string with the password to use for the transfer while connecting to Proxy. it is meant to be used together with -proxyusername.
  • -httpauth — set this to the authentication method you want, and the available ones are:
    • basic — HTTP Basic authentication. this is the default choice, and the only method that's in widespread use and supported virtually everywhere. it sends the user name and password over the network in plain text, easily captured by others. 😬 so like... it's giving open postcard, not sealed envelope.
    • digest — HTTP Digest authentication. a more secure way to do authentication over public networks than the regular old-fashioned Basic method. glow up ✨
    • 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's primarily meant as a support for Kerberos5 authentication but may also be 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 the winbind helper. authentication is performed by a separate binary application that's executed when needed. the name of the application is specified at libcurl's compile time but is typically /usr/bin/ntlm_auth.
heads up 🚨 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 🌈

welcome to the HTTP section bestie, this is where the web stuff lives 🌐💫

  • -autoreferer — pass a 1 to enable this. when enabled, TclCurl will automatically set the Referer: field in requests where it follows a Location: redirect. polite. courteous. iconic. 🎀
  • -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 the 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 — a 1 tells the library to follow any Location: header that the server sends as part of an HTTP header.

this means 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 — a 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. ⚠️ like, actually read that twice.
  • -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 — this one is the redirect drama manager 💅 it controls how TclCurl acts when a POST comes back with a 301 or 302 and there's a redirect to follow. Pass 301 and you're telling TclCurl to respect RFC 2616/10.3.2 and not convert POST requests into GET requests when following a 301 redirection. Pass 302 and TclCurl keeps the request method intact after a 302 redirect. And all? That's just the convenience string that turns both behaviours on at once. slay ✨

Okay so lowkey the non-RFC behaviour is everywhere in web browsers, which is why the extension does the conversion by default — consistency, bestie. But sometimes a server is like "no actually, I need this POST to stay a POST" after a redirection, and that's when you reach for this.

Heads up: this option is meaningful only when you're setting -followlocation.
  • -put — an 1 parameter tells the extension to use HTTP PUT for a file. The file to put must be set with -infile and -infilesize. 📁
Deprecation alert 🚨 starting with version 0.12.1 this option is deprecated — you should use -upload instead.

Also, this option does not limit how much data TclCurl will actually send — that's controlled entirely by what the read callback returns. fr fr.

  • -post — an 1 parameter tells the library to do a regular HTTP post 🫶 this is the normal application/x-www-form-urlencoded kind, aka the one HTML forms use the most. Peep -postfields for how to specify the data to post, and -postfieldsize for how to set the data size.

Use -postfields 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 an HTTP 1.1 server, you can send data without knowing the size before starting the POST, as long as you use chunked encoding 🎀 you enable that 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. no takebacks otherwise 💀
  • -postfields — pass a string as parameter, and it should be the full data to post in an HTTP POST operation 🌸 you gotta make sure 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 — because 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 sent 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 the -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. iconic behaviour honestly.

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 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. So using this option you can add new headers, replace and remove internal headers. full control, main character energy 👑

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 brand new cookie "session" ✨. It forces TclCurl to ignore every cookie it's about to load that counts as a "session cookie" from the previous session. By default TclCurl always stores and loads all cookies, no matter whether they're session cookies or not. And what even is a session cookie bestie? It's a cookie with no expiry date — it's meant to live and breathe for this "session" only, that's it, that's the whole vibe. 💅
  • -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 wasn't enabled yet, it gets enabled, slay. Passing the magic string "ALL" will erase every known cookie, while "FLUSH" will write all the cookies TclCurl knows about to the file specified by -cookiejar. 🎀
  • -httpget — if set to 1 it forces the HTTP request to get back to GET, which is usable if POST, PUT or a custom request have been used previously with the same handle. So like, a lil reset button, iconic.
When setting httpget to 1, nobody will automatically be set to 0.
  • -httpversion — set it to one of the values below, and they force TclCurl to use those specific HTTP versions 🌈. Honestly? Only use this if you really MUST because of a silly remote server. Not the flex you think it is.
    • none — we do not care about what version the library uses. TclCurl will use whatever it thinks fits.
    • 1.0 — enforce HTTP 1.0 requests.
    • 1.1 — enforce HTTP 1.1 requests.
    • 2.0 — enforce HTTP version 2 requests.
    • 2TLS — enforce version 2 requests for HTTPS, version 1.1 for HTTP.
    • 2_PRIOR_KNOWLEDGE — enforce HTTP 2 requests without performing the HTTP/1.1 Upgrade first.
  • -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. But heads up: 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. No cap.
  • -httpcontentdecoding — set to zero to disable content decoding. Set to 1 and it's enabled. Note however that TclCurl has no default content decoding but requires you to use encoding for that. Fr fr, you gotta bring your own.
  • -httptransferencoding — set to zero to disable transfer decoding, set to 1 and it's enabled (this is the 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 the first letter, TclCurl will assume you're providing a single email address only and enclose that with angle brackets for you. So thoughtful, honestly.

🧚 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. So basically it's giving maybe, depending on the server's mood. 💀

🌈 FTP options 🌈

okay bestie, this whole little section is the FTP-specific corner of the menu 💅 if you're doing file transfers over FTP or SFTP, this is your aisle. let's go 🫶

  • -ftpport — hand it a string, and it'll be used to figure out the IP address for the FTP PORT instruction. the PORT instruction is basically telling the remote server "hey, connect back to this IP address." that string can be a plain IP address, a host name, a network interface name (under unix 🐧), or just a - to let the library use your system's default IP address. fun fact: default FTP operations are passive, so PORT doesn't even get used by default.

the address can be followed by a : to specify a port, optionally followed by a - to specify a port range. if the port you specify is 0, the operating system picks a free port for you 🎀 if you give a range and all the ports in it are unavailable, libcurl reports CURLE_FTP_PORT_FAILED for the handle. invalid port/range settings get ignored. IPv6 addresses followed by a port or portrange have to be in brackets, and IPv6 addresses without a 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

wanna disable PORT again and go back to the passive version? just set this option to an empty string. iconic ✨

  • -quote — pass a list of the FTP or SFTP commands to send to the server before your ftp request. this happens before any other FTP commands get issued (even before the CWD command 👀). if you don't want to transfer any files, set nobody to 1 and header to 0.

prefix a command with an asterisk (*) to make TclCurl keep going even if that command fails — because by default TclCurl will stop 🛑

disable the whole thing again by setting an empty string.

keep in mind the commands you send have to be 'raw' ftp commands, bestie. 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 send to the server after your ftp transfer request. if you don't want to transfer any files, set nobody to 1 and header to 0.
  • -prequote — pass a list of FTP or SFTP commands to send 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. works with both FTP and SFTP urls 💖

this causes an FTP NLST command to be sent. beware though — some FTP servers only list files in their response to NLST, and 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, because 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 an 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 it'll first attempt EPRT and then LPRT before using PORT. if you pass zero to this option, it will not try 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 it'll first attempt EPSV before using PASV, but if you pass a zero to this option, it will not try 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 if 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 simultaneous connections against the same server and they all have this option enabled — because 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 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's recommended that if you use it 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 tells 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 still 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 below to alter how TclCurl issues "AUTH TLS" or "AUTH SSL" when FTP over SSL is activated (see -ftpssl).

you might 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 have been provided, this data gets 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 ✨

okay bestie, these are the protocol-level knobs and they're lowkey iconic 💅 let's get into it.

  • -transfertext — set it to 1 and TclCurl uses ASCII mode for ftp transfers instead of the default binary transfer. On win32 systems it does not set the stdout to binary mode. This is useful when you're moving text data between systems that have different views on certain characters, like newlines and 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 🦋

okay bestie, this whole cluster is about time and speed — how long we're willing to wait, how slow is too slow, and how fast is too fast. let's get into it 💅

  • -timeout — hand over the maximum time in seconds you're letting the whole TclCurl transfer take. real talk tho: name lookups can eat a considerable amount of time, so if you cap things under a few minutes you risk killing perfectly normal, healthy operations. 😭

This option makes libcurl use the SIGALRM to enable time-outing system calls.

On unix-like systems this might cause signals to get used unless you're rocking -nosignal. ✨

  • -timeoutms — literally -timeout but in milliseconds instead. one lil caveat: if libcurl is built to use the standard system name resolver, that part still uses full-second resolution for its timeouts. 🫶
  • -lowspeedlimit — the speed in bytes per second that the transfer should stay below during lowspeedtime seconds before the extension decides it's too slow and bails. 💀
  • -lowspeedtime — the time in seconds the transfer should stay below lowspeedlimit before the extension calls it too slow and aborts. 🌸
  • -maxsendspeed — a speed in bytes per second. if an upload goes over this on the cumulative average during the transfer, the transfer will pause to keep the average rate less than or equal to your value. defaults to unlimited speed, iykyk. 🔥
  • -maxrecvspeed — same energy but for downloads: a speed in bytes per second. if a download exceeds it on the cumulative average during the transfer, the transfer pauses to keep the average rate less than or equal to the value. defaults to unlimited speed. 💖
  • -maxconnects — sets the persistent connection cache size across all the protocols that support persistent connections. the number you set is the max amount of simultaneous connections TclCurl may cache in this easy handle. default is 5, and honestly there's not much point changing it unless you are perfectly aware of how this works and how it changes TclCurl's behaviour. 👑

When you hit the max limit, TclCurl closes the oldest connection in the cache so the number of open connections doesn't grow.

Note: if you've already done transfers with this curl handle, setting a smaller maxconnects than before may cause open connections to get closed unnecessarily. 🙈

And if you add this easy handle to a multi handle, this setting is not acknowledged — instead you have to configure the multi handle's own maxconnects option. periodt.

  • -connecttimeout — maximum time in seconds you allow the connection to the server to take. it only limits the connection phase, so once it's connected this option is of no more use. set it to zero to disable connection timeout (it'll then only time out on the internal timeouts).

On unix-like systems this might cause signals to be used unless -nosignal is set. ✨

  • -connecttimeoutms — like -connecttimeout but in milliseconds. and yeah, same name-resolver note: if libcurl is built to use the standard system name resolver, that part still uses full-second resolution for timeouts. 🫶
  • -ipresolve — lets an app pick what kind of IP addresses to use when resolving host names. only interesting when you're using host names that resolve to more than one version of IP. the allowed values are:
    • whatever — the default, resolves addresses to all IP versions 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 individual name resolve string goes in 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 else that operates against that HOST+PORT will use your provided ADDRESS instead. 👑

You can also 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 added previously. 🎀

  • -usessl — pass one of the values 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/TLS for the control connection and the data connection.

Or 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 connection, or fail with "use ssl failed" (64).
  • all — use SSL for all communication, or fail with "use ssl failed" (64).

🔐 SSL and security options 🔐

the serious-but-make-it-glam section, bestie. certs, keys, and vibes. 🧚

  • -sslcert — pass a string as parameter: the string should be the file name of your certificate. the default format is "PEM" and you can change it 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 so it doesn't get confused 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 you can change it 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 "ENG" format enables you to load the private key from a crypto engine. in that 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's 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 do need one to load your private key.

This option used to be known as -sslkeypasswd and -sslcertpasswd. 🫶

  • -sslengine — pass a string as parameter. it's used as the identifier for the crypto engine you want to use for your private key.
NOTE: if the crypto device can't 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 can't be set, an error will be returned. 😭
  • -sslversion — use this to set what version of SSL/TLS to use. the available options are:
    • default — the default action. it attempts 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 or later
    • sslv2 — force SSLv2
    • sslv3 — force SSLv3
    • tlsv1_0 — force TLSv1.0 or later
    • tlsv1_1 — force TLSv1.1 or later
    • tlsv1_2 — force TLSv1.2 or later
    • tlsv1_3 — force TLSv1.3 or later
    • maxdefault — use the maximum supported TLS version by libcurl, or the default value from the SSL library.
    • maxtlsv1_0 — define maximum supported TLS version as TLSv1.0
    • maxtlsv1_1 — define maximum supported TLS version as TLSv1.1
    • maxtlsv1_2 — define maximum supported TLS version as TLSv1.2
    • maxtlsv1_3 — define maximum supported TLS version as TLSv1.3
  • -sslverifypeer — this one decides 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 showing its identity. TclCurl verifies whether that certificate is authentic — i.e. that you can trust 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 verification fails to prove 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 make sure 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 in combination with the -sslverifypeer option — if it's 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 — hand it a string that names a file holding a CA certificate in PEM format. Once that's set, TclCurl does an extra vibe check against the peer certificate to confirm the issuer really is the one tied to the cert you passed in. This extra check is chef's kiss in multi-level PKI situations, where you need to enforce that the peer certificate is coming from one specific branch of the tree 🌳.

This option only makes sense when you use it alongside -sslverifypeer. Otherwise the result of that check just... isn't treated as a failure, bestie. 🤷♀️

  • -capath — pass the directory that holds a whole stack of CA certificates you want to verify the peer with. If libcurl is built against OpenSSL, that certificate directory has to be prepped using the openssl c_rehash utility. This only makes sense when paired with -sslverifypeer; if it's set to zero, -capath doesn't even need to point at an accessible path 👀.

This option apparently does not work in Windows, due to some limitation in openssl. 💀

This one is OpenSSL-specific and does literally nothing if libcurl is built to use GnuTLS. And NSS-powered libcurl only provides the option for backward compatibility. So, yk, know what you're running on.

  • -crlfile — pass a string naming a file with the concatenation of CRL (in PEM format) to use in the certificate validation that happens during the SSL exchange.

When libcurl is built to use NSS or GnuTLS, there is no way to influence the use of CRL passed in to help 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 together with -sslverifypeer.

There's a specific error code, CURLE_SSL_CRL_BADFILE, defined with this option. It gets returned when the SSL exchange fails because the CRL file can't be loaded. But heads up — a failure in certificate verification caused by revocation information found in the CRL does not trigger this specific error. 🫠

  • -sslverifyhost — this is the option that decides whether TclCurl verifies that the server claims to be who you want it to be. Main character identity check energy 👑

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 you actually meant to connect to, or the connection fails. Periodt.

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 you told Curl to connect to.

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. Wild, but okay.

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. And if libcurl is built against NSS and -verifypeer is zero, -verifyhost is ignored.

  • -certinfo — set it to '1' to switch on TclCurl's certificate chain info gatherer. With this enabled, TclCurl (if built with OpenSSL) will extract a ton of information and data about the certificates in the certificate chain used in the SSL connection. Then after a transfer you can pull all that data out using the getinfo command and its option certinfo. It's giving detective 🔍
  • -randomfile — pass a file name. That file gets read from to seed the random engine for SSL. The more random the file you specify is, the more secure the SSL connection becomes. Simple math, bestie. 🎲
  • -egdsocket — pass a path name to the Entropy Gathering Daemon socket. It'll 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 consist of one or more cipher strings separated by colons. Commas or spaces are also acceptable separators, but colons are the ones 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'll 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 the ones you passed in are enabled. All or nothing 💅

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 out in the wild that may require you to disable this so you can actually succeed. Not me fighting the wild broken implementations 😭
  • -krblevel — set the kerberos security level for FTP. This also enables kerberos awareness. It's a string: 'clear', 'safe', 'confidential' or 'private'. If the string is set but doesn't match one of those, '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. No match, no connection, sorry babe 🚫
  • -publickeyfile — pass the file name for your public key. If not used, TclCurl defaults to using $HOME/.ssh/id_dsa.pub when the 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 when the 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 the name of the procedure that will be called when the known_host matching has been done, so your application can 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, and 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's opinion about how they match may be: "match", "mismatch", "missing" or "error".

The procedure must return:

  1. 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.
  2. 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.
  3. 2 — The host+key is rejected. TclCurl will close the connection.
  4. 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

okay bestie these are the extras, the little sprinkles on top, and some of them are genuinely iconic 💅

  • -headervar — the name of a Tcl array variable where TclCurl is gonna stash the headers the server sent back. free real estate for all that header tea ✨
  • -bodyvar — the name of a Tcl variable where TclCurl drops the file you asked for. could be text, could be binary, she contains multitudes 💖
  • -canceltransvar — the name of a Tcl variable. so if you set up a proc with the -progressproc option, then setting this variable to '1' will cancel the transfer. yep, that's the kill switch, handle with care 🛑
  • -command — runs the given command after the transfer is done. but listen, it only works with blocking transfers, so it's pretty much useless. not me exposing a flop 😭
  • -share — pass a share handle in as the parameter. that share handle has to have been created by a previous call to curl::shareinit. once you set this, this handle uses the data from the shared handle instead of hoarding it all for itself (sharing is caring fr). see tclcurl_share for the full details 👑
  • -newfileperms — pass a number here, it's the permissions value that gets assigned to newly created files on the remote server. default is 0644, but any valid value works. the only protocols that can use this are sftp://, scp:// and file:// 🗂️
  • -newdirectoryperms — same energy, but for newly created directories on the remote server. default is 0755, any valid value is fine. again, only sftp://, scp:// and file:// can use it 📁

📞 Telnet options

  • -telnetoptions — pass a list of variables for the telnet negotiations. the variables gotta be in the <option=value> format. TclCurl supports the options 'TTYPE', 'XDISPLOC' and 'NEW_ENV'. see the TELNET standard for the whole lore iykyk 📟

🚫 NOT SUPPORTED

so some of the options libcurl offers are just… not supported here. the author didn't think they were worth supporting in TclCurl, but if you genuinely 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
  • CURLOPT_CONNECT_ONLY
  • CURLOPT_OPENSOCKETFUNCTION
  • CURLOPT_OPENSOCKETDATA

🦋 curlHandle perform

this is the procedure you call after the init and all the configure calls are done, and it goes and performs the transfer exactly as described in the options. it's the main character moment, the actual doing of the thing ✨

you must call it with the same curlHandle that the curl::init call gave you. and good news: you can call perform as many times as you want on the same handle. if you're transferring more than one file, you're actually encouraged to do it this way 🫶 TclCurl will try to re-use the same connection for the following transfers, which makes everything faster, less CPU intense, and uses less network resources. just remember you'll have to use configure between the invokes to set options for the next perform 🌸

no cap, listen up: you must never call this procedure simultaneously from two places using the same handle. let it return first before you invoke it again. if you want parallel transfers, you have to use several curl handles. do not test her 🙈

RETURN VALUE

it returns '0' if all went well, and non-zero if it didn't. if there was an error and you set the errorbuffer with configure, there'll be a readable error message waiting for you 💌

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 an 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 🌸

okay bestie, this is the little detective procedure that goes digging around inside your curl session and pulls out all the ✨internal tea✨. One thing tho — it's meant to be used AFTER a transfer has actually happened, and you can only really trust what it tells you if the perform returned 0. So use it after a performed transfer when what you want is transfer-oriented data. 💅

Here's everything you can extract:

  • effectiveurl — the last effective URL that got used. 👑
  • responsecode — the last HTTP or FTP code that came back. It'll be 0 if no server response code was ever received. Heads up: a proxy's CONNECT response is a whole different thing — read that with httpconnectcode, not this one. 🚫
  • httpconnectcode — the last proxy response code to a CONNECT request.
  • filetime — the remote time of the document you retrieved, in seconds since 1 jan 1970 in the GMT/UTC time zone. If you get -1, it could be so many reasons (nobody knows, the server's hiding it, the server doesn't support the command that tells you document time, etc) and basically the time of the document is unknown. Also, for this to work at all you have to set the -filetime option before the transfer. ⏰
  • namelookuptime — the time in seconds from the start until name resolving was done.
  • connecttime — the time in seconds from the start until the connect to the remote host (or proxy) was completed.
  • appconnecttime — the time in seconds from the start until the SSL/SSH connect/handshake to the remote host was completed. This one's usually super close to the PRETRANSFER time, except in cases like HTTP pipelining where the pretransfer time can get delayed from waiting in line for the pipeline and stuff. 🚦
  • pretransfertime — the time in seconds from the start until the file transfer is just about to begin. That includes every pre-transfer command and negotiation specific to the protocol(s) involved.
  • starttransfertime — the time in seconds from the start until the first byte is just about to be transferred. It includes the pretransfertime plus whatever time the server needed to calculate the result.
  • totaltime — the total transaction time in seconds for the previous transfer, name resolving, TCP connect, all of it. 🕐
  • redirecturl — the URL a redirect would take you to if you enable followlocation. This one is chef's kiss handy if you think libcurl's built-in redirect logic isn't good enough for you but you'd still rather not hand-roll all the magic of figuring out the new URL yourself.
  • redirecttime — the total time in seconds for all the redirection steps — name lookup, connect, pretransfer and transfer — before the final transaction started. It's the complete execution time for multiple redirections, so it's 0 if no redirections were needed.
  • redirectcount — the total number of redirections that were actually followed.
  • numconnects — how many brand new connections TclCurl had to create to pull off the previous transfer (only successful connects get counted, bestie). Pair it with redirectcount and you can tell how many times TclCurl successfully reused existing connection(s) and how many times it didn't. Peep the Connection Options of setopt to see how TclCurl tries to keep persistent connections around to save time. 🔌
  • primaryip — the IP address of the most recent connection made with this handle. This string may be IPv6 if that's enabled.
  • primaryport — the destination port of the most recent connection made with this handle.
  • localip — the local (source) IP address of the most recent connection made with this handle. This string may be IPv6 if that's enabled.
  • localport — the local (source) port of the most recent connection made with this handle.
  • sizeupload — the total amount of bytes that were uploaded.
  • sizedownload — the total amount of bytes that were downloaded. Careful: this is only for the latest transfer and it gets reset again for every new transfer. 🔄
  • speeddownload — the average download speed in bytes/second for the complete download.
  • speedupload — the average upload speed in bytes/second for the complete upload.
  • headersize — the total size in bytes of all the headers received.
  • requestsize — the total size of the requests that were issued. So far this is HTTP requests only. Note that this can be more than one request if followLocation is true. 📨
  • sslverifyresult — the result of the certification verification that was requested (using the -sslverifypeer option to configure).
  • sslengines — a list of the OpenSSL crypto-engines supported. Note that engines are normally implemented in separate dynamic libraries, so not all the returned engines may actually be available at run-time. 🧚
  • contentlengthdownload — 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 — the specified size of the upload.
  • contenttype — 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 the protocol being used just doesn't support this. 🤷
  • httpauthavail — a list with the authentication method(s) available.
  • proxyauthavail — a list with the authentication method(s) available for your proxy authentication.
  • oserrno — the errno value from a connect failure. This value is only set on failure — it does not get reset after a successful operation. ⚠️
  • cookielist — a list of all the cookies TclCurl knows about (expired ones too, no judgment 🍪). If there are no cookies (like cookies for the handle haven't been enabled, or simply none were ever received) the list will just be empty.
  • ftpentrypath — a string holding the path of the entry path. That's the initial path TclCurl ended up in when it logged on to the remote FTP server. Returns an empty string if something's wrong.
  • certinfo — a list with information about the certificate chain, assuming you had the -certinfo option enabled when the previous request was done. The first item of the list reports how many certs it found, and then you can pull info for each of those certs by following the list. The info chain comes as 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), and you'll get a 0 if the condition was met instead.

🎀 curlHandle cleanup 🎀

This procedure has to be the last one you call for a curl session, periodt. It's the opposite of the curl::init procedure, and you must call it with the same curlhandle as input that the curl::init call returned. What it does is effectively close all the connections TclCurl has used and possibly been keeping open until now. So bestie — do not call this if you intend to transfer more files. 💀

🌈 curlHandle reset 🌈

Re-initializes all options previously set on a specified handle back to their default values.

That puts the handle back to the exact same state it was in when it was freshly created with curl::init. ✨

It does not change the following info kept in the handle: live connections, the Session ID cache, the DNS cache, the cookies and shares.

🦋 curlHandle duphandle 🦋

This procedure returns a new curl handle — a duplicate — using all the options previously set in the input curl handle. Both handles can then be used independently, and they both have to 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 inside a progress callback procedure to pause the transfer. ⏸️

🌸 curlHandle resume 🌸

Resumes a transfer that was paused with curlhandle pause. ▶️

💜 curl::transfer 💜

If you don't want persistent connections, you can use this command instead — it takes the same arguments as the curlHandle configure and will init, configure, perform and cleanup a connection for you. One-stop shop, no cap. 🛍️

You can also grab the getinfo information by using -infooption variable pairs — after the transfer, the 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 the OpenSSL version). 🌈

⭐ RETURN VALUE ⭐

The string with the version info.

🧚 curl::escape url 🧚

This procedure converts the given input string into a URL encoded string and returns that. Every input character that isn't a-z, A-Z or 0-9 gets converted into its "URL escaped" version (%NN where NN is a two-digit hexadecimal number). 💅

🎀 RETURN VALUE 🎀

The converted string.

🍓 curl::unescape url 🍓

This procedure converts the given URL encoded input string into a "plain string" and returns that. Every input character that's URL encoded (%XX where XX is a two-digit hexadecimal number) gets converted into its plain text version. ✨

💫 RETURN VALUE 💫

The string unencoded.

curl::curlConfig option</p> 🛠️✨

Okay bestie, this one's your little spy into how cURL was actually installed on this machine. It hands back info, that's it, no cap.

  • -prefix — gives you the directory root where cURL got installed. Like, where it lives. 🏠
  • -feature — returns a list of the particular main features your installed libcurl was built with. That list may include SSL, KRB4 or IPv6, and do not assume any particular order. It's giving chaos, not alphabetical. 🙈
  • -vernum — outputs version info about the installed libcurl, in numerical mode. It gives you the version number in hexadecimal, with 8 bits for each part: major, minor, patch. So libcurl 7.7.4 would show up as 070704, and libcurl 12.13.14 would show up as 0c0d0e... 🧮💅

curl::versioninfo option 🔍💖

This one tells you about the various run-time features in TclCurl. Run-time, not compile-time — that distinction is the whole plot.

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.

Translation: check at runtime, bestie, because DLLs can get swapped out under you. Trust nothing static. 😭

  • -version — returns the version of libcurl we are using. ⭐
  • -versionnum — returns the version of libcurl we are using in hexadecimal, with 8 bits for each part: major, minor, patch. So 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. Sneaky little zero. 🕵️♀️
  • -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. (yes, spelled exactly like that, we don't make the rules)
    • 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. Fr fr, it's a list, not a ranked tier list. 😤

  • -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. Zero. Nothing. Nada. 💀
  • -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. You feed it a sad little error code, it hands you back words. Emotional support, honestly. 🫶

🌈 SEE ALSO 🌈

And that's a wrap on this whole entire manpage, bestie!! 🎀 You read all twelve parts, that's main character energy if I've ever seen it. 👑

This little masterpiece is from TclCurl 7.22.0, dated 3 October 2011 — yes, it's an elder but it ate and left no crumbs. 💖

Now go forth and curl responsibly. Mwah. 💅✨🦋

📦 where this page comes from