TclCurl(n)

📦
version 8.0.3 · 2 versions
, in ubuntu stonking

🦋 TclCurl(n) — TclCurl Easy Interface 🦋

okay bestie, sit down, hydrate, and let me tell you about TclCurl — it's the Tcl extension that lets you talk to basically the entire internet like it's nothing. ✨

✨ NAME ✨

TclCurl — transfer data to and from URLs using FTP, FTPS, HTTP, HTTPS, SCP, SFTP, TFTP, TELNET, DICT, FILE, LDAP, LDAPS, IMAP, IMAPS, POP, POP3, SMTP, SMTPS, and GOPHER.

like… pick a protocol, any protocol 💅

🎀 SYNOPSIS 🎀

curl::init
curl::transfer ?options?
curl::version
curl::escape url
curl::unescape url
curl::curlConfig option
curl::versioninfo option
curl::easystrerror errorCode

curlHandle configure ?options?
curlHandle perform
curlHandle getinfo curlinfo_option
curlHandle cleanup
curlHandle reset
curlHandle duphandle
curlHandle pause
curlHandle resume

💜 DESCRIPTION 💜

So TclCurl is the extension that hands Tcl programmers the keys to the libcurl library, written by Daniel Stenberg. With TclCurl you can download from URLs, upload to them, and do a whole bunch of other network transfer operations. Want more tea? Go look at http://curl.haxx.se. ☕✨

🌸 curl::init 🌸

okay so this procedure must be called first, no skipping, no shortcuts. It returns a curlHandle, and you use that handle to invoke all your TclCurl procedures. Calling init initializes TclCurl, and every single call to init MUST have a corresponding call to cleanup when the operation is complete. like, they're a matched set, you don't leave one hanging 😭

You should perform all sequential file transfers using the same curlHandle. This lets TclCurl reuse persistent connections when possible — bestie behaviour fr fr 🫶

RETURN VALUE

The curlHandle to use. that's it, that's the gift 🎁

💅 curlHandle configure ?OPTIONS? 💅

configure

configure is used to set the options for a transfer. Most operations in TclCurl have default behavior, and you can change that behavior by setting the appropriate options as documented. Each option is specified as the option followed by a parameter. 🔧

Notes:

  • The options set with this procedure apply to subsequent data transfers 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 value returned by the curl::init call.

✨ OPTIONS ✨

🔥 BEHAVIOUR OPTIONS 🔥

  • -verbose — Set this option to 1 to make the library display detailed information about its operations. This option is useful when debugging libcurl and protocol-related problems.

You will rarely want to enable this in production, but it is often helpful when debugging or reporting problems. Another useful debugging option is -debugproc.

  • -header — Set this option to 1 to include headers in the body output. This is relevant only for protocols that actually send headers before the data, such as HTTP.
  • -noprogress — Set this option to 1 to disable the progress meter completely. It also prevents progressproc from being called.
  • -nosignal — Set this option to 1 to make TclCurl avoid functions that install signal handlers or cause signals to be sent to the process. This option exists mainly so that multi-threaded Unix applications can still use timeout options without risking signal-related side effects.

If this option is set and libcurl has been built with the standard name resolver, timeouts will not occur while name resolution is in progress. Consider building libcurl with c-ares support to enable asynchronous DNS lookups, which allows proper timeouts for name resolution without signals.

Setting nosignal to 1 makes libcurl stop asking the system to ignore SIGPIPE signals. Such signals may otherwise be sent by the system when data is written to a socket that has been closed by the peer. libcurl tries to avoid triggering SIGPIPE, but some operating systems provide no reliable way to prevent it, and even on those that do, some corner cases remain. In addition, using ntlm_Wb authentication may cause a SIGCHLD signal to be raised.

  • -wildcard — Set this option to 1 to transfer multiple files that match 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 the URL, that is, the file name.

By default, TclCurl uses its internal wildcard matching implementation. You can provide your own matching function with the -fnmatchproc option.

At present, this feature is supported only for FTP downloads.

A brief introduction of its syntax follows:

  • * - ASTERISK
ftp://example.com/some/path/***.txt** (for all .txt files from the
root directory) - ? - QUESTION MARK

The question mark matches any single 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 — Sets a Tcl procedure that TclCurl invokes whenever received data is available to be handled. The callback procedure must have a single argument. When the procedure is invoked, that argument refers to the contents of a data buffer managed by libcurl.
NOTE: The amount of data passed on each invocation is not fixed. The callback may be invoked with an empty buffer, or with a buffer containing a large amount of data. so don't be weird about it, okay? 💀
  • -file — File in which the transferred data will be saved. 📁
  • -readproc — Sets a Tcl procedure that TclCurl calls whenever it needs to read data to send to the peer. The procedure must take one parameter, which contains the maximum number of bytes to read. It should return the actual number of bytes read, or 0 if you want to stop the transfer.

If you stop the current transfer by returning 0 prematurely, for example after indicating that you would upload N bytes but uploading fewer than N, the server may appear to hang while waiting for the remaining data. 😭 awkward.

When doing TFTP uploads, you must return exactly the amount of data requested by the callback. Otherwise, the server may treat it as the final packet and end the transfer. no cap, exact numbers only.

  • -infile — File from which the data will be transferred.
  • -progressproc — Name of the Tcl procedure that TclCurl invokes at regular intervals during an operation, roughly once per second or more often, whether or not data is currently being transferred. Unknown or unused argument values passed to the callback are set to zero. For example, if you only download data, the upload size remains 0. The procedure must have the following prototype:
proc ProgressCallback {dltotal dlnow ultotal ulnow}

For this option to work, you must set the -noprogress option to 0. Setting this option to the empty string restores 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 the file name to which the header part of the received data will be written. Headers are written to this file one by one, and only complete lines are written. This makes header parsing straightforward. 🧚

See also the -headervar option to get the headers into an array.

  • -debugproc — Name of the procedure that receives the debug data produced by the -verbose option. The callback procedure must have two arguments:
debugProc {infoType data}

The infoType argument identifies the kind of debug information: 0 text, 1 incoming header, 2 outgoing header, 3 incoming data, 4 outgoing data, 5 incoming SSL data, and 6 outgoing SSL data. The data argument contains the corresponding data buffer.

  • -chunkbgnproc — Name of the procedure that is called before a file is transferred by FTP. The callback procedure must have one argument:
ChunkBgnProc {remains}

The remains argument is the number of files left to be transferred 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 for the file about to be transferred. If you do not use this option, ::fileData is used.

The available data is: filename, filetype (file, directory, symlink, device block, device char, named pipe, socket, door, or error if it could not be identified), time, perm, uid, gid, size, hardlinks, and flags. 👑

  • -chunkendproc — Name of the procedure that is called after a file has been transferred or skipped by FTP. The callback procedure takes no arguments:
ChunkEndProc {}

It should return 0 if everything is fine and 1 if an error occurred.

  • -fnmatchProc — Name of the procedure that is called instead of the internal wildcard matching function. The callback procedure must have two arguments:
FnMatchProc {pattern string}

The pattern argument contains the pattern to be matched. The string argument contains the candidate string. The procedure must return 0 if the string matches the pattern and 1 otherwise. 🎯

💖 ERROR OPTIONS 💖

  • -errorbuffer — hand over the name of a variable and TclCurl will stash a whole human-readable error message in there for you 🥺. Lowkey more useful than the return code alone, because the return code is giving one-word-answer energy and this is giving context.
  • -stderr — pass a file name. TclCurl writes to that stream instead of stderr whenever it's reporting errors. Redirecting your trauma, but make it a file 💅.
  • -failonerror — set this to 1 and the transfer fails if the HTTP status code that comes back is 400 or greater. By default though? TclCurl just returns the page like normal and is NOT treating those status codes as transfer errors. Chill behavior, honestly.
⚠️ heads up bestie, this is not fail-safe. In some cases non-successful response codes may still slip through, especially when authentication is involved — looking at you, status codes 401 and 407 👀.

Also, some header data may be transferred before this condition is even detected. For example, a 100-continue response may be received for a POST or PUT request before a subsequent 401 or 407 response comes back. It's giving ✨chaos✨.

🌐 NETWORK OPTIONS 🌐

  • -url — the URL to use for the transfer. Iconic. Essential. The main character, truly.

If the URL doesn't have a protocol part like http:// or ftp://, TclCurl tries to guess the protocol from the host name 🧚. And if the protocol you specified in the URL isn't supported, TclCurl returns the unsupported protocol error when you call perform. Wanna know which protocols are actually supported? Use curl::versioninfo for the detailed tea ☕.

Starting with version 7.22.0, the fragment part of the URI is no longer sent as part of the path, unlike earlier versions. Era change, periodt.

💀 NOTE: this is the only option that must be set before perform is called. The rest can vibe, this one cannot.
  • -protocols — pass a lowercase list of protocols to limit which ones TclCurl is allowed to use for the transfer. So if your TclCurl build supports a whole buffet of protocols, you can restrict a specific transfer down to just a subset 🍽️.

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 — same deal, but for redirects 🌀. Pass a lowercase list of accepted protocols to limit which ones TclCurl may use when following a redirect with -followlocation enabled. Lets you restrict specific transfers to a subset of protocols for redirections.

