1 <HTML><HEAD><TITLE>Manpage of TclCurl</TITLE>
4 Section: Easy inteface (3)<BR>Updated: 03 October 2011<BR>
5 <A NAME="lbAB"> </A>
9 TclCurl: - get a URL with FTP, FTPS, HTTP, HTTPS, SCP, SFTP, TFTP, TELNET, DICT, FILE, LDAP,
10 LDAPS, IMAP, IMAPS, POP, POP3, SMTP, SMTPS and gopher syntax.
11 <A NAME="lbAC"> </A>
17 <I>curlHandle</I><B> configure </B><I>?options?</I>
20 <I>curlHandle</I><B> perform</B>
23 <I>curlHandle</I><B> getinfo </B><I>curlinfo_option</I>
26 <I>curlhandle</I><B> cleanup</B>
29 <I>curlhandle</I><B> reset</B>
32 <I>curlHandle</I><B> duhandle</B>
35 <I>curlHandle</I><B> pause</B>
38 <I>curlHandle</I><B> resume</B>
41 <B>curl::transfer</B><I> ?options?</I>
47 <B>curl::escape </B><I>url</I>
50 <B>curl::unescape </B><I>url</I>
53 <B>curl::curlConfig </B><I>option</I>
56 <B>curl::versioninfo </B><I>option</I>
59 <B>curl::easystrerror </B><I>errorCode</I>
62 <A NAME="lbAD"> </A>
65 The TclCurl extension gives Tcl programmers access to the <a href="http://curl.haxx.se/libcurl/">libcurl</a>
66 library written by <a href="http://daniel.haxx.se/">Daniel Stenberg</a>, with it you can download urls,
67 upload them and many other neat tricks.
69 <A NAME="lbAE"> </A>
72 This procedure must be the first one to call, it returns a
75 that you need to use to invoke TclCurl procedures. The init calls intializes
76 curl and this call MUST have a corresponding call to
79 when the operation is completed.
80 You should perform all your sequential file transfers using the same
81 curlHandle. This enables TclCurl to use persistant connections when
90 <A NAME="lbAF"> </A>
91 <H2>curlHandle configure ?options?</H2>
96 is called to set the options for the transfer. Most operations in TclCurl
97 have default actions, and by using the appropriate options you can
98 make them behave differently (as documented). All options are set with
99 the <I>option</I> followed by a parameter.
103 the options set with this procedure are valid for the
104 forthcoming data transfers that are performed when you invoke
108 The options are not reset between transfers (except where noted), so if
109 you want subsequent transfers with different options, you must change them
110 between the transfers. You can optionally reset all options back to the internal
111 default with <B>curlHandle reset</B>.
115 is the return code from the
124 <A NAME="lbAG"> </A>
125 <H2>Behaviour options</H2>
132 Set the parameter to 1 to get the library to display a lot of verbose
133 information about its operations. Very useful for libcurl and/or protocol
134 debugging and understanding.
136 You hardly ever want this set in production use, you will almost always want
137 this when you debug/report problems. Another neat option for debugging is
144 A 1 tells the extension to include the headers in the body output. This is
145 only relevant for protocols that actually have headers preceding the data (like HTTP).
147 <DT><B>-noprogress</B>
150 A 1 tells the extension to turn on the progress meter
151 completely. It will also prevent the <I>progessproc</I> from getting called.
156 A 1 tells TclCurl not use any functions that install signal
157 handlers or any functions that cause signals to be sent to the process. This
158 option is mainly here to allow multi-threaded unix applications to still
159 set/use all timeout options etc, without risking getting signals.
161 If this option is set and libcurl has been built with the standard name resolver,
162 timeouts will not occur while the name resolve takes place. Consider building
163 libcurl with c-ares support to enable asynchronous DNS lookups, which enables
164 nice timeouts for name resolves without signals.
166 Setting <I>nosignal</I> to 1 makes libcurl NOT ask the system to ignore
167 SIGPIPE signals, which otherwise are sent by the system when trying to send
168 data to a socket which is closed in the other end. libcurl makes an effort to
169 never cause such SIGPIPEs to trigger, but some operating systems have no way
170 to avoid them and even on those that have there are some corner cases when
171 they may still happen, contrary to our desire. In addition, using
172 <I>ntlm_Wb</I> authentication could cause a SIGCHLD signal to be raised.
177 Set this option to 1 if you want to transfer multiple files according to a
178 file name pattern. The pattern can be specified as part of the
179 <B>-url</B> option, using an fnmatch-like pattern (Shell Pattern
180 Matching) in the last part of URL (file name).
182 By default, TClCurl uses its internal wildcard matching implementation. You
183 can provide your own matching function by the <B>-fnmatchproc</B> option.
185 This feature is only supported by the FTP download for now.
187 A brief introduction of its syntax follows:
191 ftp://example.com/some/path/*.txt (for all txt's from the root directory)
197 <DT>? - QUESTION MARK<DD>
198 Question mark matches any (exactly one) character.
200 ftp://example.com/some/path/photo?.jpeg
206 <DT>[ - BRACKET EXPRESSION<DD>
207 The left bracket opens a bracket expression. The question mark and asterisk have
208 no special meaning in a bracket expression. Each bracket expression ends by the
209 right bracket and matches exactly one character. Some examples follow:
211 <B>[a-zA-Z0-9]</B> or <B>[f-gF-G]</B> - character interval
213 <B>[abc]</B> - character enumeration
215 <B>[^abc]</B> or <B>[!abc]</B> - negation
217 <B>[[:</B><I>name</I><B>:]]</B> class expression. Supported classes are
218 <B>alnum</B>,<B>lower</B>, <B>space</B>, <B>alpha</B>, <B>digit</B>, <B>print</B>,
219 <B>upper</B>, <B>blank</B>, <B>graph</B>, <B>xdigit</B>.
221 <B>[][-!^]</B> - special case - matches only '-', ']', '[', '!' or '^'. These
222 characters have no special purpose.
224 <B>[\[\]\\]</B> - escape syntax. Matches '[', ']' or '\'.
226 Using the rules above, a file name pattern can be constructed:
228 ftp://example.com/some/path/[a-z[:upper:]\\].jpeg
236 <A NAME="lbAH"> </A>
237 <H2>Callback options</H2>
241 <DT><B>-writeproc</B>
244 Use it to set a Tcl procedure that will be invoked by TclCurl as soon as
245 there is received data that needs to be saved. The procedure will receive
246 a single parameter with the data to be saved.
248 NOTE: you will be passed as much data as possible in all invokes, but you
249 cannot possibly make any assumptions. It may be nothing if the file is
250 empty or it may be thousands of bytes.
255 File in which the transfered data will be saved.
260 Sets a Tcl procedure to be called by TclCurl as soon as it needs to read
261 data in order to send it to the peer. The procedure has to take one
262 parameter, which will contain the maximun numbers of bytes to read. It
263 should return the actual number of bytes read, or '0' if you want to
266 If you stop the current transfer by returning 0 "pre-maturely" (i.e before
267 the server expected it, like when you've said you will upload N bytes and
268 you upload less than N bytes), you may experience that the server "hangs"
269 waiting for the rest of the data that won't come.
271 Bugs: when doing TFTP uploads, you must return the exact amount of data
272 that the callback wants, or it will be considered the final packet by the
273 server end and the transfer will end there.
278 File from which the data will be transfered.
280 <DT><B>-progressproc</B>
283 Name of the Tcl procedure that will invoked by TclCurl with a frequent
284 interval during operation (roughly once per second or sooner), no matter if data
285 is being transfered or not. Unknown/unused
286 argument values passed to the callback will be set to zero (like if you
287 only download data, the upload size will remain 0), the prototype of the
290 <B>proc ProgressCallback {dltotal dlnow ultotal ulnow}</B>
293 In order to this option to work you have to set the <B>noprogress</B>
294 option to '0'. Setting this option to the empty string will restore the
295 original progress function.
297 If you transfer data with the multi interface, this procedure will not be
298 called during periods of idleness unless you call the appropriate procedure
299 that performs transfers.
301 You can pause and resume a transfer from within this procedure using the
302 <B>pause</B> and <B>resume</B> commands.
304 <DT><B>-writeheader</B>
307 Pass a the file name to be used to write the header part of the received data to.
308 The headers are guaranteed to be written one-by-one to this file and
309 only complete lines are written. Parsing headers should be easy enough using
312 See also the headervar option to get the headers into an array.
314 <DT><B>-debugproc</B>
317 Name of the procedure that will receive the debug data produced by the
320 option, it should match the following prototype:
322 <B>debugProc {infoType data}</B>
325 where <B>infoType</B> specifies what kind of information it is (0 text,
326 1 incoming header, 2 outgoing header, 3 incoming data, 4 outgoing data,
327 5 incoming SSL data, 6 outgoing SSL data).
329 <DT><B>-chunkbgnproc</B>
332 Name of the procedure that will be called before a file will be transfered by
333 ftp, it should match the following prototype:
335 <B>ChunkBgnProc {remains}</B>
339 Where remains is the number of files left to be transfered (or skipped)
341 This callback makes sense only when using the <B>-wildcard</B> option.
343 <DT><B>-chunkbgnvar</B>
346 Name of the variable in the global scope that will contain the data of the file about
347 to be transfered. If you don't use this option '::fileData' will be used.
349 The available data is: filename, filetype (file, directory, symlink, device block, device char,
350 named pipe, socket, door or error if it couldn't be identified), time, perm, uid, gid,
351 size, hardlinks and flags.
353 <DT><B>-chunkendproc</B>
356 Name of the procedure that will be called after a file is transfered (or skipped)
357 by ftp, it should match the following prototype:
359 <B>ChunkEndProc {}</B>
362 It should return '0' if everyhting is fine and '1' if some error occurred.
364 <DT><B>-fnmatchProc</B>
367 Name of the procedure that will be called instead of the internal wildcard
368 matching function, it should match the following prototype:
370 <B>FnMatchProc {pattern string}</B>
373 Returns '0' if it matches, '1' if it doesn't.
376 <A NAME="lbAI"> </A>
377 <H2>Error Options</H2>
381 <DT><B>-errorbuffer</B>
384 Pass a variable name where TclCurl may store human readable error
385 messages in. This may be more helpful than just the return code from the
391 Pass a file name as parameter. This is the stream to use internally instead
392 of stderr when reporting errors.
393 <DT><B>-failonerror</B>
396 A 1 parameter tells the extension to fail silently if the HTTP code
397 returned is equal or larger than 400. The default action would be to return
398 the page normally, ignoring that code.
400 This method is not fail-safe and there are occasions where non-successful response
401 codes will slip through, especially when authentication is involved
402 (response codes 401 and 407).
404 You might get some amounts of headers transferred before this situation is detected,
405 like for when a "100-continue" is received as a response to a POST/PUT and a 401
406 or 407 is received immediately afterwards.
409 <A NAME="lbAJ"> </A>
410 <H2>Network options</H2>
417 The actual URL to deal with.
419 If the given URL lacks the protocol part ("http://" or "ftp://" etc), it will
420 attempt to guess which protocol to use based on the given host name. If the
421 given protocol of the set URL is not supported, TclCurl will return the
422 <B>unsupported protocol</B> error when you call <B>perform</B>. Use
423 <B>curl::versioninfo</B> for detailed info on which protocols are supported.
425 Starting with version 7.22.0, the fragment part of the URI will not be send as
426 part of the path, which was the case previously.
428 <B>NOTE</B>: this is the one option required to be set before <B>perform</B> is called.
430 <DT><B>-protocols</B>
433 Pass a list in lowecase of protocols to limit what protocols TclCurl may use in the transfer. This
434 allows you to have a TclCurl built to support a wide range of protocols but still limit
435 specific transfers to only be allowed to use a subset of them.
437 Accepted protocols are 'http', 'https', 'ftp', 'ftps', 'scp', 'sftp', 'telnet', 'ldap',
441 <DT><B>-redirprotocols</B>
444 Pass a list in lowercase of accepted protocols to limit what protocols TclCurl may use in a transfer
445 that it follows to in a redirect when <B>-followlocation</B> is enabled. This allows you
446 to limit specific transfers to only be allowed to use a subset of protocols in redirections.
448 By default TclCurl will allow all protocols except for FILE and SCP. This is a difference
449 compared to pre-7.19.4 versions which unconditionally would follow to all protocols supported.
454 If you need to use a http proxy to access the outside world, set the
455 proxy string with this option. To specify port number in this string,
456 append :[port] to the end of the host name. The proxy string may be
457 prefixed with [protocol]:// since any such prefix will be ignored.
459 When you tell the extension to use a HTTP proxy, TclCurl will
460 transparently convert operations to HTTP even if you specify a FTP
461 URL etc. This may have an impact on what other features of the library
465 and similar FTP specifics that will not work unless you tunnel through
466 the HTTP proxy. Such tunneling is activated with
470 TclCurl respects the environment variables http_proxy, ftp_proxy,
471 all_proxy etc, if any of those are set. The use of this option does
472 however override any possibly set environment variables.
474 Setting the proxy string to "" (an empty string) will explicitly disable
475 the use of a proxy, even if there is an environment variable set for it.
477 The proxy host string can be specified the exact same way as the proxy
478 environment variables, include protocol prefix (<A HREF="http://)">http://)</A> and embedded
481 Since 7.22.0, the proxy string may be specified with a protocol:// prefix to
482 specify alternative proxy protocols. Use socks4://, socks4a://, socks5:// or
483 socks5h:// (the last one to enable socks5 and asking the proxy to do the resolving)
484 to request the specific SOCKS version
485 to be used. No protocol specified, http:// and all others will be treated as
488 <DT><B>-proxyport</B>
491 Use this option to set the proxy port to use unless it is specified in
492 the proxy string by <B>-proxy</B>. If not specified, TclCurl will default
493 -to using port 1080 for proxies.
495 <DT><B>-proxytype</B>
498 Pass the type of the proxy. Available options are 'http', 'http1.0', 'socks4', 'socks4a',
499 <BLOCKQUOTE>man2html: unable to open or read file
504 If you set it to <I>http1.0</I>, it will only affect how libcurl speaks to a proxy
505 when CONNECT is used. The HTTP version used for "regular" HTTP requests is instead
506 controled with <I>httpversion</I>.
511 Pass a string, a comma-separated list of hosts which do not use a proxy, if one
512 is specified. The only wildcard is a single * character, which matches all hosts,
513 and effectively disables the proxy. Each name in this list is matched as either
514 a domain which contains the hostname, or the hostname itself. For example, local.com
515 would match local.com, local.com:80, and www.local.com, but not http://www.notlocal.com.
517 <DT><B>-httpproxytunnel</B>
520 Set the parameter to 1 to get the extension to tunnel all non-HTTP
521 operations through the given HTTP proxy. Do note that there is a big
522 difference between using a proxy and tunneling through it. If you don't know what
523 this means, you probably don't want this tunnel option.
525 <DT><B>-socks5gssapiservice</B>
528 Pass thee name of the service. The default service name for a SOCKS5 server is
529 rcmd/server-fqdn. This option allows you to change it.
531 <DT><B>-socks5gssapinec</B>
534 Pass a 1 to enable or 0 to disable. As part of the gssapi negotiation a protection
535 mode is negotiated. The rfc1961 says in section 4.3/4.4 it should be protected, but
536 the NEC reference implementation does not. If enabled, this option allows the
537 unprotected exchange of the protection mode negotiation.
539 <DT><B>-interface</B>
542 Pass the interface name to use as outgoing
543 network interface. The name can be an interface name, an IP address or a host
546 <DT><B>-localport</B>
549 This sets the local port number of the socket used for connection. This can
550 be used in combination with <B>-interface</B> and you are recommended to use
551 <B>localportrange</B> as well when this is set. Valid port numbers
554 <DT><B>-localportrange</B>
557 This is the number of attempts TclCurl should do to find a working local port
558 number. It starts with the given <B>-localport</B> and adds
559 one to the number for each retry. Setting this value to 1 or below will make
560 TclCurl do only one try for each port number. Port numbers by nature
561 are a scarce resource that will be busy at times so setting this value to something
562 too low might cause unnecessary connection setup failures.
564 <DT><B>-dnscachetimeout</B>
567 Pass the timeout in seconds. Name resolves will be kept in memory for this number
568 of seconds. Set to '0' to completely disable caching, or '-1' to make the
569 cached entries remain forever. By default, TclCurl caches this info for 60 seconds.
571 The name resolve functions of various libc implementations don't re-read name
572 server information unless explicitly told so (for example, by calling
573 <BR> <I>res_init(3)</I>). This may cause TclCurl to keep using the older server even
574 if DHCP has updated the server info, and this may look like a DNS cache issue.
576 <DT><B>-dnsuseglobalcache</B>
579 If the value passed is 1, it tells TclCurl to use a global DNS cache that
580 will survive between curl handles creations and deletions. This is not thread-safe
581 as it uses a global varible.
583 <B>WARNING:</B> this option is considered obsolete. Stop using it. Switch over
584 to using the share interface instead! See <I>tclcurl_share</I>.
586 <DT><B>-buffersize</B>
589 Pass your prefered size for the receive buffer in TclCurl. The main point of this
590 would be that the write callback gets called more often and with smaller chunks.
591 This is just treated as a request, not an order. You cannot be guaranteed to
592 actually get the given size.
598 Pass the number specifying what remote port to connect to, instead of the one specified
599 in the URL or the default port for the used protocol.
601 <DT><B>-tcpnodelay</B>
605 Pass a number to specify whether the TCP_NODELAY option should be set or cleared (1 = set, 0 = clear).
606 The option is cleared by default. This will have no effect after the connection has been established.
608 Setting this option will disable TCP's Nagle algorithm. The purpose of this algorithm is to try to
609 minimize the number of small packets on the network (where "small packets" means TCP segments less
610 than the Maximum Segment Size (MSS) for the network).
612 Maximizing the amount of data sent per TCP segment is good because it amortizes the overhead of the
613 send. However, in some cases (most notably telnet or rlogin) small segments may need to be sent without
614 delay. This is less efficient than sending larger amounts of data at a time, and can contribute to
615 congestion on the network if overdone.
617 <DT><B>-addressscope</B>
620 Pass a number specifying the scope_id value to use when connecting to IPv6 link-local or site-local
624 <A NAME="lbAK"> </A>
625 <H2>Names and Passwords options</H2>
632 A 1 parameter tells the extension to scan your
635 file to find user name and password for the remote site you are about to
636 access. Do note that TclCurl does not verify that the file has the correct
637 properties set (as the standard unix ftp client does), and that only machine
638 name, user name and password is taken into account (init macros and similar
639 things are not supported).
641 You can set it to the following values:
647 The use of your ~/.netrc file is optional, and information in the URL is to
648 be preferred. The file will be scanned with the host and user name (to find
649 the password only) or with the host only, to find the first user name and
650 password after that machine, which ever information is not specified in
653 Undefined values of the option will have this effect.
657 The extension will ignore the file and use only the information in the URL.
662 This value tells the library that use of the file is required, to ignore
663 the information in the URL, and to search the file with the host only.
668 <DT><B>-netrcfile</B>
671 Pass a string containing the full path name to the file you want to use as .netrc
672 file. For the option to work, you have to set the <B>netrc</B> option to
673 <B>required</B>. If this option is omitted, and <B>netrc</B> is set, TclCurl
674 will attempt to find the a .netrc file in the current user's home directory.
679 Pass a string as parameter, which should be [username]:[password] to use for
680 the connection. Use <B>-httpauth</B> to decide authentication method.
682 When using NTLM, you can set domain by prepending it to the user name and
683 separating the domain and name with a forward (/) or backward slash (\). Like
684 this: "domain/user:password" or "domain\user:password". Some HTTP servers (on
685 Windows) support this style even for Basic authentication.
687 When using HTTP and <B>-followlocation</B>, TclCurl might perform several
688 requests to possibly different hosts. TclCurl will only send this user and
689 password information to hosts using the initial host name (unless
690 <B>-unrestrictedauth</B> is set), so if TclCurl follows locations to other
691 hosts it will not send the user and password to those. This is enforced to
692 prevent accidental information leakage.
694 <DT><B>-proxyuserpwd</B>
697 Pass a string as parameter, which should be [username]:[password] to use for
698 the connection to the HTTP proxy.
703 Pass a string with the user name to use for the transfer. It sets the user name
704 to be used in protocol authentication. You should not use this option together
705 with the (older) <B>-userpwd</B> option.
707 In order to specify the password to be used in conjunction with the user name
708 use the <B>-password</B> option.
713 Pass a string with the password to use for the transfer.
715 It should be used in conjunction with the <B>-username</B> option.
717 <DT><B>-proxyusername</B>
720 Pass a string with the user name to use for the transfer while connecting to Proxy.
722 It should be used in same way as the <B>-proxyuserpwd</B> is used, except that it
723 allows the username to contain a colon, like in the following example:
724 "sip:user@example.com".
726 Note the <B>-proxyusername</B> option is an alternative way to set the user name
727 while connecting to Proxy. It doesn't make sense to use them together.
729 <DT><B>-proxypassword</B>
732 Pass a string with the password to use for the transfer while connecting to Proxy. It
733 is meant to use together with <B>-proxyusername</B>.
738 Set to the authentication method you want, the available ones are:
744 HTTP Basic authentication. This is the default choice, and the only
745 method that is in widespread use and supported virtually everywhere.
746 It sends the user name and password over the network in plain text,
747 easily captured by others.
752 HTTP Digest authentication. Digest authentication is a more secure
753 way to do authentication over public networks than the regular
754 old-fashioned Basic method.
759 HTTP Digest authentication with an IE flavor. TclCurl will use a special
760 "quirk" that IE is known to have used before version 7 and that some
761 servers require the client to use.
763 <DT><B>gssnegotiate</B>
766 HTTP GSS-Negotiate authentication. The GSS-Negotiate method, also known as
767 plain "Negotiate",was designed by Microsoft and is used in their web
768 applications. It is primarily meant as a support for Kerberos5 authentication
769 but may be also used along with another authentication methods.
774 HTTP NTLM authentication. A proprietary protocol invented and used by Microsoft.
775 It uses a challenge-response and hash concept similar to Digest, to prevent the
776 password from being eavesdropped.
781 NTLM delegating to winbind helper. Authentication is performed by a separate
782 binary application that is executed when needed. The name of the application is
783 specified at libcurl's compile time but is typically /usr/bin/ntlm_auth.
785 Note that libcurl will fork when necessary to run the winbind application and kill
786 it when complete, calling waitpid() to await its exit when done. On POSIX operating
787 systems, killing the process will cause a SIGCHLD signal to be raised
788 (regardless of whether <B>-nosignal</B> is set). This behavior is subject to change
789 in future versions of libcurl.
794 TclCurl will automatically select the one it finds most secure.
799 It may use anything but basic, TclCurl will automaticly select the
800 one it finds most secure.
805 <DT>Use it to tell TclCurl which authentication method(s) you want it to use for TLS authentication.<DD>
808 <DT><DT><B>tlsauthsrp</B>
812 TLS-SRP authentication. Secure Remote Password authentication for TLS is
813 defined in RFC 5054 and provides mutual authentication if both sides have a
814 shared secret. To use TLS-SRP, you must also set the
815 <B>-tlsauthusername</B> and <B>-tlsauthpassword</B> options.
817 You need to build libcurl with GnuTLS or OpenSSL with TLS-SRP support for this
823 <DT><B>-tlsauthusername</B>
826 Pass a string with the username to use for the TLS authentication method specified
827 with the <B>-tlsauthtype</B> option. Requires that the <B>-tlsauthpassword</B> option
830 <DT><B>-tlsauthpassword</B>
833 Pass a string with the password to use for the TLS authentication method specified
834 with the <B>-tlsauthtype</B> option. Requires that the <B>-tlsauthusername</B> option
837 <DT><B>-proxyauth</B>
840 Use it to tell TclCurl which authentication method(s) you want it to use for
841 your proxy authentication. Note that for some methods, this will induce an
842 extra network round-trip. Set the actual name and password with the
843 <B>proxyuserpwd</B> option.
845 The methods are those listed above for the <B>httpauth</B> option. As of this
846 writing, only Basic and NTLM work.
849 <A NAME="lbAL"> </A>
850 <H2>HTTP options</H2>
854 <DT><B>-autoreferer</B>
857 Pass an 1 parameter to enable this. When enabled, TclCurl will
858 automatically set the Referer: field in requests where it follows a Location:
864 Sets the contents of the Accept-Encoding: header sent in an HTTP
865 request, and enables decoding of a response when a Content-Encoding:
866 header is received. Three encodings are supported: <I>identity</I>,
867 which does nothing, <I>deflate</I> which requests the server to
868 compress its response using the zlib algorithm, and <I>gzip</I> which
869 requests the gzip algorithm. Use <I>all</I> to send an
870 Accept-Encoding: header containing all supported encodings.
872 This is a request, not an order; the server may or may not do it. This
873 option must be set or else any unsolicited
874 encoding done by the server is ignored. See the special file
875 lib/README.encoding in libcurl docs for details.
877 <DT><B>-transferencoding</B>
880 Adds a request for compressed Transfer Encoding in the outgoing HTTP
881 request. If the server supports this and so desires, it can respond with the
882 HTTP resonse sent using a compressed Transfer-Encoding that will be
883 automatically uncompressed by TclCurl on receival.
885 Transfer-Encoding differs slightly from the Content-Encoding you ask for with
886 <B>-encoding</B> in that a Transfer-Encoding is strictly meant to
887 be for the transfer and thus MUST be decoded before the data arrives in the
888 client. Traditionally, Transfer-Encoding has been much less used and supported
889 by both HTTP clients and HTTP servers.
891 <DT><B>-followlocation</B>
894 An 1 tells the library to follow any
895 <B>Location: header</B>
897 that the server sends as part of a HTTP header.
899 This means that the extension will re-send the same request on the new location
900 and follow new <B>Location: headers</B> all the way until no more such headers are
901 returned. <B>-maxredirs</B> can be used to limit the number of redirects
904 Since 7.19.4, TclCurl can limit what protocols it will automatically follow.
905 The accepted protocols are set with <B>-redirprotocols</B> and it excludes the FILE
908 <DT><B>-unrestrictedauth</B>
911 An 1 parameter tells the extension it can continue
912 to send authentication (user+password) when following
913 locations, even when hostname changed. Note that this
914 is meaningful only when setting <B>-followlocation</B>.
916 <DT><B>-maxredirs</B>
919 Sets the redirection limit. If that many redirections have been followed,
920 the next redirect will cause an error. This option only makes sense if the
921 <B>-followlocation</B> option is used at the same time. Setting the limit
922 to 0 will make libcurl refuse any redirect. Set it to -1 for an infinite
923 number of redirects (which is the default)
928 Controls how TclCurl acts on redirects after POSTs that get a 301 or 302 response back.
929 A "301" as parameter tells the TclCurl to respect RFC 2616/10.3.2 and not convert POST
930 requests into GET requests when following a 301 redirection. Passing a "302" makes
931 TclCurl maintain the request method after a 302 redirect. "all" is a convenience string
932 that activates both behaviours.
934 The non-RFC behaviour is ubiquitous in web browsers, so the extension does the conversion
935 by default to maintain consistency. However, a server may require a POST to remain a POST
936 after such a redirection.
938 This option is meaningful only when setting <B>-followlocation</B>
940 The option used to be known as <B>-post301</B>, which should still work but is know
946 An 1 parameter tells the extension to use HTTP PUT a file. The file to put
947 must be set with <B>-infile</B> and <B>-infilesize</B>.
949 This option is deprecated starting with version 0.12.1, you should use <B>-upload</B>.
951 This option does not limit how much data TclCurl will actually send, as that is
952 controlled entirely by what the read callback returns.
957 An 1 parameter tells the library to do a regular HTTP post. This is a
958 normal application/x-www-form-urlencoded kind, which is the most commonly used
959 one by HTML forms. See the <B>-postfields</B> option for how to specify the
960 data to post and <B>-postfieldsize</B> about how to set the data size.
962 Use the <B>-postfields</B> option to specify what data to post and <B>-postfieldsize</B>
963 to set the data size. Optionally, you can provide data to POST using the <B>-readproc</B>
966 You can override the default POST Content-Type: header by setting your own with
969 Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header.
970 You can disable this header with <B>-httpheader</B> as usual.
972 If you use POST to a HTTP 1.1 server, you can send data without knowing the
973 size before starting the POST if you use chunked encoding. You enable this
974 by adding a header like "Transfer-Encoding: chunked" with <B>-httpheader</B>.
975 With HTTP 1.0 or without chunked transfer, you must specify the size in the
978 When setting <B>post</B> to an 1 value, it will automatically set
981 NOTE: if you have issued a POST request and want to make a HEAD or GET instead, you must
982 explicitly pick the new request type using <B>-nobody</B> or <B>-httpget</B> or similar.
984 <DT><B>-postfields</B>
987 Pass a string as parameter, which should be the full data to post in a HTTP
988 POST operation. You must make sure that the data is formatted the way you
989 want the server to receive it. TclCurl will not convert or encode it for you.
990 Most web servers will assume this data to be url-encoded.
992 This is a normal application/x-www-form-urlencoded kind,
993 which is the most commonly used one by HTML forms.
995 If you want to do a zero-byte POST, you need to set
996 <B>-postfieldsize</B> explicitly to zero, as simply setting
997 <B>-postfields</B> to NULL or "" just effectively disables the sending
998 of the specified string. TclCurl will instead assume that the POST
999 data will be send using the read callback!
1001 Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header.
1002 You can disable this header with <B>-httpheader</B> as usual.
1004 <B>Note</B>: to make multipart/formdata posts (aka rfc1867-posts), check out
1005 <B>-httppost</B> option.
1007 <DT><B>-postfieldsize</B>
1010 If you want to post data to the server without letting TclCurl do a strlen()
1011 to measure the data size, this option must be used. Also, when this option is
1012 used, you can post fully binary data which otherwise is likely to fail. If
1013 this size is set to zero, the library will use strlen() to get the data
1016 <DT><B>-httppost</B>
1019 Tells TclCurl you want a multipart/formdata HTTP POST to be made and you
1020 instruct what data to pass on to the server through a
1024 <B>This is the only case where the data is reset after a transfer.</B>
1026 First, there are some basics you need to understand about multipart/formdata
1027 posts. Each part consists of at least a <B>NAME</B> and a <B>CONTENTS</B> part. If the part
1028 is made for file upload, there are also a stored <B>CONTENT-TYPE</B> and a
1029 <B>FILENAME</B>. Below, we'll discuss on what options you use to set these
1030 properties in the parts you want to add to your post.
1032 The list must contain a <B>'name'</B> tag with the name of the section followed
1033 by a string with the name, there are three tags to indicate the value of
1034 the section: <B>'value'</B> followed by a string with the data to post, <B>'file'</B>
1035 followed by the name of the file to post and <B>'contenttype'</B> with the
1036 type of the data (text/plain, image/jpg, ...), you can also indicate a <I>false</I>
1037 file name with <B>'filename'</B>, this is useful in case the server checks if the given
1038 file name is valid, for example, by testing if it starts with 'c:\' as any real file
1039 name does or if you want to include the full path of the file to post. You can also post
1040 the content of a variable as if it were a file with the options <B>'bufferName'</B> and
1041 <B>'buffer'</B> or use <B>'filecontent'</B> followed by a file name to read that file and
1042 use the contents as data.
1044 Should you need to specify extra headers for the form POST section, use
1045 <B>'contentheader</B>' followed by a list with the headers to post.
1047 Please see 'httpPost.tcl' and 'httpBufferPost.tcl' for examples.
1049 If TclCurl can't set the data to post an error will be returned:
1050 <DL COMPACT><DT><DD>
1055 If the memory allocation fails.
1059 If one option is given twice for one form.
1063 If an empty string was given.
1067 If an unknown option was used.
1071 If the some form info is not complete (or error)
1075 If an illegal option is used in an array.
1079 TclCurl has no http support.
1087 Pass a string as parameter. It will be used to set the
1090 header in the http request sent to the remote server. This can be used to
1091 fool servers or scripts. You can also set any custom header with
1095 <DT><B>-useragent</B>
1098 Pass a string as parameter. It will be used to set the
1101 header in the http request sent to the remote server. This can be used to fool
1102 servers or scripts. You can also set any custom header with
1106 <DT><B>-httpheader</B>
1112 with the HTTP headers to pass to the server in your request.
1113 If you add a header that is otherwise generated
1114 and used by TclCurl internally, your added one will be used instead. If you
1115 add a header with no contents as in 'Accept:', the internally used header will
1116 just get disabled. Thus, using this option you can add new headers, replace
1117 and remove internal headers.
1119 The headers included in the linked list must not be CRLF-terminated, because
1120 TclCurl adds CRLF after each header item. Failure to comply with this will
1121 result in strange bugs because the server will most likely ignore part of the
1122 headers you specified.
1124 The first line in a request (containing the method, usually a GET or POST) is
1125 not a header and cannot be replaced using this option. Only the lines
1126 following the request-line are headers. Adding this method line in this list
1127 of headers will only cause your request to send an invalid header.
1129 <B>NOTE</B>:The most commonly replaced headers have "shortcuts" in the options:
1130 <B>cookie, useragent,</B>
1136 <DT><B>-http200aliases</B>
1139 Pass a list of aliases to be treated as valid HTTP 200 responses. Some servers
1140 respond with a custom header response line. For example, IceCast servers respond
1141 with "ICY 200 OK". By including this string in your list of aliases, the
1142 response will be treated as a valid HTTP header line such as "HTTP/1.0 200 OK".
1144 <B>NOTE</B>:The alias itself is not parsed for any version strings. Before version
1145 7.16.3, TclCurl used the value set by option <B>httpversion</B>, but starting with
1146 7.16.3 the protocol is assumed to match HTTP 1.0 when an alias matched.
1151 Pass a string as parameter. It will be used to
1152 set a cookie in the http request. The format of the string should be
1154 what the cookie should contain.
1156 If you need to set mulitple cookies, you need to set them all using
1157 a single option and thus you need to concatenate them all in one single string.
1158 Set multiple cookies in one string like this: "name1=content1; name2=content2;"
1161 This option sets the cookie header explictly in the outgoing request(s).
1162 If multiple requests are done due to authentication, followed redirections or similar,
1163 they will all get this cookie passed on.
1165 Using this option multiple times will only make the latest string override
1168 <DT><B>-cookiefile</B>
1171 Pass a string as parameter. It should contain the name of your file holding
1172 cookie data. The cookie data may be in netscape cookie data format or just
1173 regular HTTP-style headers dumped to a file.
1175 Given an empty or non-existing file, this option will enable cookies for this
1176 curl handle, making it understand and parse received cookies and then use
1177 matching cookies in future requests.
1179 If you use this option multiple times, you add more files to read.
1181 <DT><B>-cookiejar</B>
1184 Pass a file name in which TclCurl will dump all internally known cookies
1186 <B>curlHandle cleanup</B>
1188 is called. If no cookies are known, no file will be created.
1189 Specify "-" to have the cookies written to stdout.
1191 Using this option also enables cookies for this session, so if you, for
1192 example, follow a location it will make matching cookies get sent accordingly.
1194 TclCurl will not and cannot report an error for this. Using '<B>verbose</B>'
1195 will get a warning to display, but that is the only visible feedback you get
1196 about this possibly lethal situation.
1198 <DT><B>-cookiesession</B>
1201 Pass an 1 to mark this as a new cookie "session". It will
1202 force TclCurl to ignore all cookies it is about to load that are "session
1203 cookies" from the previous session. By default, TclCurl always stores and
1204 loads all cookies, independent of whether they are session cookies are not.
1205 Session cookies are cookies without expiry date and they are meant to be
1206 alive and existing for this "session" only.
1208 <DT><B>-cookielist</B>
1211 Pass a string with a cookie. The cookie can be either in Netscape / Mozilla
1212 format or just regular HTTP-style header (Set-Cookie: ...) format. If the
1213 cookie engine was not enabled it will be enabled. Passing a
1214 magic string "ALL" will erase all known cookies while "FLUSH" will write
1215 all cookies known by TclCurl to the file specified by <B>-cookiejar</B>.
1220 If set to 1 forces the HTTP request to get back to GET, usable if
1221 POST, PUT or a custom request have been used previously with the
1224 When setting <B>httpget</B> to 1, <B>nobody</B> will automatically be set to 0.
1226 <DT><B>-httpversion</B>
1229 Set to one of the values decribed below, they force TclCurl to use the
1230 specific http versions. It should only be used if you really MUST do
1231 that because of a silly remote server.
1232 <DL COMPACT><DT><DD>
1237 We do not care about what version the library uses. TclCurl will use whatever
1242 Enforce HTTP 1.0 requests.
1246 Enforce HTTP 1.1 requests.
1250 Enforce HTTP version 2 requests.
1254 Enforce version 2 requests for HTTPS, version 1.1 for HTTP.
1255 <DT><B>2_PRIOR_KNOWLEDGE</B>
1258 Enforce HTTP 2 requests without performing HTTP/1.1 Upgrade first.
1263 <DT><B>-ignorecontentlength</B>
1266 Ignore the Content-Length header. This is useful for Apache 1.x (and similar
1267 servers) which will report incorrect content length for files over 2
1268 gigabytes. If this option is used, TclCurl will not be able to accurately
1269 report progress, and will simply stop the download when the server ends the
1272 <DT><B>-httpcontentdecoding</B>
1275 Set to zero to disable content decoding. If set to 1 it is enabled. Note however
1276 that TclCurl has no default content decoding but requires you to use <B>encoding</B> for that.
1278 <DT><B>-httptransferencoding</B>
1281 Set to zero to disable transfer decoding, if set to 1 it is enabled (default). TclCurl does
1282 chunked transfer decoding by default unless this option is set to zero.
1285 <A NAME="lbAM"> </A>
1286 <H2>SMTP options</H2>
1290 <DT><B>-mailfrom</B>
1293 Pass a string to specify the sender address in a mail when sending an SMTP mail with TclCurl.
1295 <DT><B>-mailrcpt</B>
1298 Pass a list of recipients to pass to the server in your SMTP mail request.
1300 Each recipient in SMTP lingo is specified with angle brackets (<>), but should you not use an
1301 angle bracket as first letter, TclCurl will assume you provide a single email address only and
1302 enclose that with angle brackets for you.
1305 <A NAME="lbAN"> </A>
1306 <H2>TFTP option</H2>
1310 <DT><B>tftpblksize</B>
1314 Specify the block size to use for TFTP data transmission. Valid range as per RFC 2348 is 8-65464 bytes.
1315 The default of 512 bytes will be used if this option is not specified. The specified block size will
1316 only be used pending support by the remote server. If the server does not return an option acknowledgement
1317 or returns an option acknowledgement with no blksize, the default of 512 bytes will be used.
1320 <A NAME="lbAO"> </A>
1321 <H2>FTP options</H2>
1328 Pass a string as parameter. It will be used to
1329 get the IP address to use for the ftp PORT instruction. The PORT instruction
1330 tells the remote server to connect to our specified IP address. The string may
1331 be a plain IP address, a host name, a network interface name (under unix) or
1332 just a '-' to let the library use your systems default IP address. Default FTP
1333 operations are passive, and thus will not use PORT.
1335 The address can be followed by a ':' to specify a port, optionally followed by a '-'
1336 o specify a port range. If the port specified is 0, the operating system will pick
1337 a free port. If a range is provided and all ports in the range are not available,
1338 libcurl will report CURLE_FTP_PORT_FAILED for the handle. Invalid port/range settings
1339 are ignored. IPv6 addresses followed by a port or portrange have to be in brackets.
1340 IPv6 addresses without port/range specifier can be in brackets.
1342 Examples with specified ports:
1344 <BR> eth0:0 192.168.1.2:32000-33000 curl.se:32123 [::1]:1234-4567
1346 You disable PORT again and go back to using the passive version by setting this option to
1352 Pass a <B>list</B> list with the FTP or SFTP commands to pass to the server prior to your
1353 ftp request. This will be done before any other FTP commands are issued (even
1354 before the CWD command).If you do not want to transfer any files, set
1355 <B>nobody</B> to '1' and <B>header</B> to '0'.
1357 Prefix the command with an asterisk (*) to make TclCurl continue even if the command
1358 fails as by default TclCurl will stop.
1360 Disable this operation again by setting an empty string to this option.
1362 Keep in mind the commands to send must be 'raw' ftp commands, for example, to
1363 create a directory you need to send <B>mkd Test</B>, not <B>mkdir Test</B>.
1365 Valid SFTP commands are: chgrp, chmod, chown, ln, mkdir, pwd, rename, rm,
1368 <DT><B>-postquote</B>
1371 Pass a <B>list</B> with the FTP commands to pass to the server after your
1372 ftp transfer request. If you do not want to transfer any files, set
1373 <B>nobody</B> to '1' and <B>header</B> to '0'.
1375 <DT><B>-prequote</B>
1378 Pass a <B>list</B> of FTP or SFTP commands to pass to the server after the
1379 transfer type is set.
1381 <DT><B>-dirlistonly</B>
1384 A 1 tells the library to just list the names of files in a
1385 directory, instead of doing a full directory listing that would include file
1386 sizes, dates etc. It works with both FTP and SFTP urls.
1388 This causes an FTP NLST command to be sent. Beware that some FTP servers list
1389 only files in their response to NLST, they might not include subdirectories
1392 Setting this option to 1 also implies a directory listing even if the URL
1393 doesn't end with a slash, which otherwise is necessary.
1395 Do NOT use this option if you also use <B>-wildcardmatch</B> as it will
1396 effectively break that feature.
1401 A 1 parameter tells the extension to append to the remote file instead of
1402 overwriting it. This is only useful when uploading to a ftp site.
1404 <DT><B>-ftpusepret</B>
1407 Set to 1 to tell TclCurl to use the EPRT (and LPRT) command when doing
1408 active FTP downloads (which is enabled by '<B>ftpport</B>'). Using EPRT means
1409 that it will first attempt to use EPRT and then LPRT before using PORT, if
1410 you pass zero to this option, it will not try using EPRT or LPRT, only plain PORT.
1412 <DT><B>-ftpuseepvs</B>
1415 Set to one to tell TclCurl to use the EPSV command when doing passive FTP
1416 downloads (which it always does by default). Using EPSV means that it will
1417 first attempt to use EPSV before using PASV, but if you pass a zero to this
1418 option, it will not try using EPSV, only plain PASV.
1420 <DT><B>-ftpusepret</B>
1424 Set to one to tell TclCurl to send a PRET command before PASV (and EPSV). Certain
1425 FTP servers, mainly drftpd, require this non-standard command for directory listings
1426 as well as up and downloads in PASV mode. Has no effect when using the active FTP
1429 <DT><B>-ftpcreatemissingdirs</B>
1432 If set to 1, TclCurl will attempt to create any remote directory that it
1433 fails to CWD into. CWD is the command that changes working directory.
1435 This setting also applies to SFTP-connections. TclCurl will attempt to create
1436 the remote directory if it can't obtain a handle to the target-location. The
1437 creation will fail if a file of the same name as the directory to create
1438 already exists or lack of permissions prevents creation.
1440 If set to 2, TclCurl will retry the CWD command again if the subsequent MKD
1441 command fails. This is especially useful if you're doing many simultanoeus
1442 connections against the same server and they all have this option enabled,
1443 as then CWD may first fail but then another connection does MKD before this
1444 connection and thus MKD fails but trying CWD works
1446 <DT><B>-ftpresponsetimeout</B>
1449 Causes TclCurl to set a timeout period (in seconds) on the amount of time that
1450 the server is allowed to take in order to generate a response message for a
1451 command before the session is considered hung. Note that while TclCurl is waiting
1452 for a response, this value overrides <B>timeout</B>. It is recommended that if used
1453 in conjunction with <B>timeout</B>, you set it to a value smaller than <B>timeout</B>.
1455 <DT><B>-ftpalternativetouser </B>
1458 Pass a string which will be used to authenticate if the usual FTP "USER user" and
1459 "PASS password" negotiation fails. This is currently only known to be required when
1460 connecting to Tumbleweed's Secure Transport FTPS server using client certificates for
1463 <DT><B>-ftpskippasvip</B>
1466 If set to 1, it instructs TclCurl not to use the IP address the
1467 server suggests in its 227-response to TclCurl's PASV command when TclCurl
1468 connects the data connection. Instead TclCurl will re-use the same IP address
1469 it already uses for the control connection. But it will use the port number
1470 from the 227-response.
1472 This option has no effect if PORT, EPRT or EPSV is used instead of PASV.
1474 <DT><B>-ftpsslauth</B>
1478 Pass TclCurl one of the values from below, to alter how TclCurl issues
1479 "AUTH TLS" or "AUTH SSL" when FTP over SSL is activated (see <B>-ftpssl</B>).
1481 You may need this option because of servers like <a href="http://bsdftpd-ssl.sc.ru/">BSDFTPD-SSL</A>
1482 which won't work properly when "AUTH SSL" is issued
1483 (although the server responds fine and everything) but requires "AUTH TLS"
1486 <DL COMPACT><DT><DD>
1491 Allows TclCurl to decide.
1495 Try "AUTH SSL" first, and only if that fails try "AUTH TLS".
1499 Try "AUTH TLS" first, and only if that fails try "AUTH SSL".
1504 <DT><B>-ftpsslccc </B>
1507 Set it to make TclCurl use CCC (Clear Command Channel). It shuts down the
1508 SSL/TLS layer after authenticating. The rest of the control channel
1509 communication will be unencrypted. This allows NAT routers to follow the
1510 FTP transaction. Possible values are:
1512 <DL COMPACT><DT><DD>
1517 Do not attempt to use CCC.
1521 Do not initiate the shutdown, wait for the server to do it. Do not send a reply.
1525 Initiate the shutdown and wait for a reply.
1530 <DT><B>-ftpaccount</B>
1533 Pass string (or "" to disable). When an FTP server asks for "account data" after
1534 user name and password has been provided, this data is sent off using the ACCT
1537 <DT><B>-ftpfilemethod</B>
1540 It allows three values:
1541 <DL COMPACT><DT><DD>
1546 The default, TclCurl will do a single CWD operation for each path part in the given
1547 URL. For deep hierarchies this means very many commands. This is how RFC1738 says it
1552 No CWD at all is done, TclCurl will do SIZE, RETR, STOR, etc and give a full path to
1554 <DT><B>singlecwd</B>
1557 Make one CWD with the full target directory and then operate on the file "normally".
1558 This is somewhat more standards compliant than 'nocwd' but without the full penalty of 'multicwd'.
1564 <A NAME="lbAP"> </A>
1565 <H2>Protocol options</H2>
1569 <DT><B>-transfertext</B>
1572 A 1 tells the extension to use ASCII mode for ftp transfers,
1573 instead of the default binary transfer. For win32 systems it does not set the
1574 stdout to binary mode. This option can be usable when transferring text data
1575 between systems with different views on certain characters, such as newlines
1578 <B>NOTE:</B> TclCurl does not do a complete ASCII conversion when doing ASCII
1579 transfers over FTP. This is a known limitation/flaw that nobody has
1580 rectified. TclCurl simply sets the mode to ascii and performs a standard
1583 <DT><B>-proxytransfermode</B>
1586 If set to 1, TclCurl sets the transfer mode (binary or ASCII) for FTP transfers
1587 done via an HTTP proxy, by appending ;type=a or ;type=i to the URL.
1588 Without this setting, or it being set to 0, the default, <B>-transfertext</B> has
1589 no effect when doing FTP via a proxy. Beware that not all proxies support this feature.
1594 If set to '1', TclCurl converts Unix newlines to CRLF newlines on transfers. Disable
1595 this option again by setting the value to '0'.
1600 Pass a string as parameter, which should contain the specified range you
1601 want. It should be in the format
1604 , where X or Y may be left out. HTTP
1605 transfers also support several intervals, separated with commas as in
1608 Using this kind of multiple intervals will cause the HTTP server to send the
1609 response document in pieces (using standard MIME separation techniques).
1611 Ranges only work on HTTP, FTP and FILE transfers.
1613 <DT><B>-resumefrom</B>
1616 Pass the offset in number of bytes that you want the transfer to start from.
1617 Set this option to 0 to make the transfer start from the beginning
1618 (effectively disabling resume).
1620 For FTP, set this option to -1 to make the transfer start from the end of the
1621 target file (useful to continue an interrupted upload).
1623 When doing uploads with FTP, the resume position is where in the local/source
1624 file TclCurl should try to resume the upload from and it will then append the
1625 source file to the remote target file.
1627 <DT><B>-customrequest</B>
1630 Pass a string as parameter. It will be used instead of GET or HEAD when doing
1631 the HTTP request. This is useful for doing DELETE or other more obscure HTTP
1632 requests. Do not do this at will, make sure your server supports the command first.
1634 Note that TclCurl will still act and assume the keyword it would use if you
1635 do not set your custom and it will act according to that. Thus, changing this
1636 to a HEAD when TclCurl otherwise would do a GET might cause TclCurl to act funny,
1637 and similar. To switch to a proper HEAD, use <B>-nobody</B>, to switch to a proper
1638 POST, use <B>-post</B> or <B>-postfields</B> and so on.
1640 <DT><B>-filetime</B>
1643 If you pass a 1, TclCurl will attempt to get the
1644 modification date of the remote document in this operation. This requires that
1645 the remote server sends the time or replies to a time querying command. The
1646 getinfo procedure with the
1649 argument can be used after a transfer to extract the received time (if any).
1654 A 1 tells the library not to include the body-part in the
1655 output. This is only relevant for protocols that have a separate header and
1656 body part. On HTTP(S) servers, this will make TclCurl do a HEAD request.
1658 To change request to GET, you should use <B>httpget</B>. Change request
1659 to POST with <B>post</B> etc.
1661 <DT><B>-infilesize</B>
1664 When uploading a file to a remote site, this option should be used to tell
1665 TclCurl what the expected size of the infile is.
1667 This option is mandatory for uploading using SCP.
1672 A 1 tells the library to prepare for an upload. The
1673 <B>-infile</B> and <B>-infilesize</B> options are also interesting for uploads.
1674 If the protocol is HTTP, uploading means using the PUT request unless you tell
1677 Using PUT with HTTP 1.1 implies the use of a "Expect: 100-continue" header.
1678 You can disable this header with <B>-httpheader</B> as usual.
1680 If you use PUT to a HTTP 1.1 server, you can upload data without knowing the
1681 size before starting the transfer if you use chunked encoding. You enable this
1682 by adding a header like "Transfer-Encoding: chunked" with <B>-httpheader</B>.
1683 With HTTP 1.0 or without chunked transfer, you must specify the size.
1685 <DT><B>-maxfilesize</B>
1688 This allows you to specify the maximum size (in bytes) of a file to download.
1689 If the file requested is larger than this value, the transfer will not start
1690 and error 'filesize exceeded' (63) will be returned.
1692 NOTE: The file size is not always known prior to download, and for such files
1693 this option has no effect even if the file transfer ends up being larger than
1694 this given limit. This concerns both FTP and HTTP transfers.
1696 <DT><B>-timecondition</B>
1699 This defines how the <B>timevalue</B> value is treated. You can set this
1700 parameter to <B>ifmodsince</B> or <B>ifunmodsince</B>. This feature applies to
1703 <DT><B>-timevalue</B>
1706 This should be the time in seconds since 1 jan 1970, and the time will be
1707 used in a condition as specified with <B>timecondition</B>.
1711 <A NAME="lbAQ"> </A>
1712 <H2>Connection options</H2>
1719 Pass the maximum time in seconds that you allow
1720 the TclCurl transfer operation to take. Do note that normally, name lookups
1721 may take a considerable time and that limiting the operation to less than a
1722 few minutes risks aborting perfectly normal operations. This option will
1723 cause libcurl to use the SIGALRM to enable time-outing system calls.
1725 In unix-like systems, this might cause signals to be used unless
1726 <B>-nosignal</B> is used.
1728 <DT><B>-timeoutms</B>
1731 Like <B>timeout</B> but takes a number of milliseconds instead. If libcurl is
1732 built to use the standard system name resolver, that part will still use
1733 full-second resolution for timeouts.
1735 <DT><B>-lowspeedlimit</B>
1738 Pass the speed in bytes per second that the transfer should be below during
1741 seconds for the extension to consider it too slow and abort.
1743 <DT><B>-lowspeedtime</B>
1746 Pass the time in seconds that the transfer should be below the
1747 <B>lowspeedlimit</B>
1749 for the extension to consider it too slow and abort.
1751 <DT><B>-maxsendspeed</B>
1754 Pass a speed in bytes per seconds. If an upload exceeds this speed on cumulative
1755 average during the transfer, the transfer will pause to keep the average rate less
1756 than or equal to the parameter value. Defaults to unlimited speed.
1758 <DT><B>-maxrecvspeed</B>
1761 Pass a speed in bytes per second. If a download exceeds this speed on cumulative
1762 average during the transfer, the transfer will pause to keep the average rate less
1763 than or equal to the parameter value. Defaults to unlimited speed.
1765 <DT><B>-maxconnects</B>
1768 Sets the persistant connection cache size in all the protocols that support
1769 persistent conecctions. The set amount will be the maximum amount of simultaneous
1770 connections that TclCurl may cache in this easy handle. Default is 5, and there
1771 isn't much point in changing this value unless you are perfectly aware of how this
1772 work and changes TclCurl's behaviour.
1774 When reaching the maximum limit, TclCurl closes the oldest connection in the cache
1775 to prevent the number of open connections to increase.
1777 <B>Note</B>: if you have already performed transfers with this curl handle,
1781 than before may cause open connections to unnecessarily get closed.
1783 If you add this easy handle to a multi handle, this setting is not
1784 being acknowledged, instead you must configure the multi handle its own
1785 <B>maxconnects</B> option.
1787 <DT><B>-connecttimeout</B>
1790 Maximum time in seconds that you allow the
1791 connection to the server to take. This only limits the connection phase, once
1792 it has connected, this option is of no more use. Set to zero to disable
1793 connection timeout (it will then only timeout on the internal timeouts).
1795 In unix-like systems, this might cause signals to be used unless
1796 <B>-nosignal</B> is set.
1798 <DT><B>-connecttimeoutms</B>
1801 Like <B>connecttimeout</B> but takes a number of milliseconds instead. If libcurl
1802 is built to use the standard system name resolver, that part will still use
1803 full-second resolution for timeouts.
1805 <DT><B>-ipresolve</B>
1808 Allows an application to select what kind of IP addresses to use when
1809 resolving host names. This is only interesting when using host names
1810 that resolve addresses using more than one version of IP. The allowed
1812 <DL COMPACT><DT><DD>
1817 Default, resolves addresses to all IP versions that your system allows.
1821 Resolve to ipv4 addresses.
1825 Resolve to ipv6 addresses.
1833 Pass a list of strings with host name resolve information to use for requests with
1836 Each single name resolve string should be written using the format
1837 HOST:PORT:ADDRESS where HOST is the name TclCurl will try to resolve, PORT is
1838 the port number of the service where TclCurl wants to connect to the HOST and
1839 ADDRESS is the numerical IP address. If libcurl is built to support IPv6,
1840 ADDRESS can be either IPv4 or IPv6 style addressing.
1842 This option effectively pre-populates the DNS cache with entries for the
1843 host+port pair so redirects and everything that operations against the
1844 HOST+PORT will instead use your provided ADDRESS.
1846 You can remove names from the DNS cache again, to stop providing these fake
1847 resolves, by including a string in the linked list that uses the format
1848 "-HOST:PORT". The host name must be prefixed with a dash, and the host name
1849 and port number must exactly match what was already added previously.
1854 Pass a one of the values from below to make TclCurl use your desired level of SSL for the transfer.
1855 This is for enabling SSL/TLS when you use FTP, SMTP, POP3, IMAP etc.
1857 You can use ftps:// URLs to explicitly switch on SSL/TSL for the control
1858 connection and the data connection.
1860 Alternatively you can set the option to one of these values:
1862 <DL COMPACT><DT><DD>
1867 Do not attempt to use SSL
1871 Try using SSL, proceed anyway otherwise.
1875 Use SSL for the control conecction or fail with "use ssl failed" (64).
1879 Use SSL for all communication or fail with "use ssl failed" (64).
1885 <A NAME="lbAR"> </A>
1886 <H2>SSL and security options</H2>
1893 Pass a string as parameter. The string should be the file name of your certificate.
1894 The default format is "PEM" and can be changed with <B>-sslcerttype</B>.
1896 With NSS this is the nickname of the certificate you wish to authenticate with.
1897 If you want to use a file from the current directory, please precede it with the
1898 "./" prefix, in order to avoid confusion with a nickname.
1900 <DT><B>-sslcerttype</B>
1903 Pass a string as parameter. The string should be the format of your certificate.
1904 Supported formats are "PEM" and "DER".
1909 Pass a pointer to a zero terminated string as parameter. The string should be
1910 the file name of your private key. The default format is "PEM" and can be
1911 changed with <B>-sslkeytype</B>.
1913 <DT><B>-sslkeytype</B>
1916 Pass a pointer to a zero terminated string as parameter. The string should be
1917 the format of your private key. Supported formats are "PEM", "DER" and "ENG"
1919 <B>NOTE:</B>The format "ENG" enables you to load the private key from a crypto
1920 engine. in this case <B>-sslkey</B> is used as an identifier passed to
1921 the engine. You have to set the crypto engine with <B>-sslengine</B>. The "DER"
1922 format key file currently does not work because of a bug in OpenSSL.
1924 <DT><B>-keypasswd</B>
1927 Pass a string as parameter. It will be used as the password required to use the
1928 <B>-sslkey</B> or <B>-sshprivatekeyfile</B> private key.
1930 You never need a pass phrase to load a certificate but you need one to load you
1933 This option used to be known as <B>-sslkeypasswd</B> and <B>-sslcertpasswd</B>.
1935 <DT><B>-sslengine</B>
1938 Pass a string as parameter. It will be used as the identifier for the crypto
1939 engine you want to use for your private key.
1941 <B>NOTE:</B>If the crypto device cannot be loaded, an error will be returned.
1943 <DT><B>-sslenginedefault</B>
1946 Pass a 1 to set the actual crypto engine as the default for (asymmetric) crypto operations.
1948 <B>NOTE:</B>If the crypto device cannot be set, an error will be returned.
1950 <DT><B>-sslversion</B>
1953 Use it to set what version of SSL/TLS to use. The available options are:
1954 <DL COMPACT><DT><DD>
1959 The default action. This will attempt to figure out the remote SSL protocol version,
1960 i.e. either SSLv3 or TLSv1 (but not SSLv2, which became disabled by default with 7.18.1).
1977 <DT><B>-sslverifypeer</B>
1980 This option determines whether TclCurl verifies the authenticity of the peer's certificate.
1981 A 1 means it verifies; zero means it doesn't. The default is 1.
1983 When negotiating an SSL connection, the server sends a certificate indicating its identity.
1984 TclCurl verifies whether the certificate is authentic, i.e. that you can trust that the
1985 server is who the certificate says it is. This trust is based on a chain of digital signatures,
1986 rooted in certification authority (CA) certificates you supply.
1988 TclCurl uses a default bundle of CA certificates that comes with libcurl but you can specify
1989 alternate certificates with the <B>-cainfo</B> or the <B>-capath</B> options.
1991 When <B>-sslverifypeer</B> is nonzero, and the verification fails to prove that the certificate
1992 is authentic, the connection fails. When the option is zero, the peer certificate verification
1993 succeeds regardless.
1995 Authenticating the certificate is not by itself very useful. You typically want to ensure
1996 that the server, as authentically identified by its certificate, is the server you mean to
1997 be talking to, use <B>-sslverifyhost</B> to control that. The check that the host name in
1998 the certificate is valid for the host name you're connecting to is done
1999 independently of this option.
2004 Pass a file naming holding the certificate to verify the peer with. This only
2005 makes sense when used in combination with the <B>-sslverifypeer</B> option, if
2006 it is set to zero <B>-cainfo</B> need not even indicate an accessible file.
2008 This option is by default set to the system path where libcurl's cacert bundle
2009 is assumed to be stored, as established at build time.
2011 When built against NSS this is the directory that the NSS certificate database
2014 <DT><B>-issuercert</B>
2017 Pass a string naming a file holding a CA certificate in PEM format. If the option
2018 is set, an additional check against the peer certificate is performed to verify
2019 the issuer is indeed the one associated with the certificate provided by the option.
2020 This additional check is useful in multi-level PKI where one need to enforce the peer
2021 certificate is from a specific branch of the tree.
2023 This option makes sense only when used in combination with the <B>-sslverifypeer</B>
2024 option. Otherwise, the result of the check is not considered as failure.
2029 Pass the directory holding multiple CA certificates to verify the peer with.
2030 If libcurl is built against OpenSSL, the certificate directory must be prepared
2031 using the openssl c_rehash utility.
2032 This only makes sense when used in combination with the <B>-sslverifypeer</B>
2033 option, if it is set to zero, <B>-capath</B> need not even indicate an accessible
2036 This option apparently does not work in Windows due to some limitation in openssl.
2038 This option is OpenSSL-specific and does nothing if libcurl is built to use GnuTLS.
2039 NSS-powered libcurl provides the option only for backward compatibility.
2044 Pass a string naming a file with the concatenation of CRL (in PEM format) to use in
2045 the certificate validation that occurs during the SSL exchange.
2047 When libcurl is built to use NSS or GnuTLS, there is no way to influence the use of
2048 CRL passed to help in the verification process. When built with OpenSSL support,
2049 X509_V_FLAG_CRL_CHECK and X509_V_FLAG_CRL_CHECK_ALL are both set, requiring CRL
2050 check against all the elements of the certificate chain if a CRL file is passed.
2052 This option makes sense only when used in combination with the <B>-sslverifypeer</B>
2055 A specific error code (CURLE_SSL_CRL_BADFILE) is defined with the option. It is returned
2056 when the SSL exchange fails because the CRL file cannot be loaded. A failure in certificate
2057 verification due to a revocation information found in the CRL does not trigger this specific
2060 <DT><B>-sslverifyhost</B>
2063 This option determines whether TclCurl verifies that the server claims to be
2064 who you want it to be.
2066 When negotiating an SSL connection, the server sends a certificate
2067 indicating its identity.
2069 When <B>-sslverifyhost</B> is set to 2, that certificate must indicate
2070 that the server is the server to which you meant to connect, or the
2073 TclCurl considers the server the intended one when the Common Name field
2074 or a Subject Alternate Name field in the certificate matches the host
2075 name in the URL to which you told Curl to connect.
2077 When set to 1, the certificate must contain a Common Name field,
2078 but it does not matter what name it says. (This is not ordinarily a
2081 When the value is 0, the connection succeeds regardless of the names in
2084 The default value for this option is 2.
2086 This option controls the identity that the server <I>claims</I>. The server
2087 could be lying. To control lying, see <B>-sslverifypeer</B>. If libcurl is built
2088 against NSS and <B>-verifypeer</B> is zero, <B>-verifyhost</B> is ignored.
2090 <DT><B>-certinfo</B>
2093 Set to '1' to enable TclCurl's certificate chain info gatherer. With this enabled, TclCurl
2094 (if built with OpenSSL) will extract lots of information and data about the certificates
2095 in the certificate chain used in the SSL connection. This data can then be to extracted
2096 after a transfer using the <B>getinfo</B> command and its option <B>certinfo</B>.
2098 <DT><B>-randomfile</B>
2101 Pass a file name. The file will be used to read from to seed the random engine
2102 for SSL. The more random the specified file is, the more secure the SSL
2105 <DT><B>-egdsocket</B>
2108 Pass a path name to the Entropy Gathering Daemon socket. It will be used to seed
2109 the random engine for SSL.
2111 <DT><B>-sslcypherlist</B>
2114 Pass a string holding the ciphers to use for the SSL connection. The list must
2115 consists of one or more cipher strings separated by colons. Commas or spaces
2116 are also acceptable separators but colons are normally used, , - and + can be
2119 For OpenSSL and GnuTLS valid examples of cipher lists include 'RC4-SHA', 'SHA1+DES',
2122 You will find more details about cipher lists on this URL:
2123 <BR> <A HREF="http://www.openssl.org/docs/apps/ciphers.html">http://www.openssl.org/docs/apps/ciphers.html</A>
2125 For NSS valid examples of cipher lists include 'rsa_rc4_128_md5', 'rsa_aes_128_sha',
2126 etc. With NSS you don't add/remove ciphers. If you use this option then all known
2127 ciphers are disabled and only those passed in are enabled.
2129 You'll find more details about the NSS cipher lists on this URL:
2130 <BR> <A HREF="http://directory.fedora.redhat.com/docs/mod_nss.html">http://directory.fedora.redhat.com/docs/mod_nss.html</A>
2132 <DT><B>-sslsessionidcache</B>
2135 Pass a 0 to disable TclCurl's use of SSL session-ID caching or a 1 to enable it.
2136 By default all transfers are done using the cache. While nothing ever
2137 should get hurt by attempting to reuse SSL session-IDs, there seem to be broken SSL
2138 implementations in the wild that may require you to disable this in order for you to
2141 <DT><B>-krblevel</B>
2144 Set the kerberos security level for FTP, this also enables kerberos awareness.
2145 This is a string, 'clear', 'safe', 'confidential' or 'private'. If the string
2146 is set but does not match one of these, 'private' will be used. Set the string
2147 to NULL to disable kerberos4. Set the string to "" to disable kerberos
2150 <DT><B>-gssapidelegation</B>
2153 Set the option to 'flag' to allow unconditional GSSAPI credential delegation. The delegation
2154 is disabled by default since 7.21.7. Set the parameter to 'policyflag' to delegate only if
2155 the OK-AS-DELEGATE flag is set in the service ticket in case this feature is supported by the
2156 GSSAPI implementation and the definition of GSS_C_DELEG_POLICY_FLAG was available at compile-time.
2160 <A NAME="lbAS"> </A>
2161 <H2>SSH options</H2>
2165 <DT><B>-sshauthtypes</B>
2168 The allowed types are:
2170 <DL COMPACT><DT><DD>
2172 <DT><B>publickey</B>
2187 To let TclCurl pick one
2192 <DT><B>-sshhostpublickeymd5</B>
2195 Pass a string containing 32 hexadecimal digits. The string should be the 128
2196 bit MD5 cheksum of the remote host public key, and TclCurl will reject the
2197 connection to the host unless the md5sums match. This option is only for SCP
2200 <DT><B>-publickeyfile</B>
2203 Pass the file name for your public key. If not used, TclCurl defaults to using <B>$HOME/.ssh/id_dsa.pub</B>.
2204 HOME environment variable is set, and just <B>id_dsa</B> in the current directory if not.
2206 <DT><B>-privatekeyfile</B>
2209 Pass the file name for your private key. If not used, TclCurl defaults to using <B>$HOME/.ssh/id_dsa.pub</B>.
2210 HOME environment variable is set, and just <B>id_dsa</B> in the current directory if not.
2211 If the file is password-protected, set the password with <B>-keypasswd</B>.
2213 <DT><B>-sshknownhosts</B>
2216 Pass a string holding the file name of the known_host file to use. The known_hosts
2217 file should use the OpenSSH file format as supported by libssh2. If this file is
2218 specified, TclCurl will only accept connections with hosts that are known and present
2219 in that file, with a matching public key. Use <B>-sshkeyproc</B> to alter the default
2220 behavior on host and key (mis)matching.
2222 <DT><B>-sshkeyproc </B>
2225 Pass a the name of the procedure that will be called when the known_host matching has
2226 been done, to allow the application to act and decide for TclCurl how to proceed. The
2227 callback will only be called if <B>-knownhosts</B> is also set.
2229 It gets passed a list with three elements, the first one is a list with the type of the
2230 key from the known_hosts file and the key itself, the second is another list with
2231 the type of the key from the remote site and the key itslef, the third tells you
2232 what TclCurl thinks about the matching status.
2234 The known key types are: "rsa", "rsa1" and "dss", in any other case "unknown" is given.
2236 TclCurl opinion about how they match may be: "match", "mismatch", "missing" or "error".
2238 The procedure must return:
2239 <DL COMPACT><DT><DD>
2244 The host+key is accepted and TclCurl will append it to the known_hosts file before
2245 continuing with the connection. This will also add the host+key combo to the known_host
2246 pool kept in memory if it wasn't already present there. The adding of data to
2247 the file is done by completely replacing the file with a new copy, so the permissions of
2248 the file must allow this.
2252 The host+key is accepted, TclCurl will continue with the connection. This will also add
2253 the host+key combo to the known_host pool kept in memory if it wasn't already present
2258 The host+key is rejected. TclCurl will close the connection.
2262 The host+key is rejected, but the SSH connection is asked to be kept alive. This feature
2263 could be used when the app wants to somehow return back and act on the host+key situation
2264 and then retry without needing the overhead of setting it up from scratch again.
2269 Any other value will cause the connection to be closed.
2272 <A NAME="lbAT"> </A>
2273 <H2>Other options</H2>
2277 <DT><B>-headervar</B>
2280 Name of the Tcl array variable where TclCurl will store the headers returned
2286 Name of the Tcl variable where TclCurl will store the file requested, the file
2287 may contain text or binary data.
2289 <DT><B>-canceltransvar</B>
2292 Name of a Tcl variable, in case you have defined a procedure to call with
2293 <B>-progressproc</B> setting this variable to '1' will cancel the transfer.
2298 Executes the given command after the transfer is done, since it only works
2299 with blocking transfers, it is pretty much useless.
2304 Pass a share handle as a parameter. The share handle must have been created by
2305 a previous call to <B>curl::shareinit</B>. Setting this option, will make this
2306 handle use the data from the shared handle instead of keeping the data to itself.
2307 See <I>tclcurl_share</I> for details.
2309 <DT><B>-newfileperms</B>
2312 Pass a number as a parameter, containing the value of the permissions that will
2313 be assigned to newly created files on the remote server. The default value is 0644,
2314 but any valid value can be used. The only protocols that can use this are sftp://,
2317 <DT><B>-newdirectoryperms</B>
2320 Pass a number as a parameter, containing the value of the permissions that will be
2321 assigned to newly created directories on the remote server. The default value is 0755,
2322 but any valid value can be used. The only protocols that can use this are sftp://, scp://
2326 <A NAME="lbAU"> </A>
2327 <H2>Telnet options</H2>
2331 <DT><B>-telnetoptions</B>
2334 Pass a list with variables to pass to the telnet negotiations. The variables should be in
2335 the format <option=value>. TclCurl supports the options 'TTYPE', 'XDISPLOC' and 'NEW_ENV'.
2336 See the TELNET standard for details.
2339 <A NAME="lbAV"> </A>
2340 <H2>NOT SUPPORTED</H2>
2342 Some of the options libcurl offers are not supported, I don't think them
2343 worth supporting in TclCurl but if you need one of them don't forget to
2346 <B>CURLOPT_FRESH_CONNECT, CURLOPT_FORBID_REUSE, CURLOPT_PRIVATE,</B>
2348 <B>CURLOPT_SSL_CTX_FUNCTION, CURLOPT_SSL_CTX_DATA, CURLOPT_SSL_CTX_FUNCTION and</B>
2350 <B>CURLOPT_CONNECT_ONLY, CURLOPT_OPENSOCKETFUNCTION, CURLOPT_OPENSOCKETDATA.</B>
2353 <A NAME="lbAW"> </A>
2354 <H2>curlHandle perform</H2>
2356 This procedure is called after the
2362 calls are made, and will perform the transfer as described in the options.
2364 It must be called with the same
2365 <I>curlHandle</I> <B>curl::init</B> call returned.
2366 You can do any amount of calls to perform while using the same handle. If you
2367 intend to transfer more than one file, you are even encouraged to do
2368 so. TclCurl will then attempt to re-use the same connection for the following
2369 transfers, thus making the operations faster, less CPU intense and using less
2370 network resources. Just note that you will have to use
2373 between the invokes to set options for the following perform.
2375 You must never call this procedure simultaneously from two places using the
2376 same handle. Let it return first before invoking it another time. If
2377 you want parallel transfers, you must use several curl handles.
2379 <DT><B>RETURN VALUE</B>
2388 there will be a readable error message.
2389 The error codes are:
2391 Unsupported protocol. This build of TclCurl has no support for this protocol.
2393 Very early initialization code failed. This is likely to be and internal error
2394 or a resource problem where something fundamental couldn't get done at init time.
2396 URL malformat. The syntax was not correct.
2398 A requested feature, protocol or option was not found built-in in this libcurl
2399 due to a build-time decision. This means that a feature or option was not
2400 enabled or explicitly disabled when libcurl was built and in order to get it
2401 to function you have to get a rebuilt libcurl.
2403 Couldn't resolve proxy. The given proxy host could not be resolved.
2405 Couldn't resolve host. The given remote host was not resolved.
2407 Failed to connect to host or proxy.
2409 FTP weird server reply. The server sent data TclCurl couldn't parse.
2410 The given remote server is probably not an OK FTP server.
2412 We were denied access to the resource given in the URL. For FTP, this occurs
2413 while trying to change to the remote directory.
2415 FTP weird PASS reply. TclCurl couldn't parse the reply sent to the PASS request.
2417 FTP weird PASV reply, TclCurl couldn't parse the reply sent to the PASV or EPSV
2420 FTP weird 227 format. TclCurl couldn't parse the 227-line the server sent.
2422 FTP can't get host. Couldn't resolve the host IP we got in the 227-line.
2424 FTP couldn't set type. Couldn't change transfer method to either binary or
2427 Partial file. Only a part of the file was transfered, this happens when
2428 the server first reports an expected transfer size and then delivers data
2429 that doesn't match the given size.
2431 FTP couldn't RETR file, we either got a weird reply to a 'RETR' command or
2432 a zero byte transfer.
2434 Quote error. A custom 'QUOTE' returned error code 400 or higher (for FTP) or
2435 otherwise indicated unsuccessful completion of the command.
2437 HTTP returned error. This return code only appears if <B>-failonerror</B> is
2438 used and the HTTP server returns an error code that is 400 or higher.
2440 Write error. TclCurl couldn't write data to a local filesystem or an error
2441 was returned from a write callback.
2443 Failed upload failed. For FTP, the server typcially denied the STOR
2444 command. The error buffer usually contains the server's explanation to this.
2446 Read error. There was a problem reading from a local file or an error was returned
2447 from the read callback.
2449 Out of memory. A memory allocation request failed. This should never happen unless
2450 something weird is going on in your computer.
2452 Operation timeout. The specified time-out period was reached according to the
2455 The FTP PORT command failed, not all FTP servers support the PORT command,
2456 try doing a transfer using PASV instead!.
2458 FTP couldn't use REST. This command is used for resumed FTP transfers.
2460 Range error. The server doesn't support or accept range requests.
2462 HTTP post error. Internal post-request generation error.
2464 SSL connect error. The SSL handshaking failed, the error buffer may have
2465 a clue to the reason, could be certificates, passwords, ...
2467 The download could not be resumed because the specified offset was out of the
2470 A file given with FILE:// couldn't be read. Did you checked the permissions?
2472 LDAP cannot bind. LDAP bind operation failed.
2476 A required zlib function was not found.
2478 Aborted by callback. An application told TclCurl to abort the operation.
2480 Internal error. A function was called with a bad parameter.
2482 Interface error. A specified outgoing interface could not be used.
2484 Too many redirects. When following redirects, TclCurl hit the maximum amount, set
2485 your limit with --maxredirs
2487 An option passed to TclCurl is not recognized/known. Refer to the appropriate
2488 documentation. This is most likely a problem in the program that uses
2489 TclCurl. The error buffer might contain more specific information about which
2490 exact option it concerns.
2492 A telnet option string was illegally formatted.
2494 The remote peer's SSL certificate or SSH md5 fingerprint wasn't ok
2496 The server didn't reply anything, which here is considered an error.
2498 The specified crypto engine wasn't found.
2500 Failed setting the selected SSL crypto engine as default!
2502 Failed sending network data.
2504 Failure with receiving network data.
2506 Problem with the local client certificate.
2508 Couldn't use specified SSL cipher.
2510 Peer certificate cannot be authenticated with known CA certificates.
2512 Unrecognized transfer encoding.
2516 Maximum file size exceeded.
2520 Sending the data requires a rewind that failed, since TclCurl should
2521 take care of it for you, it means you found a bug.
2523 Failed to initialise ssl engine.
2525 Failed to login, user password or similar was not accepted.
2527 File not found on TFTP server.
2529 There is a permission problem with the TFTP request.
2531 The remote server has run out of space.
2533 Illegal TFTP operation.
2535 Unknown transfer ID.
2537 TFTP file already exists and will not be overwritten.
2539 No such user in the TFTP server and good behaving TFTP servers
2540 should never return this.
2542 Character conversion failed.
2544 Problem with reading the SSL CA cert (path? access rights?).
2546 Remote file not found
2548 Error from the SSH layer
2550 Failed to shut down the SSL connection
2552 Failed to load CRL file
2556 The FTP server does not understand the PRET command at all or does not support
2557 the given argument. Be careful when using <B>-customrequest</B>, a
2558 custom LIST command will be sent with PRET CMD before PASV as well.
2560 Mismatch of RTSP CSeq numbers.
2562 Mismatch of RTSP Session Identifiers.
2564 Unable to parse FTP file list (during FTP wildcard downloading).
2566 Chunk callback reported error.
2569 <A NAME="lbAX"> </A>
2570 <H2>curlHandle getinfo option</H2>
2572 Request internal information from the curl session with this procedure.
2573 This procedure is intended to get used *AFTER* a performed transfer,
2574 and can be relied upon only if the <B>perform</B> returns 0. Use
2575 this function AFTER a performed transfer if you want to get
2576 transfer-oriented data.
2578 The following information can be extracted:
2581 <DT><B>effectiveurl</B>
2584 Returns the last used effective URL.
2586 <DT><B>responsecode</B>
2589 Returns the last received HTTP or FTP code. This will be zero if no server
2590 response code has been received. Note that a proxy's CONNECT response should
2591 be read with <B>httpconnectcode</B> and not this.
2593 <DT><B>httpconnectcode</B>
2596 Returns the last received proxy response code to a CONNECT request.
2601 Returns the remote time of the retrieved document (in number of seconds
2602 since 1 jan 1970 in the GMT/UTC time zone). If you get -1,
2603 it can be because of many reasons (unknown, the server hides it or the
2604 server doesn't support the command that tells document time etc) and the time
2605 of the document is unknown.
2607 In order for this to work you have to set the <B>-filetime</B> option before
2610 <DT><B>namelookuptime</B>
2613 Returns the time, in seconds, it took from the start until the name resolving
2616 <DT><B>connecttime</B>
2619 Returns the time, in seconds, it took from the start until the connect to the
2620 remote host (or proxy) was completed.
2622 <DT><B>appconnecttime</B>
2625 Returns the time, in seconds, it took from the start until the SSL/SSH
2626 connect/handshake to the remote host was completed. This time is most often very
2627 near to the PRETRANSFER time, except for cases such as HTTP pippelining where the
2628 pretransfer time can be delayed due to waits in line for the pipeline and more.
2630 <DT><B>pretransfertime</B>
2633 Returns the time, in seconds, it took from the start until the file transfer
2634 is just about to begin. This includes all pre-transfer commands and
2635 negotiations that are specific to the particular protocol(s) involved.
2637 <DT><B>starttransfertime</B>
2640 Returns the time, in seconds, it took from the start until the first byte
2641 is just about to be transfered. This includes the <B>pretransfertime</B>,
2642 and also the time the server needs to calculate the result.
2644 <DT><B>totaltime</B>
2647 Returns the total transaction time, in seconds, for the previous transfer,
2648 including name resolving, TCP connect etc.
2650 <DT><B>redirecturl</B>
2653 Returns the URL a redirect would take you to if you enable <B>followlocation</B>.
2654 This can come very handy if you think using the built-in libcurl redirect logic
2655 isn't good enough for you but you would still prefer to avoid implementing all
2656 the magic of figuring out the new URL.
2658 <DT><B>redirecttime</B>
2661 Returns the total time, in seconds, it took for all redirection steps
2662 including name lookup, connect, pretransfer and transfer before
2663 the final transaction was started, it returns the complete execution
2664 time for multiple redirections, so it returns zero if no redirections
2667 <DT><B>redirectcount</B>
2670 Returns the total number of redirections that were actually followed.
2672 <DT><B>numconnects</B>
2675 Returns how many new connections TclCurl had to create to achieve the
2676 previous transfer (only the successful connects are counted). Combined
2677 with <B>redirectcount</B> you are able to know how many times TclCurl
2678 successfully reused existing connection(s) or not. See the Connection
2679 Options of <B>setopt</B> to see how TclCurl tries to make persistent
2680 connections to save time.
2682 <DT><B>primaryip</B>
2685 Returns the IP address of the most recent connection done with this handle.
2686 This string may be IPv6 if that's enabled.
2688 <DT><B>primaryport</B>
2691 Returns the destination port of the most recent connection done with this handle.
2696 Returns the local (source) IP address of the most recent connection done
2697 with this handle. This string may be IPv6 if that's enabled.
2699 <DT><B>localport</B>
2702 Returns the local (source) port of the most recent connection done with this handle.
2704 <DT><B>sizeupload</B>
2707 Returns the total amount of bytes that were uploaded.
2709 <DT><B>sizedownload</B>
2712 Returns the total amount of bytes that were downloaded. The amount is only
2713 for the latest transfer and will be reset again for each new transfer.
2715 <DT><B>speeddownload</B>
2718 Returns the average download speed, measured in bytes/second, for the complete download.
2720 <DT><B>speedupload</B>
2723 Returns the average upload speed, measured in bytes/second, for the complete upload.
2725 <DT><B>headersize</B>
2728 Returns the total size in bytes of all the headers received.
2730 <DT><B>requestsize</B>
2733 Returns the total size of the issued requests. This is so far only for HTTP
2734 requests. Note that this may be more than one request if followLocation is true.
2736 <DT><B>sslverifyresult</B>
2739 Returns the result of the certification verification that was requested
2740 (using the -sslverifypeer option to configure).
2742 <DT><B>sslengines</B>
2745 Returns a <B>list</B> of the OpenSSL crypto-engines supported. Note that engines are
2746 normally implemented in separate dynamic libraries. Hence not all the returned
2747 engines may be available at run-time.
2749 <DT><B>contentlengthdownload</B>
2752 Returns the content-length of the download. This is the value read from the
2753 <B>Content-Length:</B>
2755 field. If the size isn't known, it returns -1.
2757 <DT><B>contentlengthupload</B>
2760 Returns the specified size of the upload.
2762 <DT><B>contenttype</B>
2765 Returns the content-type of the downloaded object. This is the value
2766 read from the Content-Type: field. If you get an empty string, it means
2767 the server didn't send a valid Content-Type header or that the protocol
2768 used doesn't support this.
2770 <DT><B>httpauthavail</B>
2773 Returns a list with the authentication method(s) available.
2775 <DT><B>proxyauthavail</B>
2778 Returns a list with the authentication method(s) available for your
2779 proxy athentication.
2784 Returns the errno value from a connect failure. This value is only set on
2785 failure, it is no reset after a successfull operation.
2787 <DT><B>cookielist</B>
2790 Returns a list of all cookies TclCurl knows (expired ones, too). If there
2791 are no cookies (cookies for the handle have not been enabled or simply
2792 none have been received) the list will be empty.
2794 <DT><B>ftpentrypath </B>
2797 Returns a string holding the path of the entry path. That is the initial path
2798 TclCurl ended up in when logging on to the remote FTP server. Returns an empty
2799 string if something is wrong.
2804 Returns list with information about the certificate chain, assuming you had the
2805 <B>-certinfo</B> option enabled when the previous request was done. The list
2806 first item reports how many certs it found and then you can extract info for each
2807 of those certs by following the list. The info chain is provided in a series of data
2808 in the format "name:content" where the content is for the specific named data.
2810 NOTE: this option is only available in libcurl built with OpenSSL support.
2812 <DT><B>conditionunmet</B>
2815 Returns the number 1 if the condition provided in the previous request
2816 didn't match (see <I>timecondition</I>), you will get a zero if the condition
2820 <A NAME="lbAY"> </A>
2821 <H2>curlHandle cleanup</H2>
2823 This procedure must be the last one to call for a curl session. It is the
2827 procedure and must be called with the same
2830 as input as the curl::init call returned.
2831 This will effectively close all connections TclCurl has used and possibly
2832 has kept open until now. Don't call this procedure if you intend to transfer
2835 <A NAME="lbAZ"> </A>
2836 <H2>curlHandle reset</H2>
2839 Re-initializes all options previously set on a specified handle to the
2842 This puts back the handle to the same state as it was in when it was just
2843 created with curl::init.
2845 It does not change the following information kept in the handle: live
2846 connections, the Session ID cache, the DNS cache, the cookies and shares.
2848 <A NAME="lbBA"> </A>
2849 <H2>curlHandle duphandle</H2>
2851 This procedure will return a new curl handle, a duplicate,
2852 using all the options previously set in the input curl handle.
2853 Both handles can subsequently be used independently and
2854 they must both be freed with
2857 The new handle will not inherit any state information,
2858 connections, SSL sessions or cookies.
2860 <DT><B>RETURN VALUE</B>
2863 A new curl handle or an error message if the copy fails.
2866 <A NAME="lbBB"> </A>
2867 <H2>curlHandle pause</H2>
2869 You can use this command from within a progress callback procedure
2870 to pause the transfer.
2872 <A NAME="lbBC"> </A>
2873 <H2>curlHandle resume</H2>
2875 Resumes a transfer paused with <B>curlhandle pause</B>
2877 <A NAME="lbBD"> </A>
2878 <H2>curl::transfer</H2>
2880 In case you do not want to use persistant connections you can use this
2881 command, it takes the same arguments as the <I>curlHandle</I> <B>configure</B>
2882 and will init, configure, perform and cleanup a connection for you.
2884 You can also get the <I>getinfo</I> information by using <I>-infooption variable</I>
2885 pairs, after the transfer <I>variable</I> will contain the value that would have
2886 been returned by <I>$curlHandle getinfo option</I>.
2888 <DT><B>RETURN VALUE</B>
2891 The same error code <B>perform</B> would return.
2894 <A NAME="lbBE"> </A>
2895 <H2>curl::version</H2>
2897 Returns a string with the version number of tclcurl, libcurl and some of
2898 its important components (like OpenSSL version).
2900 <DT><B>RETURN VALUE</B>
2903 The string with the version info.
2906 <A NAME="lbBF"> </A>
2907 <H2>curl::escape url</H2>
2909 This procedure will convert the given input string to an URL encoded string and
2910 return that. All input characters that are not a-z,
2911 A-Z or 0-9 will be converted to their "URL escaped" version (%NN where NN is a
2912 two-digit hexadecimal number)
2914 <DT><B>RETURN VALUE</B>
2917 The converted string.
2919 <A NAME="lbBG"> </A>
2920 <H2>curl::unescape url</H2>
2922 This procedure will convert the given URL encoded input string to a "plain
2923 string" and return that. All input characters that
2924 are URL encoded (%XX where XX is a two-digit hexadecimal number) will be
2925 converted to their plain text versions.
2927 <DT><B>RETURN VALUE</B>
2930 The string unencoded.
2933 <A NAME="lbBH"> </A>
2934 <H2>curl::curlConfig option</H2>
2936 Returns some information about how you have
2945 Returns the directory root where you installed
2951 Returns a list containing particular main features the installed
2954 was built with. The list may include SSL, KRB4 or IPv6, do not
2955 assume any particular order.
2959 Outputs version information about the installed libcurl, in
2960 numerical mode. This outputs the version number, in hexadecimal,
2961 with 8 bits for each part; major, minor, patch. So that libcurl
2962 7.7.4 would appear as 070704 and libcurl 12.13.14 would appear as
2966 <A NAME="lbBI"> </A>
2967 <H2>curl::versioninfo option</H2>
2969 Returns information about various run-time features in TclCurl.
2971 Applications should use this information to judge if things are possible to do
2972 or not, instead of using compile-time checks, as dynamic/DLL libraries can be
2973 changed independent of applications.
2979 Returns the version of libcurl we are using.
2981 <DT><B>-versionnum</B>
2984 Retuns the version of libcurl we are using in hexadecimal with 8 bits for each
2985 part; major, minor, patch. So that libcurl 7.7.4 would appear as 070704 and
2986 libcurl 12.13.14 would appear as 0c0d0e... Note that the initial zero might be
2992 Returns a string with the host information as discovered by a configure
2993 script or set by the build environment.
2995 <DT><B>-features</B>
2998 Returns a list with the features compiled into libcurl, the possible elements are:
2999 <DL COMPACT><DT><DD>
3001 <DT><B>ASYNCHDNS</B>
3004 Libcurl was built with support for asynchronous name lookups, which allows
3005 more exact timeouts (even on Windows) and less blocking when using the multi
3010 Libcurl was built with support for character conversions.
3014 Libcurl was built with extra debug capabilities built-in. This is mainly of
3015 interest for libcurl hackers.
3016 <DT><B>GSSNEGOTIATE</B>
3019 Supports HTTP GSS-Negotiate.
3023 Supports IDNA, domain names with international letters.
3028 <DT><B>KERBEROS4</B>
3031 Supports kerberos4 (when using FTP).
3032 <DT><B>LARGEFILE</B>
3035 Libcurl was built with support for large files.
3039 Supports HTTP deflate using libz.
3047 Libcurl was built with support for SPNEGO authentication (Simple and Protected
3048 GSS-API Negotiation Mechanism, defined in RFC 2478)
3052 Supports SSL (HTTPS/FTPS)
3056 Libcurl was built with support for SSPI. This is only available on Windows and
3057 makes libcurl use Windows-provided functions for NTLM authentication. It also
3058 allows libcurl to use the current user and the current user's password without
3059 the app having to pass them on.
3060 <DT><B>TLSAUTH_SRP</B>
3063 Libcurl was built with support for TLS-SRP.
3066 Libcurl was built with support for NTLM delegation to a winbind helper.
3070 Do not assume any particular order.
3072 <DT><B>-sslversion</B>
3075 Returns a string with the OpenSSL version used, like OpenSSL/0.9.6b.
3077 <DT><B>-sslversionnum</B>
3080 Returns the numerical OpenSSL version value as defined by the OpenSSL project.
3081 If libcurl has no SSL support, this is 0.
3083 <DT><B>-libzversion</B>
3086 Returns a string, there is no numerical version, for example: 1.1.3.
3088 <DT><B>-protocols</B>
3091 Lists what particular protocols the installed TclCurl was built to support.
3092 At the time of writing, this list may include HTTP, HTTPS, FTP, FTPS,
3093 FILE, TELNET, LDAP, DICT. Do not assume any particular order. The protocols
3094 will be listed using uppercase. There may be none, one or several protocols
3098 <A NAME="lbBJ"> </A>
3099 <H2>curl::easystrerror errorCode</H2>
3101 This procedure returns a string describing the error code passed in the argument.
3103 <A NAME="lbBK"> </A>
3106 <I>curl, <a href="http://curl.haxx.se/docs/httpscripting.html">The art of HTTP scripting</A>, RFC 2396,</I>
3111 <A NAME="index"> </A><H2>Index</H2>
3113 <DT><A HREF="#lbAB">NAME</A><DD>
3114 <DT><A HREF="#lbAC">SYNOPSIS</A><DD>
3115 <DT><A HREF="#lbAD">DESCRIPTION</A><DD>
3116 <DT><A HREF="#lbAE">curl::init</A><DD>
3117 <DT><A HREF="#lbAF">curlHandle configure ?options?</A><DD>
3118 <DT><A HREF="#lbAG">Behaviour options</A><DD>
3119 <DT><A HREF="#lbAH">Callback options</A><DD>
3120 <DT><A HREF="#lbAI">Error Options</A><DD>
3121 <DT><A HREF="#lbAJ">Network options</A><DD>
3122 <DT><A HREF="#lbAK">Names and Passwords options</A><DD>
3123 <DT><A HREF="#lbAL">HTTP options</A><DD>
3124 <DT><A HREF="#lbAM">SMTP options</A><DD>
3125 <DT><A HREF="#lbAN">TFTP option</A><DD>
3126 <DT><A HREF="#lbAO">FTP options</A><DD>
3127 <DT><A HREF="#lbAP">Protocol options</A><DD>
3128 <DT><A HREF="#lbAQ">Connection options</A><DD>
3129 <DT><A HREF="#lbAR">SSL and security options</A><DD>
3130 <DT><A HREF="#lbAS">SSH options</A><DD>
3131 <DT><A HREF="#lbAT">Other options</A><DD>
3132 <DT><A HREF="#lbAU">Telnet options</A><DD>
3133 <DT><A HREF="#lbAV">NOT SUPPORTED</A><DD>
3134 <DT><A HREF="#lbAW">curlHandle perform</A><DD>
3135 <DT><A HREF="#lbAX">curlHandle getinfo option</A><DD>
3136 <DT><A HREF="#lbAY">curlHandle cleanup</A><DD>
3137 <DT><A HREF="#lbAZ">curlHandle reset</A><DD>
3138 <DT><A HREF="#lbBA">curlHandle duphandle</A><DD>
3139 <DT><A HREF="#lbBB">curlHandle pause</A><DD>
3140 <DT><A HREF="#lbBC">curlHandle resume</A><DD>
3141 <DT><A HREF="#lbBD">curl::transfer</A><DD>
3142 <DT><A HREF="#lbBE">curl::version</A><DD>
3143 <DT><A HREF="#lbBF">curl::escape url</A><DD>
3144 <DT><A HREF="#lbBG">curl::unescape url</A><DD>
3145 <DT><A HREF="#lbBH">curl::curlConfig option</A><DD>
3146 <DT><A HREF="#lbBI">curl::versioninfo option</A><DD>
3147 <DT><A HREF="#lbBJ">curl::easystrerror errorCode</A><DD>
3148 <DT><A HREF="#lbBK">SEE ALSO</A><DD>
3151 This document was created by man2html, using the manual pages.<BR>
projects / sven / tclcurl.git / blob