By default, TclCurl allows all protocols except FILE and SCP. Which is different from versions before 7.19.4 — those would follow redirects to all supported protocols unconditionally. Wild times, glad we evolved 🦋.

  • -proxy — need an HTTP proxy? Set the proxy string right here. Wanna include a port number in the string? Append :[port] to the end of the host name, slay.

The proxy string may be prefixed with [protocol]://, although that prefix gets ignored unless noted otherwise below. iykyk.

When you configure an HTTP proxy, TclCurl transparently converts operations to HTTP even if you gave it an FTP URL or some other protocol. Sneaky! And this may affect which library features are available. For example, quote and similar FTP-specific features do not work unless you tunnel through the HTTP proxy — and such tunneling is enabled with -proxytunnel 🕳️.

TclCurl respects the environment variables http_proxy, ftp_proxy, all_proxy, and others of the same kind, if they are set. Using this option overrides any such environment variables. Setting the proxy string to "" explicitly disables proxy use, even if a corresponding environment variable is set. Boundaries! We love to see it 💅.

The proxy host string can be specified the same way as the proxy environment variables, including a protocol prefix such as http:// and embedded user name and password information.

Since 7.22.0, the proxy string may include a protocol:// prefix to specify alternative proxy protocols. Use socks4://, socks4a://, socks5://, or socks5h:// to request a specific SOCKS version. The last form enables SOCKS5 and asks the proxy to perform name resolution 🧠. If no protocol is specified — and for http:// and all other prefixes — the proxy is treated as an HTTP proxy.

  • -proxyport — use this to set the proxy port, unless it's already specified in the proxy string you passed with -proxy. And if you don't specify it at all? TclCurl uses port 1080 by default 🎀.
  • -proxytype — pass the proxy type. Available values are http, http1.0, socks4, socks4a, socks5, and socks5h. The default is http.

If you set it to http1.0, it only affects how libcurl speaks to a proxy when CONNECT is used. The HTTP version used for ordinary HTTP requests is instead controlled by httpversion. Different department, bestie ✨.

  • -noproxy — pass a string with a comma-separated list of hosts that should 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 the list is matched either as a domain containing the host name, or as the host name itself. For example, local.com matches local.com, local.com:80, and www.local.com, but not www.notlocal.com. The receipts are right there 📋.
  • -httpproxytunnel — set to 1 to tunnel all non-HTTP operations through the given HTTP proxy. Using a proxy and tunneling through a proxy are different behaviors, okay? They're not the same thing. This option should only be enabled when that distinction is actually required 🫶.
  • -socks5gssapiservice — pass the service name. The default service name for a SOCKS5 server is rcmd/server-fqdn. This option lets you change it 💜.
  • -socks5gssapinec — pass 1 to enable or 0 to disable. As part of the GSSAPI negotiation, a protection mode gets negotiated. RFC 1961 specifies in sections 4.3 and 4.4 that this exchange should be protected, but the NEC reference implementation does not do that 🙈. When enabled, this option allows the protection mode negotiation to be exchanged unprotected.
  • -interface — pass the interface name to use as the outgoing network interface. The name may be an interface name, an IP address, or a host name. Flexible queen ✨.
  • -localport — sets the local port number of the socket used for the connection. Can be used together with -interface, and it is recommended to use -localportrange as well when this option is set. Valid port numbers are 1 through 65535 🔢.
  • -localportrange — the number of attempts TclCurl should make to find a working local port number. It starts with the port specified by -localport and increments it by one for each retry. Setting this value to 1 or less makes TclCurl try only one port number. Because port numbers are a limited resource and may already be in use, setting this value too low may cause unnecessary connection setup failures 💀. Don't do that to yourself.
  • -dnscachetimeout — pass the timeout in seconds. Name resolution results are kept in memory for this number of seconds. Set this option to 0 to disable caching completely, or to -1 to keep cached entries indefinitely. By default, TclCurl caches this info for 60 seconds ⏱️.

The name resolution functions in various libc implementations do not re-read name server information unless explicitly told to, for example by calling res_init(3). As a result, TclCurl may keep using older server information even after DHCP has updated it — which may look like a DNS cache issue but is honestly not TclCurl's fault 🫠.

  • -dnsuseglobalcache — if set to 1, TclCurl uses a global DNS cache that survives the creation and deletion of curl handles. This is not thread-safe, because it relies on a global variable 😭. This option was deprecated in libcurl v7.11.1 and is disabled by default in the TclCurl build. See README.md for instructions on how to re-enable it.
🚨 WARNING: This option is obsolete. Use the share interface instead. See tclcurl_share.
  • -buffersize — pass the preferred size for the TclCurl receive buffer. A smaller buffer may cause the write callback to be invoked more often with smaller chunks 🧩. But bestie, this value is treated as a request, not as a guarantee. Manifesting it, essentially.
  • -port — pass the remote port number to connect to, instead of the port specified in the URL or the default port for the protocol in use. Override the default, you're the main character now 👑.
  • -tcpnodelay — pass a number to specify whether the TCP_NODELAY option should be set or cleared (1 = set, 0 = clear). This option is cleared by default. It has no effect after the connection has already been established ⏳.

Setting this option will disable TCP's Nagle algorithm. The purpose of that algorithm is to try to minimize the number of small packets on the network — and by "small packets" we mean 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 🌊. Basically: use it with intention, not on impulse.

  • -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 prove it. very "let me in, i have credentials" energy. 🔐

  • -netrc — set this bad boy and TclCurl goes digging through your ~/.netrc file looking for the user name and password of the remote site you're about to hit. heads up tho: TclCurl does not verify that the file has the correct properties set, unlike the standard Unix ftp client. only machine name, user name and password get taken into account — init macros and similar entries are simply not supported. 🙈

accepted values:

  • optional — using ~/.netrc is optional, and whatever's in the URL wins. the file gets searched using the host and user name to find the password only, or using the host name alone to find the first user name and password for that machine — depends on which info the URL is missing. Undefined values for this option do the exact same thing.
  • ignored — TclCurl ignores the file completely and uses only what's in the URL. this is the default. 💅
  • required — TclCurl requires the file, ignores the info in the URL, and searches the file using the host name only.
  • -netrcfile — pass a string with the full path name of the file to use as the .netrc file. for this option to work you must set -netrc to required. if you omit this option but -netrc is set, TclCurl tries to find a .netrc file in the current user's home directory. 🏠
  • -userpwd — pass a string in the form [username]:[password] to use for the connection. use -httpauth to pick the authentication method.

when you're using NTLM you can specify a domain by prepending it to the user name and separating the domain and name with a forward slash (/) or backward slash (\\), like domain/user:password or domain\\user:password. some HTTP servers on Windows also support this form for Basic authentication.

when you're using HTTP + -followlocation, TclCurl might make several requests to possibly different hosts. TclCurl will only send this user and password info to hosts using the initial host name (unless -unrestrictedauth is set), so if it follows locations to other hosts it will not hand over the user and password to those. this is enforced on purpose to prevent accidental information leakage. 🛡️

  • -proxyuserpwd — pass a string in the form [username]:[password] for the connection to the HTTP proxy.
  • -username — pass a string containing the user name to use for the transfer. this sets the user name used in protocol authentication. don't use this together with the older -userpwd option, that's messy.

and to specify the password that goes with it, use the -password option. ✨

  • -password — pass a string containing the password to use for the transfer. should be used together with -username, they're a duo, a package deal. 🫶
  • -proxyusername — pass a string containing the user name to use for the transfer while connecting to the proxy. it works just like -proxyuserpwd, except it lets the user name contain a colon, like sip:user@example.com. -proxyusername is an alternative way to set the user name for proxy connections — it should not be used together with -proxyuserpwd. pick one, queen. 💅
  • -proxypassword — pass a string containing the password to use for the transfer while connecting to the proxy. this one is meant to be used together with -proxyusername.
  • -httpauth — set this to the authentication method you want. accepted values:
    • basic — HTTP Basic authentication. this is the default choice and the only method in widespread use that's supported just about everywhere. it sends the user name and password over the network in plain text. 😭
    • digest — HTTP Digest authentication. over public networks this is generally more secure than Basic.
    • digestie — HTTP Digest authentication with an Internet Explorer-specific variant. TclCurl uses a compatibility behavior known to have been used by Internet Explorer before version 7, and still required by some servers. (legacy icons, we respect them 🙈)
    • gssnegotiate — HTTP GSS-Negotiate authentication. also known simply as Negotiate, this method was designed by Microsoft and is used in Microsoft web applications. it's primarily intended to support Kerberos 5 authentication, but it may also be used with other authentication methods.
    • ntlm — HTTP NTLM authentication. a proprietary protocol developed and used by Microsoft. it uses a challenge-response mechanism and hashing, similar to Digest, to avoid sending the password in clear text.
    • ntlmwb — NTLM delegated to the winbind helper. authentication is performed by a separate binary application that's executed when needed. the name of that application is specified when libcurl is built, but it's typically /usr/bin/ntlm_auth.
    • any — TclCurl automatically selects the method it considers the most secure.
    • anysafe — TclCurl may use any method except Basic, and automatically selects the one it considers the most secure.
⚠️ 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. so, yeah, it's real.
  • -tlsauthtype — selects the authentication method to use for TLS authentication. accepted values:
    • tlsauthsrp — uses TLS-SRP authentication. Secure Remote Password authentication for TLS is defined in RFC 5054 and provides mutual authentication if both sides share a secret. to use this value you must also set -tlsauthusername and -tlsauthpassword.

libcurl must be built with GnuTLS or with OpenSSL support for TLS-SRP for any of this to work. 🧚

  • -tlsauthusername — pass a string containing the user name to use for the TLS authentication method specified with -tlsauthtype. this option requires -tlsauthpassword to be set as well. besties that travel in pairs. 💞
  • -tlsauthpassword — pass a string containing the password to use for the TLS authentication method specified with -tlsauthtype. this option requires -tlsauthusername to be set as well.
  • -proxyauth — use this to tell TclCurl which authentication method to use for proxy authentication. for some methods this causes an extra network round trip. set the actual user name and password with -proxyuserpwd.

the methods are those listed above for the httpauth option. as of this writing, only Basic and NTLM work. 📝

🌈 HTTP OPTIONS 🌈

the main character section. this is where all the real HTTP✨ moves live.

  • -autoreferer — set this option to 1 to enable automatic updates of the Referer: header when TclCurl follows a Location: redirect. 🔁
  • -encoding — sets the contents of the Accept-Encoding: header sent in an HTTP request, and enables decoding of a response when a Content-Encoding: header is received.

accepted values:

  • identity — requests no encoding.
  • deflate — requests compression using the zlib algorithm.
  • gzip — requests gzip compression.
  • all — sends an Accept-Encoding: header containing all supported encodings.

important vibe check: this is a request, not a requirement. the server may or may not honor it. 🥲 this option must be set, or any unsolicited encoding used by the server is ignored. see lib/README.encoding in the libcurl documentation for details.

  • -transferencoding — adds a request for compressed Transfer-Encoding in the outgoing HTTP request. if the server supports this and chooses to use it, the response may use a compressed Transfer-Encoding, which TclCurl then decompresses automatically when receiving the data. 🫧

Transfer-Encoding differs from the Content-Encoding requested with -encoding in that Transfer-Encoding applies strictly to the transfer, and therefore must be decoded before the data reaches the client. traditionally, Transfer-Encoding has been used less widely and is less consistently supported by HTTP clients and servers. it's giving niche. ✨

  • -followlocation — set this option to 1 to make TclCurl follow any
Location: header

sent by the server as part of an HTTP response.

TclCurl resends the request to the new location and keeps following further Location: headers until no more come back. use -maxredirs to limit how many redirects TclCurl follows.

since 7.19.4, TclCurl can also restrict which protocols it follows automatically. the accepted protocols are set with -redirprotocols. by default, the FILE protocol is excluded. 👑

  • -unrestrictedauth — set this option to 1 to allow TclCurl to keep sending authentication credentials when following redirects, even if the host name changes. this option is meaningful only when -followlocation is enabled. 🚨
  • -maxredirs — sets the redirection limit. after that many redirects have been followed, the next redirect causes an error. this option is meaningful only when -followlocation is enabled. set the limit to 0 to refuse all redirects. set it to -1 for an unlimited number of redirects, which is the default. 🌀
  • -postredir — controls how TclCurl acts on redirects after POST requests that receive a 301, 302, or 303 response. accepted values are 301, 302, 303, and all. the values 301, 302, and 303 make TclCurl preserve the POST request method for the corresponding redirect status code. the value all enables all three behaviors.

the non-RFC behavior is common in web browsers, so TclCurl performs this conversion by default to maintain consistency. however, a server may require a POST to remain a POST after such a redirection. 😤

this option is meaningful only when -followlocation is enabled.

the legacy alias -post301 is accepted for compatibility and uses the same values.

  • -put — set this option to 1 to make TclCurl upload a file using HTTP PUT. the file to upload must be specified with -infile and -infilesize.

this option is deprecated as of version 0.12.1. use -upload. 🙅‍♀️

this option does not limit how much data TclCurl will actually send, as that is controlled entirely by what the read callback returns.

  • -post — set this option to 1 to make TclCurl perform a regular HTTP POST request using the application/x-www-form-urlencoded format commonly used by HTML forms. use -postfields to specify the data to post and -postfieldsize to specify its size. 📮

Use the -postfields option to specify what data to post and -postfieldsize to set the data size. Optionally, you can also provide POST data using -readproc.

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 an Expect: 100-continue header. You can disable this header with -httpheader as usual.

If you use POST with an HTTP 1.1 server, you can send data without knowing the size in advance by using chunked encoding. Enable this by adding a header such as Transfer-Encoding: chunked with -httpheader. With HTTP 1.0, or without chunked transfer encoding, you must specify the size in the request.

Setting -post to 1 also sets -nobody to 0.

NOTE: if you already fired off a POST request and now you're like "actually bestie, gimme a HEAD or a GET instead" — you have to explicitly pick the new request type with -nobody, -httpget, or a similar option. It will not just switch on its own, and that's on periodt. 💅
  • -postfields — hand over a string with the complete data for your HTTP POST request. ✨ And listen: you are responsible for formatting that data exactly the way you want the server to see it. TclCurl will not convert or encode it for you, no cap. Most web servers just assume it's URL-encoded.

This is the normal application/x-www-form-urlencoded form, aka the one HTML forms use like 90% of the time. 🎀

Wanna do a zero-byte POST? Then you gotta set -postfieldsize explicitly to zero, because setting -postfields to NULL or "" effectively disables sending the specified string. TclCurl then assumes your POST data is coming through the read callback instead. 🫶

Using POST with HTTP 1.1 implies the use of an Expect: 100-continue header. You can disable this header with -httpheader as usual.

NOTE: for multipart/form-data posts, go look at -httppost. Different beast entirely. 🦋
  • -postfieldsize — use this one when you wanna post data without letting TclCurl call strlen() to figure out the data size. It's also required if you're posting fully binary data, which would otherwise likely fail. 😭 If this size is set to zero, the library uses strlen() to determine the data size.
  • -httppost — makes TclCurl do an HTTP multipart/form-data POST request. The data you're sending is described through a Tcl list. 👑

This is the only case where the data is reset after a transfer. Iconic, honestly.

Each part consists of at least a NAME and a CONTENTS part. If the part is used for file upload, it may also contain CONTENT-TYPE and FILENAME information.

The list must contain a 'name' tag followed by the section name. The section value can then be described with 'value', followed by a string containing the data to post, 'file', followed by the name of the file to post, or 'contenttype', followed by the content type (text/plain, image/jpg, and so on). You can also supply an alternate file name with 'filename'. This is useful if the server checks whether the provided file name is valid, or if you want to include the full path of the file being posted. You can also post the contents of a variable as if it were a file by using 'bufferName' and 'buffer', or use 'filecontent' followed by a file name to read that file and use its contents as data. 🌸

To specify additional headers for a form section, use 'contentheader' followed by a list of headers.

See httpPost.tcl and httpBufferPost.tcl for examples. 💖

Return values:

  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 some form information is incomplete or invalid.
  6. If an illegal option is used in an array.
  7. If TclCurl has no HTTP support.
  • -referer — pass a string to set the Referer: header in the HTTP request sent to the remote server.

The Referer: header identifies the resource from which the target URI was obtained. Servers may use it for logging, analytics, backlink generation, caching decisions, or request-flow checks. 🔍

This option is useful when a scripted client must reproduce the request context normally sent by a web browser, or when a server expects a specific referring URI.

The header value should normally be a URI identifying the referring resource. Fragments and userinfo components are not part of a valid Referer: field value.

The field name Referer is a historical misspelling of referrer, but the misspelled form is the standardized HTTP header name. The way HTTP just kept the typo forever? It's giving fossilized lore. 💀

Careful bestie: this header may reveal navigation context or sensitive URI data, so set it with care. And do not rely on it as a secure means of authentication or access control. Like, at all. 🙈

You can also set this header through -httpheader.

  • -useragent — pass a string to set the User-Agent: header in the HTTP request sent to the remote server. You can also set custom headers with -httpheader. 🧚
  • -httpheader — pass a list of HTTP headers to send in the request. Here's the tea ☕: if you add a header that TclCurl would otherwise generate internally, your header is used instead. And if you add a header with no value, such as Accept:, the internal header gets disabled. So this option can add, replace, or remove internal headers. Add/replace/remove — the whole trio, slay.

This option is useful when the request must include headers not exposed by dedicated TclCurl options, or when you need exact control over the final HTTP request. Common uses include setting custom authentication-related headers, API-specific headers, cache-control directives, or overriding headers such as Content-Type: or Accept:.

IMPORTANT: the headers in the list must not be CRLF-terminated, because TclCurl adds CRLF after each header item. If you include CRLF yourself, the server will likely ignore part of the headers you specified. 💀 Don't do it.

The first line of a request, containing the method, usually GET or POST, is not a header and cannot be replaced with this option. Only the lines following the request line are headers. Adding the method line to this list causes an invalid header to be sent. 🚫

NOTE: the most commonly replaced headers have dedicated shortcut options: -cookie, -useragent, and -referer. Use those for the easy wins. 👍
  • -http200aliases — pass a list of aliases to be treated as valid HTTP 200 responses. Some servers return a custom response line. For example, IceCast servers may return ICY 200 OK. If you include such a string in the list, it is treated as a valid HTTP status line such as HTTP/1.0 200 OK. 🌈
NOTE: the alias itself is not parsed for a version string. Before version 7.16.3, TclCurl used the value set by -httpversion, but since 7.16.3 the protocol is assumed to match HTTP 1.0 when an alias matches. Little glow-up in the version history, we love to see it. ✨
  • -cookie — pass a string to set a cookie in the HTTP request. The string should use the format [NAME]=[CONTENTS];, where NAME is the cookie name and CONTENTS is the cookie value. 🍪

If you need to set multiple cookies, you must set them all in a single option value by concatenating them into one string, for example name1=content1; name2=content2;.

This option sets the cookie header explicitly in the outgoing request(s). If multiple requests are performed because of authentication, redirects, or similar causes, they all receive this cookie header.

If this option is used multiple times, only the last value is kept. So don't stack 'em, mmkay? 💅

  • -cookiefile — pass the name of a file containing cookie data. The cookie data may be in Netscape cookie file format or in regular HTTP-style headers written to a file. 🍓

If the file is empty or does not exist, this option still enables cookies for the handle, causing TclCurl to parse received cookies and use matching cookies in later requests.

If you use this option multiple times, each use adds another file to read. Additive, not replace-y. 🎀

  • -cookiejar — pass a file name to which TclCurl writes all internally known cookies when curlHandle cleanup is called. If no cookies are known, no file is created. Specify - to write the cookies to standard output. 🫙

Using this option also enables cookies for the session, so matching cookies are sent on later requests, including those caused by redirects.

Heads up: TclCurl cannot report an error if writing the cookie jar fails. If -verbose is enabled, a warning is displayed, but that is the only visible feedback in this case. So if your jar's empty and you're confused, turn on -verbose and look. 😭
  • -cookiesession — set this option to 1 to mark the current run as a new cookie session. This makes TclCurl ignore session cookies loaded from a previous session. By default, TclCurl stores and loads all cookies, including session cookies. Session cookies are cookies without an expiry date and are meant to exist only for the current session. 🦋
  • -cookielist — pass a string containing a cookie. The cookie may be in Netscape/Mozilla format or in regular HTTP-style header form, such as Set-Cookie: ..... If the cookie engine is not enabled, it is enabled automatically. No setup needed, it just handles it. 💖

Special values are ALL, which erases all known cookies, and FLUSH, which writes all known cookies to the file specified by -cookiejar. 🧹

  • -httpget — set this option to 1 to force the HTTP request method back to GET. This is useful if POST, PUT, or a custom request has previously been used with the same handle. Take it back, bestie. 🔄

Setting -httpget to 1 also sets -nobody to 0.

  • -httpversion — selects the HTTP version to use. This option should be used only when it is necessary to override the default behavior because of server-side requirements. Don't just fiddle with it for funsies. 🙈

Accepted values:

  • none — lets TclCurl use the HTTP version it considers appropriate.
  • 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 an HTTP/1.1 Upgrade first.
  • -ignorecontentlength — ignores the Content-Length header. This is useful for Apache 1.x and similar servers, which may report an incorrect content length for files larger than 2 gigabytes. 🗂️
Warning: if this option is used, TclCurl cannot report progress accurately and stops the download only when the server closes the connection. So your progress bar is basically lying to you. 💀
  • -httpcontentdecoding — set this option to 0 to disable content decoding, or to 1 to enable it. TclCurl does not enable content decoding by default; for that, you must also use -encoding. No cap, two options for one vibe. 🌸
  • -httptransferencoding — set this to 0 to turn transfer decoding OFF, or 1 to turn it ON. The default is 1. TclCurl does chunked transfer decoding by default unless you disable this option. Lowkey important, don't forget it 🫶

🍓 SMTP OPTIONS 🍓

  • -mailfrom — pass in a string with the sender address to use in the SMTP envelope.

Ok so real talk: this controls the envelope sender at the SMTP protocol level. It does not set or modify the From: header field in the message body. Two totally different things bestie, do not conflate them 💅

  • -mailrcpt — pass a list of recipient addresses to use in the SMTP envelope.

Same energy as above: this controls the envelope recipients at the SMTP protocol level. It does not set or modify message header fields like To:, Cc:, or Bcc:.

In SMTP, recipients are written with angle brackets (<>) around them. If one of your recipient values doesn't already start with an angle bracket, TclCurl assumes it's a plain email address and adds the angle brackets for you automatically. So chill, it's handled ✨

🎀 TFTP OPTION 🎀

  • -tftpblksize — specifies the block size to use for TFTP data transmission. According to RFC 2348, valid values range from 8 to 65464 bytes. If you don't specify this option, the default block size is 512 bytes.

Big caveat though: the block size you asked for only actually gets used if the remote server supports it. If the server doesn't return an option acknowledgment, or it returns an acknowledgment without a block size value, then you're getting the default 512 bytes. No negotiation, no drama 🌸

💖 FTP OPTIONS 💖

  • -ftpport — pass a string identifying the address to use for the FTP PORT instruction. The PORT instruction tells the remote server to connect to the specified client address. That string can be a plain IP address, a host name, a network interface name on Unix, or just - to let the library use the system's default IP address. By default FTP transfers are passive, so PORT doesn't get used at all.

You can tack : and a port number onto the address, and optionally - and a port range after that. If the port you specify is 0, the operating system picks a free port for you. If you gave a range and none of the ports in it are available, libcurl reports CURLE_FTP_PORT_FAILED for the handle. Invalid port or port-range settings? Ignored, silently. Also — IPv6 addresses followed by a port or port range must be enclosed in brackets. IPv6 addresses without a port or port range may also be enclosed in brackets.

Examples:

eth0:0   192.168.1.2:32000-33000   curl.se:32123 [::1]:1234-4567

Wanna turn PORT off and go back to passive mode? Set this option to the empty string. Easy 💅

  • -quote — pass a list of FTP or SFTP commands to send to the server before the FTP transfer request. These go out before any other FTP commands, including CWD. If you don't actually want to transfer any files, set -nobody to 1 and -header to 0.

Prefix a command with an asterisk (*) and TclCurl keeps going even if that command fails. By default though, a failure stops the transfer. 💀

To disable this option, set it to the empty string.

The commands have to be raw FTP commands. Like, if you wanna create a directory you send mkd Test, not mkdir Test. Don't argue with the server, it's not gonna meet you halfway.

Valid SFTP commands are chgrp, chmod, chown, ln, mkdir, pwd, rename, rm, rmdir, and symlink.

  • -postquote — pass a list of FTP commands to send to the server after the FTP transfer request. If you don't wanna 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 has been set.
  • -dirlistonly — set this to 1 and you get just the file names in a directory, instead of requesting a full directory listing with file sizes, dates and all that extra info. Works with both FTP and SFTP URLs ✨

For FTP, this makes an NLST command get sent. Heads up: some FTP servers return only files in response to NLST, and may leave out subdirectories and symbolic links. Rude, but that's the server's problem not yours.

Setting this to 1 also implies a directory listing even if the URL doesn't end with a slash, which would otherwise be required.

Do not use this option together with -wildcardmatch — it effectively disables that feature. Pick a lane bestie.

  • -append — set this to 1 to append to the remote file instead of overwriting it. Only useful when you're uploading to an FTP site.
  • -ftpuseeprt — set this to 1 and TclCurl uses the EPRT and LPRT commands for active FTP transfers, which are the ones enabled with -ftpport. With this on, TclCurl tries EPRT first, then LPRT, and only then falls back to PORT. Set it to 0 and only PORT is used. Simple as.
  • -ftpuseepsv — set this to 1 and TclCurl uses the EPSV command for passive FTP transfers. This is the default behavior. When it's on, TclCurl tries EPSV before falling back to PASV. Set this to 0 and TclCurl uses only PASV.
  • -ftpusepret — set this to 1 and TclCurl sends a PRET command before PASV or EPSV. Some FTP servers, especially drftpd, require this non-standard command for directory listings and uploads or downloads in passive mode. This option has no effect for active FTP transfers though — it's passive-only energy 💅
  • -ftpcreatemissingdirs — controls whether TclCurl should try to create a remote directory when the transfer needs that directory to exist, but a CWD command shows it doesn't exist yet or can't be entered yet.

This also applies to SFTP connections. TclCurl attempts to create the remote directory if it can't obtain a handle to the target location. Creation fails if a file with the same name already exists, or if permissions don't allow directory creation. It's giving "we tried our best" 😭

Accepted values:

  • 1 — after a failed CWD, TclCurl attempts to create the missing remote directory, then continues with the transfer.
  • 2 — after a failed CWD, TclCurl attempts to create the missing remote directory. If the following MKD command fails, TclCurl retries the CWD command before giving up. Super useful when multiple simultaneous connections target the same server and another connection may have created the directory in the meantime. Teamwork fr fr 🫶
  • -ftpresponsetimeout — sets a timeout, in seconds, for how long the server may take to return a response to an FTP command before the session counts as hung. While TclCurl is waiting for such a response, this value overrides -timeout. If you're using both, -ftpresponsetimeout should normally be set smaller than -timeout. Keep it snappy ✨
  • -ftpalternativetouser — pass a string to use for authentication if the usual FTP USER user and PASS password negotiation fails. This is known to be required in some cases when connecting to Tumbleweed Secure Transport FTPS servers that use client-certificate authentication. Niche but iconic 👑
  • -ftpskippasvip — set this to 1 and TclCurl ignores the IP address the server suggested in its 227 response to TclCurl's PASV command when opening the data connection. Instead, TclCurl reuses the same IP address already in use for the control connection, while still using the port number from the 227 response.

This option has no effect if PORT, EPRT, or EPSV is used instead of PASV. Sorry, wrong door 🙈

  • -ftpsslauth — selects how TclCurl issues AUTH TLS or AUTH SSL when FTP over SSL is enabled with -ftpssl.

You might need this for servers like BSDFTPD-SSL, which don't handle AUTH SSL correctly and require AUTH TLS instead.

Accepted values:

  • default — lets TclCurl choose.
  • ssl — tries AUTH SSL first, and tries AUTH TLS only if that fails.
  • tls — tries AUTH TLS first, and tries AUTH SSL only if that fails.
  • -ftpsslccc — controls use of CCC (Clear Command Channel). CCC shuts down the SSL/TLS layer after authentication, so the rest of the control channel is unencrypted. This can let NAT routers inspect the FTP control channel. Yes, that is a real tradeoff, read it again 🔥

Accepted values are:

  • none — do not attempt to use CCC.
  • passive — do not initiate the shutdown. Wait for the server to do so, and don't send a reply.
  • active — initiate the shutdown and wait for a reply.
  • -ftpaccount — pass a string containing account data, or "" to disable it. If an FTP server asks for account data after the user name and password have been provided, TclCurl sends this value with the ACCT command.
  • -ftpfilemethod — selects how TclCurl navigates FTP paths. Accepted values are:
    • multicwd — the default. TclCurl performs one CWD operation for each path component in the URL. For deep hierarchies this may require many commands. This is the method described by RFC 1738.
    • nocwd — TclCurl does not perform CWD at all. Instead it sends commands such as SIZE, RETR, and STOR with the full path.
    • singlecwd — TclCurl performs one CWD to the full target directory and then operates on the file normally. This is somewhat more standards compliant than nocwd, without the full overhead of multicwd. Best of both worlds, honestly 🌈

💅 PROTOCOL OPTIONS 💅

  • -transfertext — set this bad boy to 1 and you get ASCII mode for FTP transfers instead of the default binary mode. Heads up tho: on Win32 systems this does NOT flip stdout into binary mode. It's genuinely useful when you're moving text data between systems that treat stuff like newlines differently (they're messy like that 🥴).
⚠️ NOTE: TclCurl does not do full ASCII conversion during ASCII FTP transfers. It literally just sets the transfer mode to ASCII and then does a normal transfer. That's it. That's the whole thing. 💀
  • -proxytransfermode — set to 1 and TclCurl will set the transfer mode (binary or ASCII) for FTP transfers going through an HTTP proxy, by appending ;type=a or ;type=i to the URL. If you omit this or set it to 0, then -transfertext does absolutely nothing for FTP transfers through an HTTP proxy. And not every proxy supports this either, so vibe check your proxy first 🫶
  • -crlf — set to 1 and TclCurl converts Unix newlines to CRLF newlines during transfers. Set to 0 and it stops doing that. Simple as. ✨
  • -range — hand it a string with the range you want. Format is X-Y, and either X or Y can be omitted. HTTP transfers also support multiple ranges separated by commas, like X-Y,N-M. When you ask for multiple ranges over HTTP, the server sends the document back in pieces using standard MIME separation rules, no cap.

Range requests are supported only for HTTP, FTP, and FILE transfers. That's the whole guest list 🎀

  • -resumefrom — pass the offset, in bytes, where the transfer should start. Set it to 0 to start from the very beginning, which kills the resume behavior entirely.

For FTP, set it to -1 to start from the end of the target file — super handy when you're continuing an interrupted upload 👑

For FTP uploads, the resume position tells TclCurl where in the local source file to resume reading. Whatever data it reads from that point gets appended to the remote target file. Chef's kiss.

  • -customrequest — pass a string with the request method you wanna use instead of the default one (like GET or HEAD) when making an HTTP request. Great for methods like DELETE and other less common HTTP requests. Only use this when you know the server supports the method you picked, bestie.

TclCurl still behaves internally according to the type of request it would've used otherwise. So switching the method with this option can give you inconsistent behavior if you didn't also select the right request type through the usual dedicated option. Like — to make a proper HEAD request, use -nobody. To make a proper POST request, use -post or -postfields. Don't freestyle it 🙈

  • -filetime — set to 1 to make TclCurl try to grab the modification time of the remote document during the transfer. This needs the remote server to either send that time directly or support a command that queries it. After the transfer, you can get the filetime value with the getinfo procedure. Lowkey satisfying when it works.

For FTP transfers, this usually means the server has to support a command for querying the remote file modification time, like MDTM. If the server doesn't have this info, the transfer can still succeed — it's just that the filetime value stays unknown. No drama. 😌

  • -nobody — set to 1 to leave the body out of the output. This only matters for protocols that actually distinguish a header part from a body part. For HTTP and HTTPS, this makes TclCurl issue a HEAD request.

Wanna go back to GET? Use -httpget. Wanna switch to POST? Use -post or a related option. Slay. 🔥

  • -infilesize — use this when uploading a file to specify the expected size of the input file.

This option is mandatory for uploads done with SCP. Like, required required. Don't skip it. ⭐

  • -upload — set to 1 to get ready for an upload. The -infile and -infilesize options are also relevant 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 that header with -httpheader, as usual ✨

If you use PUT to an HTTP 1.1 server, you can upload data without knowing the size before you start the transfer — 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. No shortcuts, sorry 🎀

  • -maxfilesize — lets you specify the maximum size (in bytes) of a file to download. If the requested file is bigger than this value, the transfer won't even start, and error 'filesize exceeded' (63) gets returned. Bye bye 💀
⚠️ NOTE: the file size isn't always known before the download, and for files like that this option has no effect — even if the transfer ends up being bigger than the limit you set. This concerns both FTP and HTTP transfers. Rough, ik.
  • -timecondition — defines how the timevalue value gets treated. Accepted values are ifmodsince and ifunmodsince. This feature applies to HTTP, FTP, and FILE. 🌈
  • -timevalue — this should be the time in seconds since 1 jan 1970, and that time gets used in a condition exactly as specified with timecondition. Time travelling but make it HTTP. ⏰

🔌 CONNECTION OPTIONS 🔌

  • -timeout — pass the maximum time, in seconds, that a TclCurl transfer operation may take. Name resolution alone can eat up a noticeable chunk of time, so setting this too low can abort operations that would've been perfectly fine. Don't be impatient, bestie 😭

Heads up: this option may cause libcurl to use SIGALRM to interrupt blocking system calls. So on Unix-like systems, signals may be used unless -nosignal is enabled. ⚠️

  • -timeoutms — like -timeout, but the value is in milliseconds. If libcurl is built to use the standard system name resolver, name resolution still uses full-second timeout granularity. Slightly less precise than you'd hope, ngl. 🫶
  • -lowspeedlimit — pass the speed, in bytes per second, below which the transfer rate has to stay for -lowspeedtime seconds before TclCurl decides the transfer is too slow and aborts it. Slow and steady does not win this race 💀
  • -lowspeedtime — pass the number of seconds during which the transfer speed has to stay below -lowspeedlimit before TclCurl considers the transfer too slow and aborts it. It's giving patience with a timer ⏳
  • -maxsendspeed — pass a speed in bytes per second. If an upload exceeds this average speed during the transfer, TclCurl pauses the transfer as needed to keep the average rate at or below the value you set. Default is unlimited speed. Go fast if you want 🏎️
  • -maxrecvspeed — pass a speed in bytes per second. If a download exceeds this average speed during the transfer, TclCurl pauses the transfer as needed to keep the average rate at or below the value you set. Default is unlimited speed. Same energy, download edition 🌸
  • -maxconnects — sets the size of the persistent connection cache for protocols that support persistent connections. This value is the max number of simultaneous connections TclCurl may cache in the easy handle. Default is 5.

When you hit the max, TclCurl closes the oldest cached connection so the number of open connections can't keep growing. Efficiency era 💅

⚠️ NOTE: if transfers have already been performed with this easy handle, lowering -maxconnects may cause existing open connections to be closed earlier than you expected. Surprise! 🙈

If this easy handle gets added to a multi handle, this setting is ignored. In that case, configure the corresponding maxconnects option on the multi handle instead. ✨

  • -connecttimeout — pass the maximum time, in seconds, that the connection phase may take. This only limits the time needed to establish the connection. Once it's connected, this option doesn't apply anymore. Set it to 0 to disable the connection timeout entirely. 🎀

On Unix-like systems, signals may be used unless -nosignal is enabled. ⚠️

  • -connecttimeoutms — like -connecttimeout, but the value is in milliseconds. If libcurl is built to use the standard system name resolver, name resolution still uses full-second timeout granularity. Yeah, same caveat, different unit 🫶
  • -ipresolve — picks which IP address families can be used when resolving host names. This only matters when a host name resolves to more than one IP version.

Accepted values are:

  • whatever — the default. Resolves addresses using all IP versions supported by the system. 🌈
  • v4 — resolves only IPv4 addresses.
  • v6 — resolves only IPv6 addresses.
  • -resolve — pass a list of host name resolution entries to use for requests made with this handle.

Every entry has to use the format HOST:PORT:ADDRESS, where HOST is the name TclCurl tries to resolve, PORT is the destination service port, and ADDRESS is the numeric IP address to use. If libcurl supports IPv6, ADDRESS can be either an IPv4 or an IPv6 address. ✨

This option basically pre-populates the DNS cache with entries for a given HOST:PORT pair, so redirects and other requests to the same HOST:PORT use the ADDRESS you supplied. Iconic shortcut behavior 👑

To remove an entry from the DNS cache, include a string in the form -HOST:PORT. The host name must be prefixed with a dash, and both the host name and port have to exactly match an entry you added earlier. No partial matches, bestie 💅

  • -usessl — selects the desired level of SSL or TLS use for the transfer. Relevant for protocols like FTP, SMTP, POP3, and IMAP.

You can also use ftps:// URLs to enable SSL/TLS explicitly for both the control connection and the data connection. Double the SSL, double the slay 🎀

Accepted values:

  • nope — do not attempt to use SSL. Not today. 🙅
  • try — attempt to use SSL, but keep going even if it can't be negotiated.
  • 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 🔒

okay bestie this is the one where we lock it DOWN. certificates, keys, handshakes, all the trust issues (the good kind). let's go 💖

  • -sslcert — hands over a string with the file name of the certificate you wanna use. default format is PEM, and you can switch that up with -sslcerttype.

ngl, when libcurl is built against NSS, this value isn't a filename at all — it's the nickname of the certificate to use for authentication. and if you genuinely want a file that's chillin in the current directory in that case, prefix it with ./ so nobody gets confused and thinks it's a nickname. 🎀

  • -sslcerttype — passes a string saying what format the certificate from -sslcert is in.

accepted values, bestie:

  • PEM — PEM format.
  • DER — DER format.
  • -sslkey — passes a string with the file name of the private key you wanna use. default format is PEM, and you can change it with -sslkeytype.
  • -sslkeytype — passes a string saying what format the private key from -sslkey is in.

accepted values:

  • PEM — PEM format.
  • DER — DER format.
  • ENG — uses a crypto engine. in this case -sslkey gets interpreted as an identifier that gets passed to the engine, and -sslengine must also be set.
NOTE: the DER private-key format may not work with some OpenSSL versions because of upstream limitations. like, not her fault, it's the upstream's fault fr. 😭
  • -keypasswd — passes a string with the passphrase needed to use the private key you specified with -sslkey or -sshprivatekeyfile.

lowkey important: a passphrase isn't needed to load a certificate itself, but it may be needed to load the matching private key.

this option used to be known as -sslkeypasswd and -sslcertpasswd — glow-up era ✨

  • -sslengine — passes a string with the identifier of the crypto engine to use for private-key operations.
NOTE: if the crypto engine cannot be loaded, TclCurl returns an error. no engine, no vibes. 💀
  • -sslenginedefault — set this to 1 to make the selected crypto engine the default for asymmetric cryptographic operations.
NOTE: if the crypto engine cannot be made the default, TclCurl returns an error. periodt.
  • -sslversion — picks the SSL or TLS protocol version to use. she's choosing her era 💅

accepted values:

  • default — uses the default behavior. TclCurl attempts to negotiate an appropriate protocol version with the remote server.
  • tlsv1 — requires TLSv1 or later.
  • sslv2 — requires SSLv2.
  • sslv3 — requires SSLv3.
  • tlsv1_0 — requires TLSv1.0 or later.
  • tlsv1_1 — requires TLSv1.1 or later.
  • tlsv1_2 — requires TLSv1.2 or later.
  • tlsv1_3 — requires TLSv1.3 or later.
  • maxdefault — uses the maximum TLS version supported by libcurl or by the SSL backend's default configuration.
  • maxtlsv1_0 — sets the maximum supported TLS version to TLSv1.0.
  • maxtlsv1_1 — sets the maximum supported TLS version to TLSv1.1.
  • maxtlsv1_2 — sets the maximum supported TLS version to TLSv1.2.
  • maxtlsv1_3 — sets the maximum supported TLS version to TLSv1.3.
  • -sslverifypeer — controls whether TclCurl verifies the authenticity of the peer certificate. set it to 1 to turn verification on, or 0 to turn it off. default is 1. 👑

during the SSL or TLS handshake, the server sends a certificate declaring its identity. TclCurl verifies that certificate against a chain of trust rooted in one or more certification authority (CA) certificates.

TclCurl uses the default CA bundle that libcurl provides, but you can hand it alternate certificates with -cainfo or -capath.

if -sslverifypeer is nonzero and the verification fails, the connection fails. if this option is 0, peer-certificate verification gets skipped.

heads up bestie: certificate verification on its own does NOT confirm that the peer is the specific host you meant to contact. use -sslverifyhost if you wanna control host-name verification.
  • -cainfo — passes the name of a file holding one or more CA certificates used to verify the peer certificate.

this option is meaningful primarily together with -sslverifypeer. if peer verification is disabled, -cainfo doesn't need to name an accessible file.

by default, this option is set to the system path of libcurl's CA bundle, as determined when libcurl was built.

when libcurl is built against NSS, this value refers to the directory containing the NSS certificate database. 🗂️

  • -issuercert — passes the name of a file containing a CA certificate in PEM format. if this option is set, an extra check happens to verify that the peer certificate was issued by the CA certificate you provided here.

this is useful in multi-level PKI environments where the peer certificate has to be constrained to a specific branch of the certificate hierarchy. like, staying in your lane, but for certs 🌳

this option is meaningful only when used together with -sslverifypeer. otherwise, if this additional check fails, it's not treated as a connection failure.

  • -capath — passes the name of a directory containing multiple CA certificates to use when verifying the peer certificate.

when libcurl is built against OpenSSL, this directory must be prepared with the openssl c_rehash utility. this option is meaningful primarily together with -sslverifypeer. if peer verification is disabled, -capath doesn't need to name an accessible directory.

this option is OpenSSL-specific and has no effect when libcurl is built against GnuTLS. NSS-based libcurl provides it only for backward compatibility.

on Windows, this option may not work because of OpenSSL limitations. sorry windows girlies 😭
  • -crlfile — passes the name of a file containing one or more certificate revocation lists in PEM format to use during certificate validation.

when libcurl is built against NSS or GnuTLS, there's no supported way to influence revocation checking with this option. when libcurl is built with OpenSSL support, both X509_V_FLAG_CRL_CHECK and X509_V_FLAG_CRL_CHECK_ALL are enabled if a CRL file is provided, so CRL checking is applied throughout the certificate chain.

this option is meaningful only when used together with -sslverifypeer.

if the CRL file cannot be loaded, the SSL exchange fails with the specific error code CURLE_SSL_CRL_BADFILE. a certificate-verification failure caused by revocation information in the CRL does not produce that specific error code. two different problems, two different error codes, don't mix them up bestie 💅

  • -sslverifyhost — controls whether TclCurl verifies that the server certificate matches the host name you intended to contact.

during the SSL or TLS handshake, the server sends a certificate declaring its identity.

when -sslverifyhost is set to 2, the certificate must identify the intended server or the connection fails. TclCurl considers the server a match when the Common Name field or a Subject Alternative Name field in the certificate matches the host name in the URL.

when this option is set to 1, the certificate must contain a Common Name field, but the specific name is not checked. this setting is generally not useful, ngl.

when this option is set to 0, the connection succeeds regardless of the names contained in the certificate. 💀

default value is 2.

this option verifies the host identity the certificate claims. if you wanna verify that the certificate itself is trusted, use -sslverifypeer. and one more thing: if libcurl is built against NSS and -sslverifypeer is 0, then -sslverifyhost is ignored. she said nothing, she's not participating. 🙈

  • -certinfo — set this to 1 to enable collection of certificate-chain information. when it's enabled, TclCurl — if built against OpenSSL — extracts certificate details from the chain used in the SSL connection.

you can pull that info back out after the transfer with the getinfo command and its certinfo option. ✨

  • -randomfile — passes a file name. TclCurl uses this file as a source of randomness for the SSL random engine.
this option was deprecated in libcurl v7.84 and is disabled by default in the TclCurl build. see README.md for instructions on how to re-enable it. she's retired but not gone gone.
  • -egdsocket — passes the path name of an Entropy Gathering Daemon socket. TclCurl uses it as a source of randomness for the SSL random engine.
this option was deprecated in libcurl v7.84 and is disabled by default in the TclCurl build. see README.md for instructions on how to re-enable it. same retired queen energy 🎀
  • -sslcipherlist — passes a string with the cipher list to use for the SSL or TLS connection. the list is made of one or more cipher strings separated normally by colons, although commas or spaces are also accepted. the characters !, -, and + may also be used as operators.

with OpenSSL and GnuTLS, valid examples include RC4-SHA, SHA1+DES, TLSv1, and DEFAULT. the default list is usually defined by the SSL backend at build time.

with NSS, valid examples include rsa_rc4_128_md5 and rsa_aes_128_sha. NSS does not support incremental add or remove semantics for ciphers. if this option is used, all known ciphers are disabled and only the ciphers listed here are enabled. all or nothing, no in-between 👑

for details about cipher-list syntax, see: http://www.openssl.org/docs/apps/ciphers.html

for NSS-specific cipher-list details, see: http://directory.fedora.redhat.com/docs/mod_nss.html

  • -sslsessionidcache — set this to 0 to disable TclCurl's use of SSL session-ID caching, or to 1 to enable it. default is 1.

in normal circumstances, reusing SSL session IDs is harmless and may improve performance. however, some broken SSL implementations may require this option to be disabled. (broken behavior found, we're working around it 🫶)

  • -krblevel — picks the Kerberos security level for FTP and thereby also enables Kerberos awareness.

accepted values are clear, safe, confidential, and private. if the string doesn't match one of these values, private is used.

set the string to NULL to disable Kerberos 4. set it to "" to disable Kerberos support for FTP. two different empties, two different meanings, wild fr fr.

  • -gssapidelegation — picks the GSSAPI credential delegation mode.

accepted values:

  • flag — allows unconditional delegation.
  • policyflag — delegates only if the OK-AS-DELEGATE flag is set in the service ticket, provided that this feature is supported by the GSSAPI implementation and that GSS_C_DELEG_POLICY_FLAG was available at compile time.

delegation is disabled by default since 7.21.7.

🔑 SSH OPTIONS 🔑

-sshauthtypes 💖

okay so this one selects the allowed SSH authentication types. like you're telling TclCurl which glow-up method the server is allowed to use to prove it's them ✨

Accepted values are:

  • publickey — use public-key authentication 🔐
  • password — use password authentication 🤫
  • host — use host-based authentication 🏠
  • keyboard — use keyboard-interactive authentication ⌨️
  • any — let TclCurl pick an authentication method automatically, no stress, it's got this 💅

-sshhostpublickeymd5

pass a string with 32 hexadecimal digits. that string has to be the 128-bit MD5 checksum of the remote host public key. if the checksum doesn't match, TclCurl rejects the connection, periodt 🙅‍♀️

heads up bestie: this option applies only to SCP and SFTP transfers. fr fr.

-sshpublickeyfile

pass the file name of the public key to use 🗝️

if you don't set this option, TclCurl defaults to $HOME/.ssh/id_dsa.pub when the HOME environment variable is set, and to id_dsa.pub in the current directory otherwise 🫶

-sshprivatekeyfile

pass the file name of the private key to use 🔏

if you don't set this option, TclCurl defaults to $HOME/.ssh/id_dsa when the HOME environment variable is set, and to id_dsa in the current directory otherwise 🌙

if your private key is passphrase-protected, use -keypasswd to hand over the passphrase. iykyk 💅

-sshknownhosts

pass a string containing the file name of the known_hosts file you wanna use 📓 the file must use the OpenSSH known_hosts format that libssh2 supports.

if this option is set, TclCurl accepts connections only to hosts that are present in that file with a matching public key ✨

want to override the default behavior for host and key matching? use -sshkeyproc, that's literally what it's for 💖

-sshkeyproc

pass the name of a callback procedure that TclCurl invokes after known_hosts matching has been performed, so your app can decide how the connection should proceed 👑

the callback is invoked only if -sshknownhosts is also set. no known_hosts, no callback, that's the vibe check.

the callback receives a list with three elements:

  1. a list containing the key type from the known_hosts file and the key itself 🔑
  2. a list containing the key type presented by the remote host and the key itself 🌐
  3. a value describing TclCurl's matching result 🧐

possible key-type values are rsa, rsa1, dss, and unknown.

possible match-result values are match, mismatch, missing, and error.

Return values:

  • 0 — accept the host and key. TclCurl appends the host and key to the known_hosts file before continuing with the connection. If the host and key are not already present in the in-memory known-hosts pool, TclCurl also adds them there. updating the file is done by replacing it with a new copy, so the file permissions must allow that ⚠️
  • 1 — accept the host and key, and continue with the connection. If the host and key are not already present in the in-memory known-hosts pool, TclCurl also adds them there ✨
  • 2 — reject the host and key. TclCurl closes the connection 💀
  • 3 — reject the host and key, but keep the SSH connection alive 🤍 this can be useful if the application needs to inspect the host or key state and then retry without incurring the full setup cost again.
  • any other return value causes TclCurl to close the connection 🙈

✨ OTHER OPTIONS ✨

-headervar

name of the Tcl array variable where TclCurl stores the headers returned by the server 📬

-bodyvar

name of the Tcl variable where TclCurl stores the requested file contents 📥 the stored data may be either text or binary data, so whatever comes through, it's coming through.

-canceltransvarname

name of a Tcl variable used together with -progressproc 🛑 if the progress callback sets this variable to 1, the transfer is canceled. that's the whole deal, iconic.

-command

executes the given command after the transfer has completed 🎬

ngl: this option works only with blocking transfers, and therefore has limited practical use. like, it's giving niche.

-share

pass a share handle 💫 the share handle must have been created previously by calling curl::shareinit.

setting this option causes the easy handle to use data from the shared handle instead of keeping its own separate copy. see tclcurl_share for details 🫶

-newfileperms

pass a numeric value specifying the permissions assigned to newly created files on the remote server 📄 the default value is 0644, but any valid value may be used.

this option applies only to sftp://, scp://, and file:// transfers 🦋

-newdirectoryperms

pass a numeric value specifying the permissions assigned to newly created directories on the remote server 📁 the default value is 0755, but any valid value may be used.

this option applies only to sftp://, scp://, and file:// transfers 🦋

📡 TELNET OPTIONS 📡

-telnetoptions

pass a list with variables to pass to the telnet negotiations 🤝 the variables should be in the format .

TclCurl supports the options 'TTYPE', 'XDISPLOC' and 'NEW_ENV'. see the TELNET standard for details 📖

💔 NOT SUPPORTED 💔

some of the options libcurl offers are not supported. the author doesn't think them worth supporting in TclCurl, but if you need one of them, don't forget to complain 📣

CURLOPT_FRESH_CONNECT, CURLOPT_FORBID_REUSE, CURLOPT_PRIVATE,

CURLOPT_SSL_CTX_FUNCTION, CURLOPT_SSL_CTX_DATA, CURLOPT_SSL_CTX_FUNCTION and

CURLOPT_CONNECT_ONLY, CURLOPT_OPENSOCKETFUNCTION, CURLOPT_OPENSOCKETDATA.

💖 curlHandle perform 💖

Okay bestie, this procedure is called after init and all the configure calls are made, and it will perform the transfer exactly as described in the options. 💅

It must be called with the same curlHandle that curl::init returned. You can do any amount of calls to perform while using the same handle. If you intend to transfer more than one file, you are even encouraged to do so. TclCurl will then attempt to re-use the same connection for the following transfers, thus making the operations faster, less CPU intense, and using less network resources. ✨ Just note that you will have to use configure between the invokes to set options for the following perform. 🌈

🚨 You must never call this procedure simultaneously from two places using the same handle. Let it return first before invoking it another time. If you want parallel transfers, you must use several curl handles. Periodt. 💀

✨ RETURN VALUE ✨

0 if all went well, non-zero if it didn’t. In case of error, if the errorbuffer was set with configure, there will be a readable error message. The error codes are:

  • 1 — Unsupported protocol. This build of TclCurl has no support for this protocol. 🚫
  • 2 — The 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 transferred. 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 typically 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 check 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 one is literally the ✨tea✨ procedure — it goes and digs up the internal lore from your curl session. One thing though: you call this AFTER a transfer has been performed, and you can only fr fr trust what it tells you if the perform came back 0. So like, use it after a transfer when you want transfer-flavoured data. 💅

Here's everything you can extract, no gatekeeping:

  • effectiveurl — the last effective URL that got used. The final form, the glow-up version. 👑
  • responsecode — the last HTTP or FTP code you received. Heads up: it's zero if no server response code came in at all. And important — if you want a proxy's CONNECT response, that's httpconnectcode, NOT this one, k? Don't mix them up, bestie, that's a vibe check fail. 🙈
  • httpconnectcode — the last received proxy response code to a CONNECT request. Yep, this is the one for that.
  • filetime — the remote time of the retrieved document, in seconds since 1 Jan 1970 in GMT/UTC. If you get -1, it could be for a whole bunch of reasons (unknown, the server is being sneaky and hiding it, the server doesn't support the command that reports document time, etc etc) — basically the time of the document is a mystery. 🕵️

For this to even work you HAVE to set the -filetime option before the transfer. No setting, no info. Periodt.

  • namelookuptime — how many seconds it took, from the start, until name resolving was done. 🦋
  • connecttime — seconds from the start until the connect to the remote host (or proxy) completed.
  • appconnecttime — seconds from the start until the SSL/SSH connect/handshake to the remote host completed. This one is usually super close to the PRETRANSFER time, except in cases like HTTP pipelining where pretransfer can get delayed from waiting in line for the pipeline and more. (yes the original says "pippelining", love that for it 😭)
  • pretransfertime — seconds from the start until the file transfer is just about to begin. This includes all the pre-transfer commands and negotiations that are specific to the protocol(s) in play.
  • starttransfertime — seconds from the start until the first byte is just about to be transferred. Includes pretransfertime, plus the time the server needs to calculate the result. Math girlies stay winning. 🔥
  • totaltime — the total transaction time, in seconds, for the previous transfer, including name resolving, TCP connect, all of it.
  • redirecturl — the URL a redirect would take you to if you enable followlocation. This is highkey handy if you think the built-in libcurl redirect logic isn't good enough for you, but you'd still rather avoid implementing all the ✨magic✨ of figuring out the new URL yourself.
  • redirecttime — the total time, in seconds, for all the redirection steps including name lookup, connect, pretransfer and transfer, before the final transaction started. It gives you the complete execution time for multiple redirections — so it returns zero if no redirections were needed at all. 🎀
  • redirectcount — the total number of redirections that were actually followed.
  • numconnects — how many new connections TclCurl had to create to pull off the previous transfer (only the successful connects get counted, we're not counting flops). Combine it with redirectcount and you can figure out how many times TclCurl successfully reused existing connection(s) or didn't. See the Connection Options of setopt to see how TclCurl tries to make persistent connections to save time. ⭐
  • primaryip — the IP address of the most recent connection made with this handle. This string can be IPv6 if that's enabled, slay.
  • 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. Also IPv6-able if 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. Note: this is only for the latest transfer and gets reset again for each new transfer, so don't expect it to accumulate, bestie.
  • speeddownload — the average download speed, measured in bytes/second, for the complete download.
  • speedupload — the average upload speed, measured in bytes/second, for the complete upload.
  • headersize — the total size in bytes of all the headers received.
  • requestsize — the total size of the issued requests. So far this is only for HTTP requests. And heads up: this may be more than one request if followLocation is true. 🫶
  • sslverifyresult — the result of the certification verification that was requested (configured using the -sslverifypeer option).
  • 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, i.e. the value read from the Content-Type: field. If you get an empty string, it means either the server didn't send a valid Content-Type header OR the protocol used doesn't support this. Either way, not its fault. 😌
  • httpauthavail — a list with the authentication method(s) available.
  • proxyauthavail — a list with the authentication method(s) available for your proxy athentication. (their typo, not mine 💀)
  • oserrno — the errno value from a connect failure. This value is only set on failure — it is not reset after a successful operation, so don't be reading it after a win.
  • cookielist — a list of ALL the cookies TclCurl knows about (expired ones too, we include everyone). If there are no cookies — either cookies for the handle haven't been enabled or simply none have been received — the list will be empty. 🍓
  • ftpentrypath — a string holding the path of the entry path. That's the initial path TclCurl ended up in when logging on to the remote FTP server. Returns an empty string if something is wrong.
  • certinfo — a list with info 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 extract 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 that specific named data. 🔐
NOTE: this option is only available in libcurl built with OpenSSL support. No OpenSSL, no certinfo, sorry bestie. 💔
  • conditionunmet — returns the number 1 if the condition provided in the previous request didn't match (see timecondition), and you'll get a zero if the condition instead was met.

🌸 curlHandle cleanup 🌸

This procedure has to be the last one you call for a curl session. It's literally the opposite of the curl::init procedure, and you must call it with the same curlhandle as input that the curl::init call returned. It effectively closes all connections TclCurl has used and possibly kept open until now. 🫶

Don't call this procedure if you intend to transfer more files. Do NOT. It's giving closed-for-business and there's no reopening. 😭

🦋 curlHandle reset 🦋

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

This puts the handle back to the exact same state it was in when it was just created with curl::init. Fresh out the box energy. ✨

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 must both be freed with cleanup. Two queens, two cleanups. 👑

The new handle will not inherit any state information, connections, SSL sessions or cookies.

RETURN VALUE

A new curl handle, or an error message if the copy fails. 🙈

⭐ curlHandle pause ⭐

You can use this command from within a progress callback procedure to pause the transfer. Hit the pause button, bestie. ✋

⭐ curlHandle resume ⭐

Resumes a transfer paused with curlhandle pause. And we're back. 🔥

🌈 curl::transfer 🌈

In case you do not want to use persistent connections, you can use this command — it takes the same arguments as the curlHandle configure and will init, configure, perform and cleanup a connection for you. One-stop shop, main character energy. 🎀

You can also get the getinfo information by using -infooption variable pairs, after the transfer variable will contain the value that would have been returned by $curlHandle getinfo option.

RETURN VALUE

The same error code perform would return.

👑 curl::version 👑

Returns a string with the version number of tclcurl, libcurl and some of its important components (like the OpenSSL version).

RETURN VALUE

The string with the version info.

🧚 curl::escape URL 🧚

This procedure converts the given input string to a URL encoded string and returns that. All input characters that are not a-z, A-Z or 0-9 will be converted to their "URL escaped" version (%NN where NN is a two-digit hexadecimal number). Very demure, very encoded. 💅

RETURN VALUE

The converted string.

🦋 curl::unescape URL 🦋

This procedure converts the given URL encoded input string to a "plain string" and returns that. All input characters that are URL encoded (%XX where XX is a two-digit hexadecimal number) will be converted to their plain text versions. The decoding arc. ✨

RETURN VALUE

The string unencoded.

🌸 curl::curlConfig OPTION 🌸

Returns some info about how you have cURL installed. Tell me everything, king. 👑

  • -prefix — returns the directory root where you installed cURL.
  • -feature — returns a list containing particular main features the installed libcurl was built with. The list may include SSL, KRB4 or IPv6 — do not assume any particular order, it's a chaotic lil list. 🌈
  • -vernum — outputs version information about the installed libcurl, in numerical mode. This outputs the version number, in hexadecimal, with 8 bits for each part: major, minor, patch. So that libcurl 7.7.4 would appear as 070704 and libcurl 12.13.14 would appear as 0c0d0e… 🧮

🦋 curl::versioninfo OPTION

Okay bestie, this one is your little spy into what your TclCurl actually is at runtime 💅 It hands back the deets about all the various run-time features of TclCurl.

And here's the part that's actually important, so listen up: apps should use this info to figure out whether something is possible or not, instead of doing compile-time checks. Why? Because dynamic/DLL libraries can be swapped out independently of the applications that use them. So like… your app can't just assume, okay? It has to ask. ✨

  • -version — tells you the version of libcurl you're using. Slay.
  • -versionnum — gives you that same libcurl version in hexadecimal, 8 bits for each part: major, minor, patch. So 7.7.4 would show up as 070704, and a hypothetical 12.13.14 would show up as 0c0d0e… also, heads up, the initial zero might just be omitted. 🙈
  • -host — a string with the host info, as discovered by a configure script or as set by the build environment.
  • -features — a list of the features compiled into libcurl! The possible elements are:
    • ASYNCHDNS — libcurl was built with support for asynchronous name lookups, which allows more exact timeouts (even on Windows) and less blocking when using the multi interface. 👑
    • CONV — libcurl was built with support for character conversions.
    • DEBUG — libcurl was built with extra debug capabilities built in. This is mainly of interest for libcurl hackers. 🧚
    • GSSNEGOTIATE — supports HTTP GSS-Negotiate.
    • IDN — supports IDNA, domain names with international letters. 🌈
    • IPV6 — supports IPv6.
    • KERBEROS4 — supports kerberos4 (when using FTP).
    • LARGEFILE — libcurl was built with support for large files.
    • LIBZ — supports HTTP deflate using libz.
    • NTML — supports HTTP NTLM.
    • SPNEGO — libcurl was built with support for SPNEGO authentication (Simple and Protected GSS-API Negotiation Mechanism, defined in RFC 2478).
    • SSL — supports SSL (HTTPS/FTPS). 🔥
    • SSPI — libcurl was built with support for SSPI. This is only available on Windows and makes libcurl use Windows-provided functions for NTLM authentication. It also allows libcurl to use the current user and the current user's password without the app having to pass them on.
    • TLSAUTH_SRP — libcurl was built with support for TLS-SRP.
      • NTLM_WB — libcurl was built with support for NTLM delegation to a winbind helper.
And fr fr, do not assume any particular order. The list is a vibe, not a sequence. 😭
  • -sslversion — a string with the OpenSSL version used, like OpenSSL/0.9.6b.
  • -sslversionnum — the numerical OpenSSL version value as defined by the OpenSSL project. If libcurl has no SSL support, this is 0.
  • -libzversion — a string (there's no numerical version for this one), 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. Also do not assume any particular order here either, bestie. The protocols will be listed using uppercase, and 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. That's it, that's the whole thing — you hand it an error code, it hands you back words that make sense of it. 🫶

✨ EXAMPLES ✨

The examples in this section assume you are running from the root of the TclCurl source tree. (Yes, root. Go stand there. 🎀)

To start the local HTTP test server used in the examples, run:

tclsh testservers/testserver.tcl

By default, this starts an HTTP server on http://127.0.0.1:8990/. 🌸

The path http://127.0.0.1:8990/tclcurl-man returns the HTML version of this manual page from doc/tclcurl.html, which makes it a super convenient target for a basic GET example. No cap. ✨

🌈 BASIC HTTP GET

The file examples/http_get.tcl contains a minimal HTTP GET example. It performs a simple request, stores the response body in a Tcl variable, and prints both the HTTP response code and the size of the returned document. Main character behavior, honestly. 👑

If the request succeeds, rc is 0, responsecode is 200, and body contains the HTML document returned by the server. Periodt. 💅

💜 AUTHORS

  • Andres Garcia Garcia
  • Massimo Manghi

👑 SEE ALSO

aaaand that's the whole page, bestie!! 🎉 You just read all of TclCurl(n) — from TclCurl 8.0.3, dated 15 May 2026. Go forth and curl responsibly, you absolute icon. 🦋💖✨

📦 where this page comes from