1 <HTML><HEAD><TITLE>Manpage of TclCurl</TITLE>
4 Section: Easy inteface (n)<BR>Updated: 8 September 2008<BR>
5 <A NAME="lbAB"> </A>
9 TclCurl: - get a URL with FTP, FTPS, HTTP, HTTPS, SCP, SFTP, TFTP, TELNET, DICT, FILE or LDAP syntax.
10 <A NAME="lbAC"> </A>
16 <I>curlHandle</I><B> configure </B><I>?options?</I>
19 <I>curlHandle</I><B> perform</B>
22 <I>curlHandle</I><B> getinfo </B><I>curlinfo_option</I>
25 <I>curlhandle</I><B> cleanup</B>
28 <I>curlhandle</I><B> reset</B>
31 <I>curlHandle</I><B> duhandle</B>
34 <I>curlHandle</I><B> pause</B>
37 <I>curlHandle</I><B> resume</B>
40 <B>curl::transfer</B><I> ?options?</I>
46 <B>curl::escape </B><I>url</I>
49 <B>curl::unescape </B><I>url</I>
52 <B>curl::curlConfig </B><I>option</I>
55 <B>curl::versioninfo </B><I>option</I>
58 <B>curl::easystrerror </B><I>errorCode</I>
61 <A NAME="lbAD"> </A>
64 The TclCurl extension gives Tcl programmers access to the libcurl
65 library written by <a href="http://daniel.haxx.se">Daniel Stenberg</a>, with it you can download urls,
66 upload them and many other neat tricks, for more information check
67 <A HREF="http://curl.haxx.se">cURL's web page</A>
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 built-in progress meter.
151 Nowadays it is turn off by default.
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.
163 <A NAME="lbAH"> </A>
164 <H2>Callback options</H2>
168 <DT><B>-writeproc</B>
171 Use it to set a Tcl procedure that will be invoked by TclCurl as soon as
172 there is received data that needs to be saved. The procedure will receive
173 a single parameter with the data to be saved.
175 NOTE: you will be passed as much data as possible in all invokes, but you
176 cannot possibly make any assumptions. It may be nothing if the file is
177 empty or it may be thousands of bytes.
182 File in which the transfered data will be saved.
187 Sets a Tcl procedure to be called by TclCurl as soon as it needs to read
188 data in order to send it to the peer. The procedure has to take one
189 parameter, which will contain the maximun numbers of bytes to read. It
190 should return the actual number of bytes read, or '0' if you want to
196 File from which the data will be transfered.
198 <DT><B>-progressproc</B>
201 Name of the Tcl procedure that will invoked by TclCurl with a frequent
202 interval during operation (roughly once per second), no matter if data
203 is being transfered or not. Unknown/unused
204 argument values passed to the callback will be set to zero (like if you
205 only download data, the upload size will remain 0), the prototype of the
208 <B>proc ProgressCallback {dltotal dlnow ultotal ulnow}</B>
211 In order to this option to work you have to set the <B>noprogress</B>
212 option to '0'. Setting this option to the empty string will restore the
213 original progress function.
215 If you transfer data with the multi interface, this procedure will not be
216 called during periods of idleness unless you call the appropriate procedure
217 that performs transfers.
219 You can pause and resume a transfer from within this procedure using the
220 <B>pause</B> and <B>resume</B> commands.
222 <DT><B>-writeheader</B>
225 Pass a the file name to be used to write the header part of the received data to.
226 The headers are guaranteed to be written one-by-one to this file and
227 only complete lines are written. Parsing headers should be easy enough using
230 <DT><B>-debugproc</B>
233 Name of the procedure that will receive the debug data produced by the
236 option, it should match the following prototype:
238 <B>debugProc {infoType data}</B>
241 where <B>infoType</B> specifies what kind of information it is (0 text,
242 1 incoming header, 2 outgoing header, 3 incoming data, 4 outgoing data,
243 5 incoming SSL data, 6 outgoing SSL data).
246 <A NAME="lbAI"> </A>
247 <H2>Error Options</H2>
251 <DT><B>-errorbuffer</B>
254 Pass a variable name where TclCurl may store human readable error
255 messages in. This may be more helpful than just the return code from the
261 Pass a file name as parameter. This is the stream to use internally instead
262 of stderr when reporting errors.
263 <DT><B>-failonerror</B>
266 A 1 parameter tells the extension to fail silently if the HTTP code
267 returned is equal or larger than 400. The default action would be to return
268 the page normally, ignoring that code.
270 This method is not fail-safe and there are occasions where non-successful response
271 codes will slip through, especially when authentication is involved
272 (response codes 401 and 407).
274 You might get some amounts of headers transferred before this situation is detected,
275 like for when a "100-continue" is received as a response to a POST/PUT and a 401
276 or 407 is received immediately afterwards.
279 <A NAME="lbAJ"> </A>
280 <H2>Network options</H2>
287 The actual URL to deal with.
289 If the given URL lacks the protocol part ("http://" or "ftp://" etc), it will
290 attempt to guess which protocol to use based on the given host name. If the
291 given protocol of the set URL is not supported, TclCurl will return the
292 <B>unsupported protocol</B> error when you call <B>perform</B>. Use
293 <B>curl::versioninfo</B> for detailed info on which protocols that are supported.
295 <B>NOTE</B>: this the one option required to be set
304 If you need to use a http proxy to access the outside world, set the
305 proxy string with this option. To specify port number in this string,
306 append :[port] to the end of the host name. The proxy string may be
307 prefixed with [protocol]:// since any such prefix will be ignored.
309 When you tell the extension to use a HTTP proxy, TclCurl will
310 transparently convert operations to HTTP even if you specify a FTP
311 URL etc. This may have an impact on what other features of the library
315 and similar FTP specifics that will not work unless you tunnel through
316 the HTTP proxy. Such tunneling is activated with
320 TclCurl respects the environment variables http_proxy, ftp_proxy,
321 all_proxy etc, if any of those are set. The use of this option does
322 however override any possibly set environment variables.
324 Setting the proxy string to "" (an empty string) will explicitly disable
325 the use of a proxy, even if there is an environment variable set for it.
327 The proxy host string can be specified the exact same way as the proxy
328 environment variables, include protocol prefix (<A HREF="http://)">http://)</A> and embedded
331 <DT><B>-proxyport</B>
334 Use this option to set the proxy port to use unless it is specified in
335 the proxy string by <B>-proxy</B>.
337 <DT><B>-proxytype</B>
340 Pass the type of the proxy. Available options are 'http', 'socks4', 'socks4a'
341 and 'socks5', with the HTTP one being default.
343 <DT><B>-httpproxytunnel</B>
346 Set the parameter to 1 to get the extension to tunnel all non-HTTP
347 operations through the given HTTP proxy. Do note that there is a big
348 difference between using a proxy and tunneling through it. If you don't know what
349 this means, you probably don't want this tunnel option.
352 <DT><B>-interface</B>
355 Pass the interface name to use as outgoing
356 network interface. The name can be an interface name, an IP address or a host
359 <DT><B>-localport</B>
362 This sets the local port number of the socket used for connection. This can
363 be used in combination with <B>-interface</B> and you are recommended to use
364 <B>localportrange</B> as well when this is set. Note the only valid port numbers
367 <DT><B>-localportrange</B>
370 This is the number of attempts TclCurl should do to find a working local port
371 number. It starts with the given <B>-localport</B> and adds
372 one to the number for each retry. Setting this value to 1 or below will make
373 TclCurl do only one try for exact port number. Note that port numbers by nature
374 are a scarce resource that will be busy at times so setting this value to something
375 too low might cause unnecessary connection setup failures.
377 <DT><B>-dnscachetimeout</B>
380 Pass the timeout in seconds. Name resolves will be kept in memory for this number
381 of seconds. Set to '0' to completely disable caching, or '-1' to make the
382 cached entries remain forever. By default, TclCurl caches this info for 60 seconds.
384 <DT><B>-dnsuseglobalcache</B>
387 If the value passed is 1, it tells TclCurl to use a global DNS cache that
388 will survive between curl handles creations and deletions. This is not thread-safe
389 as it uses a global varible.
391 <B>WARNING:</B> this option is considered obsolete. Stop using it. Switch over
392 to using the share interface instead! See <I>tclcurl_share</I>.
394 <DT><B>-buffersize</B>
397 Pass your prefered size for the receive buffer in TclCurl. The main point of this
398 would be that the write callback gets called more often and with smaller chunks.
399 This is just treated as a request, not an order. You cannot be guaranteed to
400 actually get the given size.
406 Pass the number specifying what remote port to connect to, instead of the one specified
407 in the URL or the default port for the used protocol.
409 <DT><B>-tcpnodelay</B>
413 Pass a number to specify whether the TCP_NODELAY option should be set or cleared (1 = set, 0 = clear).
414 The option is cleared by default. This will have no effect after the connection has been established.
416 Setting this option will disable TCP's Nagle algorithm. The purpose of this algorithm is to try to
417 minimize the number of small packets on the network (where "small packets" means TCP segments less
418 than the Maximum Segment Size (MSS) for the network).
420 Maximizing the amount of data sent per TCP segment is good because it amortizes the overhead of the
421 send. However, in some cases (most notably telnet or rlogin) small segments may need to be sent without
422 delay. This is less efficient than sending larger amounts of data at a time, and can contribute to
423 congestion on the network if overdone.
425 <DT><B>-addressscope</B>
428 Pass a number specifying the scope_id value to use when connecting to IPv6 link-local or site-local
432 <A NAME="lbAK"> </A>
433 <H2>Names and Passwords options</H2>
440 A 1 parameter tells the extension to scan your
443 file to find user name and password for the remote site you are about to
444 access. Do note that TclCurl does not verify that the file has the correct
445 properties set (as the standard unix ftp client does), and that only machine
446 name, user name and password is taken into account (init macros and similar
447 things are not supported).
449 You can set it to the following values:
455 The use of your ~/.netrc file is optional, and information in the URL is to
456 be preferred. The file will be scanned with the host and user name (to find
457 the password only) or with the host only, to find the first user name and
458 password after that machine, which ever information is not specified in
461 Undefined values of the option will have this effect.
465 The extension will ignore the file and use only the information in the URL.
470 This value tells the library that use of the file is required, to ignore
471 the information in the URL, and to search the file with the host only.
476 <DT><B>-netrcfile</B>
479 Pass a string containing the full path name to the file you want to use as .netrc
480 file. For the option to work, you have to set the <B>netrc</B> option to
481 <B>required</B>. If this option is omitted, and <B>netrc</B> is set, TclCurl
482 will attempt to find the a .netrc file in the current user's home directory.
487 Pass a string as parameter, which should be [username]:[password] to use for
488 the connection. Use <B>httpauth</B> to decide authentication method.
490 When using NTLM, you can set domain by prepending it to the user name and
491 separating the domain and name with a forward (/) or backward slash (\). Like
492 this: "domain/user:password" or "domain\user:password". Some HTTP servers (on
493 Windows) support this style even for Basic authentication.
495 When using HTTP and <B>-followlocation</B>, TclCurl might perform several
496 requests to possibly different hosts. TclCurl will only send this user and
497 password information to hosts using the initial host name (unless
498 <B>-unrestrictedauth</B> is set), so if TclCurl follows locations to other
499 hosts it will not send the user and password to those. This is enforced to
500 prevent accidental information leakage.
502 <DT><B>-proxyuserpwd</B>
505 Pass a string as parameter, which should be [username]:[password] to use for
506 the connection to the HTTP proxy.
511 Set to the authentication method you want, the available ones are:
517 HTTP Basic authentication. This is the default choice, and the only
518 method that is in widespread use and supported virtually everywhere.
519 It sends the user name and password over the network in plain text,
520 easily captured by others.
525 HTTP Digest authentication. Digest authentication is a more secure
526 way to do authentication over public networks than the regular
527 old-fashioned Basic method.
529 <DT><B>gssnegotiate</B>
532 HTTP GSS-Negotiate authentication. The GSS-Negotiate method, also known as
533 plain "Negotiate",was designed by Microsoft and is used in their web
534 applications. It is primarily meant as a support for Kerberos5 authentication
535 but may be also used along with another authentication methods.
540 HTTP NTLM authentication. A proprietary protocol invented and used by Microsoft.
541 It uses a challenge-response and hash concept similar to Digest, to prevent the
542 password from being eavesdropped.
547 TclCurl will automatically select the one it finds most secure.
552 It may use anything but basic, TclCurl will automaticly select the
553 one it finds most secure.
558 <DT><B>-proxyauth</B>
561 Use it to tell TclCurl which authentication method(s) you want it to use for
562 your proxy authentication. Note that for some methods, this will induce an
563 extra network round-trip. Set the actual name and password with the
564 <B>proxyuserpwd</B> option.
566 The methods are those listed above for the <B>httpauth</B> option. As of this
567 writing, only Basic and NTLM work.
570 <A NAME="lbAL"> </A>
571 <H2>HTTP options</H2>
575 <DT><B>-autoreferer</B>
578 Pass an 1 parameter to enable this. When enabled, TclCurl will
579 automatically set the Referer: field in requests where it follows a Location:
585 Sets the contents of the Accept-Encoding: header sent in an HTTP
586 request, and enables decoding of a response when a Content-Encoding:
587 header is received. Three encodings are supported: <I>identity</I>,
588 which does nothing, <I>deflate</I> which requests the server to
589 compress its response using the zlib algorithm, and <I>gzip</I> which
590 requests the gzip algorithm. Use <I>all</I> to send an
591 Accept-Encoding: header containing all supported encodings.
593 This is a request, not an order; the server may or may not do it. This
594 option must be set or else any unsolicited
595 encoding done by the server is ignored. See the special file
596 lib/README.encoding in libcurl docs for details.
598 <DT><B>-followlocation</B>
601 An 1 tells the library to follow any
602 <B>Location: header</B>
604 that the server sends as part of a HTTP header.
606 <B>NOTE</B>: this means that the extension will re-send the same
607 request on the new location and follow new <B>Location: headers</B>
608 all the way until no more such headers are returned.
609 <B>-maxredirs</B> can be used to limit the number of redirects
612 <DT><B>-unrestrictedauth</B>
615 An 1 parameter tells the extension it can continue
616 to send authentication (user+password) when following
617 locations, even when hostname changed. Note that this
618 is meaningful only when setting <B>-followlocation</B>.
620 <DT><B>-maxredirs</B>
623 Sets the redirection limit. If that many redirections have been followed,
624 the next redirect will cause an error. This option only makes sense if the
625 <B>-followlocation</B> option is used at the same time. Setting the limit
626 to 0 will make libcurl refuse any redirect. Set it to -1 for an infinite
627 number of redirects (which is the default)
632 An 1 tells TclCurl to respect RFC 2616/10.3.2 and not
633 convert POST requests into GET requests when following a 301 redirection. The
634 non-RFC behaviour is ubiquitous in web browsers, so the conversion is done
635 by default to maintain consistency. However, a server may require
636 a POST to remain a POST after such a redirection. This option is meaningful
637 only when setting <B>-followlocation</B>.
642 An 1 parameter tells the extension to use HTTP PUT a file. The file to put
643 must be set with <B>-infile</B> and <B>-infilesize</B>.
645 This option is deprecated starting with version 0.12.1, you should use <B>-upload</B>.
650 An 1 parameter tells the library to do a regular HTTP post. This is a
651 normal application/x-www-form-urlencoded kind, which is the most commonly used
652 one by HTML forms. See the <B>-postfields</B> option for how to specify the
653 data to post and <B>-postfieldsize</B> about how to set the data size.
655 Use the <B>-postfields</B> option to specify what data to post and <B>-postfieldsize</B>
656 to set the data size. Optionally, you can provide data to POST using the <B>-readproc</B>
659 You can override the default POST Content-Type: header by setting your own with
662 Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header.
663 You can disable this header with <B>-httpheader</B> as usual.
665 If you use POST to a HTTP 1.1 server, you can send data without knowing the
666 size before starting the POST if you use chunked encoding. You enable this
667 by adding a header like "Transfer-Encoding: chunked" with <B>-httpheader</B>.
668 With HTTP 1.0 or without chunked transfer, you must specify the size in the
671 When setting <B>post</B> to an 1 value, it will automatically set
674 NOTE: if you have issued a POST request and want to make a HEAD or GET instead, you must
675 explicitly pick the new request type using <B>-nobody</B> or <B>-httpget</B> or similar.
677 <DT><B>-postfields</B>
680 Pass a string as parameter, which should be the full data to post in a HTTP
681 POST operation. You must make sure that the data is formatted the way you
682 want the server to receive it. TclCurl will not convert or encode it for you.
683 Most web servers will assume this data to be url-encoded.
685 This is a normal application/x-www-form-urlencoded kind,
686 which is the most commonly used one by HTML forms.
688 If you want to do a zero-byte POST, you need to set
689 <B>-postfieldsize</B> explicitly to zero, as simply setting
690 <B>-postfields</B> to NULL or "" just effectively disables the sending
691 of the specified string. TclCurl will instead assume that the POST
692 data will be send using the read callback!
694 Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header.
695 You can disable this header with <B>-httpheader</B> as usual.
697 <B>Note</B>: to make multipart/formdata posts (aka rfc1867-posts), check out
698 <B>-httppost</B> option.
700 <DT><B>-postfieldsize</B>
703 If you want to post data to the server without letting TclCurl do a strlen()
704 to measure the data size, this option must be used. Also, when this option is
705 used, you can post fully binary data which otherwise is likely to fail. If
706 this size is set to zero, the library will use strlen() to get the data
712 Tells TclCurl you want a multipart/formdata HTTP POST to be made and you
713 instruct what data to pass on to the server through a
717 <B>This is the only case where the data is reset after a transfer.</B>
719 First, there are some basics you need to understand about multipart/formdata
720 posts. Each part consists of at least a <B>NAME</B> and a <B>CONTENTS</B> part. If the part
721 is made for file upload, there are also a stored <B>CONTENT-TYPE</B> and a
722 <B>FILENAME</B>. Below, we'll discuss on what options you use to set these
723 properties in the parts you want to add to your post.
725 The list must contain a <B>'name'</B> tag with the name of the section followed
726 by a string with the name, there are three tags to indicate the value of
727 the section: <B>'value'</B> followed by a string with the data to post, <B>'file'</B>
728 followed by the name of the file to post and <B>'contenttype'</B> with the
729 type of the data (text/plain, image/jpg, ...), you can also indicate a <I>false</I>
730 file name with <B>'filename'</B>, this is useful in case the server checks if the given
731 file name is valid, for example, by testing if it starts with 'c:\' as any real file
732 name does or if you want to include the full path of the file to post. You can also post
733 the content of a variable as if it were a file with the options <B>'bufferName'</B> and
734 <B>'buffer'</B> or use <B>'filecontent'</B> followed by a file name to read that file and
735 use the contents as data.
737 Should you need to specify extra headers for the form POST section, use
738 <B>'contentheader</B>' followed by a list with the headers to post.
740 Please see 'httpPost.tcl' and 'httpBufferPost.tcl' for examples.
742 If TclCurl can't set the data to post an error will be returned:
748 If the memory allocation fails.
752 If one option is given twice for one form.
756 If an empty string was given.
760 If an unknown option was used.
764 If the some form info is not complete (or error)
768 If an illegal option is used in an array.
772 TclCurl has no http support.
780 Pass a string as parameter. It will be used to set the
783 header in the http request sent to the remote server. This can be used to
784 fool servers or scripts. You can also set any custom header with
788 <DT><B>-useragent</B>
791 Pass a string as parameter. It will be used to set the
794 header in the http request sent to the remote server. This can be used to fool
795 servers or scripts. You can also set any custom header with
799 <DT><B>-httpheader</B>
805 with the HTTP headers to pass to the server in your request.
806 If you add a header that is otherwise generated
807 and used by TclCurl internally, your added one will be used instead. If you
808 add a header with no contents as in 'Accept:', the internally used header will
809 just get disabled. Thus, using this option you can add new headers, replace
810 and remove internal headers.
812 The headers included in the linked list must not be CRLF-terminated, because
813 TclCurl adds CRLF after each header item. Failure to comply with this will
814 result in strange bugs because the server will most likely ignore part of the
815 headers you specified.
817 The first line in a request (containing the method, usually a GET or POST) is
818 not a header and cannot be replaced using this option. Only the lines
819 following the request-line are headers. Adding this method line in this list
820 of headers will only cause your request to send an invalid header.
822 <B>NOTE</B>:The most commonly replaced headers have "shortcuts" in the options:
823 <B>cookie, useragent,</B>
829 <DT><B>-http200aliases</B>
832 Pass a list of aliases to be treated as valid HTTP 200 responses. Some servers
833 respond with a custom header response line. For example, IceCast servers respond
834 with "ICY 200 OK". By including this string in your list of aliases, the
835 response will be treated as a valid HTTP header line such as "HTTP/1.0 200 OK".
837 <B>NOTE</B>:The alias itself is not parsed for any version strings. Before version
838 7.16.3, TclCurl used the value set by option <B>httpversion</B>, but starting with
839 7.16.3 the protocol is assumed to match HTTP 1.0 when an alias matched.
844 Pass a string as parameter. It will be used to
845 set a cookie in the http request. The format of the string should be
847 what the cookie should contain.
849 If you need to set mulitple cookies, you need to set them all using
850 a single option and thus you need to concatenate them all in one single string.
851 Set multiple cookies in one string like this: "name1=content1; name2=content2;"
854 Note that this option sets the cookie header explictly in the outgoing request(s).
855 If multiple requests are done due to authentication, followed redirections or similar,
856 they will all get this cookie passed on.
858 Using this option multiple times will only make the latest string override
861 <DT><B>-cookiefile</B>
864 Pass a string as parameter. It should contain the name of your file holding
865 cookie data. The cookie data may be in netscape cookie data format or just
866 regular HTTP-style headers dumped to a file.
868 Given an empty or non-existing file, this option will enable cookies for this
869 curl handle, making it understand and parse received cookies and then use
870 matching cookies in future requests.
872 If you use this option multiple times, you add more files to read.
874 <DT><B>-cookiejar</B>
877 Pass a file name in which TclCurl will dump all internally known cookies
879 <B>curlHandle cleanup</B>
881 is called. If no cookies are known, no file will be created.
882 Specify "-" to have the cookies written to stdout.
884 Using this option also enables cookies for this session, so if you, for
885 example, follow a location it will make matching cookies get sent accordingly.
887 TclCurl will not and cannot report an error for this. Using '<B>verbose</B>'
888 will get a warning to display, but that is the only visible feedback you get
889 about this possibly lethal situation.
891 <DT><B>-cookiesession</B>
894 Pass an 1 to mark this as a new cookie "session". It will
895 force TclCurl to ignore all cookies it is about to load that are "session
896 cookies" from the previous session. By default, TclCurl always stores and
897 loads all cookies, independent of whether they are session cookies are not.
898 Session cookies are cookies without expiry date and they are meant to be
899 alive and existing for this "session" only.
901 <DT><B>-cookielist</B>
904 Pass a string with a cookie. The cookie can be either in Netscape / Mozilla
905 format or just regular HTTP-style header (Set-Cookie: ...) format. If the
906 cookie engine was not enabled it will be enabled. Passing a
907 magic string "ALL" will erase all known cookies while "FLUSH" will write
908 all cookies known by TclCurl to the file specified by <B>-cookiejar</B>.
913 If set to 1 forces the HTTP request to get back to GET, usable if
914 POST, PUT or a custom request have been used previously with the
917 When setting <B>httpget</B> to 1, <B>nobody</B> will automatically be set to 0.
919 <DT><B>-httpversion</B>
922 Set to one of the values decribed below, they force TclCurl to use the
923 specific http versions. It should only be used if you really MUST do
924 that because of a silly remote server.
930 We do not care about what version the library uses. TclCurl will use whatever
935 Enforce HTTP 1.0 requests.
939 Enforce HTTP 1.1 requests.
944 <DT><B>-ignorecontentlength</B>
947 Ignore the Content-Length header. This is useful for Apache 1.x (and similar
948 servers) which will report incorrect content length for files over 2
949 gigabytes. If this option is used, TclCurl will not be able to accurately
950 report progress, and will simply stop the download when the server ends the
953 <DT><B>-httpcontentdecoding</B>
956 Set to zero to disable content decoding. If set to 1 it is enabled. Note however
957 that TclCurl has no default content decoding but requires you to use <B>encoding</B> for that.
959 <DT><B>-httptransferencoding</B>
962 Set to zero to disable transfer decoding, if set to 1 it is enabled (default). TclCurl does
963 chunked transfer decoding by default unless this option is set to zero.
966 <A NAME="lbAM"> </A>
974 Pass a string as parameter. It will be used to
975 get the IP address to use for the ftp PORT instruction. The PORT instruction
976 tells the remote server to connect to our specified IP address. The string may
977 be a plain IP address, a host name, a network interface name (under unix) or
978 just a '-' to let the library use your systems default IP address. Default FTP
979 operations are passive, and thus will not use PORT.
984 Pass a <B>list</B> list with the FTP or SFTP commands to pass to the server prior to your
985 ftp request. This will be done before any other FTP commands are issued (even
986 before the CWD command).If you do not want to transfer any files, set
987 <B>nobody</B> to '1' and <B>header</B> to '0'.
989 Keep in mind the commands to send must be 'raw' ftp commands, for example, to
990 create a directory you need to send <B>mkd Test</B>, not <B>mkdir Test</B>.
992 Valid SFTP commands are: chgrp, chmod, chown, ln, mkdir, pwd, rename, rm,
995 <DT><B>-postquote</B>
998 Pass a <B>list</B> with the FTP commands to pass to the server after your
999 ftp transfer request. If you do not want to transfer any files, set
1000 <B>nobody</B> to '1' and <B>header</B> to '0'.
1002 <DT><B>-prequote</B>
1005 Pass a <B>list</B> of FTP or SFTP commands to pass to the server after the
1006 transfer type is set.
1008 <DT><B>-dirlistonly</B>
1011 A 1 tells the library to just list the names of files in a
1012 directory, instead of doing a full directory listing that would include file
1013 sizes, dates etc. It works with both FTP and SFTP urls.
1015 This causes an FTP NLST command to be sent. Beware that some FTP servers list
1016 only files in their response to NLST, they might not include subdirectories
1022 A 1 parameter tells the extension to append to the remote file instead of
1023 overwriting it. This is only useful when uploading to a ftp site.
1025 <DT><B>-ftpuseeprt</B>
1028 Set to 1 to tell TclCurl to use the EPRT (and LPRT) command when doing
1029 active FTP downloads (which is enabled by '<B>ftpport</B>'). Using EPRT means
1030 that it will first attempt to use EPRT and then LPRT before using PORT, if
1031 you pass zero to this option, it will not try using EPRT or LPRT, only plain PORT.
1033 <DT><B>-ftpuseepvs</B>
1036 Set to one to tell TclCurl to use the EPSV command when doing passive FTP
1037 downloads (which it always does by default). Using EPSV means that it will
1038 first attempt to use EPSV before using PASV, but if you pass a zero to this
1039 option, it will not try using EPSV, only plain PASV.
1041 <DT><B>-ftpcreatemissingdirs</B>
1044 If set to 1, TclCurl will attempt to create any remote directory that it
1045 fails to CWD into. CWD is the command that changes working directory.
1047 This setting also applies to SFTP-connections. TclCurl will attempt to create
1048 the remote directory if it can't obtain a handle to the target-location. The
1049 creation will fail if a file of the same name as the directory to create
1050 already exists or lack of permissions prevents creation.
1052 <DT><B>-ftpresponsetimeout</B>
1055 Causes TclCurl to set a timeout period (in seconds) on the amount of time that
1056 the server is allowed to take in order to generate a response message for a
1057 command before the session is considered hung. Note that while TclCurl is waiting
1058 for a response, this value overrides <B>timeout</B>. It is recommended that if used
1059 in conjunction with <B>timeout</B>, you set it to a value smaller than <B>timeout</B>.
1061 <DT><B>-ftpalternativetouser </B>
1064 Pass a string which will be used to authenticate if the usual FTP "USER user" and
1065 "PASS password" negotiation fails. This is currently only known to be required when
1066 connecting to Tumbleweed's Secure Transport FTPS server using client certificates for
1069 <DT><B>-ftpskippasvip</B>
1072 If set to 1, it instructs TclCurl not to use the IP address the
1073 server suggests in its 227-response to TclCurl's PASV command when TclCurl
1074 connects the data connection. Instead TclCurl will re-use the same IP address
1075 it already uses for the control connection. But it will use the port number
1076 from the 227-response.
1078 This option has no effect if PORT, EPRT or EPSV is used instead of PASV.
1083 You can use ftps:// URLs to explicitly switch on SSL/TSL for the control
1084 connection and the data connection.
1086 Alternatively, and what seems to be the recommended way, you can set the
1087 option to one of these values:
1089 <DL COMPACT><DT><DD>
1094 Do not attempt to use SSL
1098 Try using SSL, proceed anyway otherwise.
1102 Use SSL for the control conecction or fail with "use ssl failed" (64).
1106 Use SSL for all communication or fail with "use ssl failed" (64).
1111 <DT><B>-ftpsslauth</B>
1115 Pass TclCurl one of the values from below, to alter how TclCurl issues
1116 "AUTH TLS" or "AUTH SSL" when FTP over SSL is activated (see <B>-ftpssl</B>).
1118 You may need this option because of servers like BSDFTPD-SSL from
1119 <A HREF="http://bsdftpd-ssl.sc.ru/">http://bsdftpd-ssl.sc.ru/</A> "which won't work properly when "AUTH SSL" is issued
1120 (although the server responds fine and everything) but requires "AUTH TLS"
1123 <DL COMPACT><DT><DD>
1128 Allows TclCurl to decide.
1132 Try "AUTH SSL" first, and only if that fails try "AUTH TLS".
1136 Try "AUTH TLS" first, and only if that fails try "AUTH SSL".
1141 <DT><B>-ftpsslccc </B>
1144 Set it to make TclCurl use CCC (Clear Command Channel). It shuts down the
1145 SSL/TLS layer after authenticating. The rest of the control channel
1146 communication will be unencrypted. This allows NAT routers to follow the
1147 FTP transaction. Possible values are:
1149 <DL COMPACT><DT><DD>
1154 Do not attempt to use CCC.
1158 Do not initiate the shutdown, wait for the server to do it. Do not send a reply.
1162 Initiate the shutdown and wait for a reply.
1167 <DT><B>-ftpaccount</B>
1170 Pass string (or "" to disable). When an FTP server asks for "account data" after
1171 user name and password has been provided, this data is sent off using the ACCT
1174 <DT><B>-ftpfilemethod</B>
1177 It allows three values:
1178 <DL COMPACT><DT><DD>
1183 The default, TclCurl will do a single CWD operation for each path part in the given
1184 URL. For deep hierarchies this means very many commands. This is how RFC1738 says it
1189 No CWD at all is done, TclCurl will do SIZE, RETR, STOR, etc and give a full path to
1191 <DT><B>singlecwd</B>
1194 Make one CWD with the full target directory and then operate on the file "normally".
1195 This is somewhat more standards compliant than 'nocwd' but without the full penalty of 'multicwd'.
1201 <A NAME="lbAN"> </A>
1202 <H2>Protocol options</H2>
1206 <DT><B>-transfertext</B>
1209 A 1 tells the extension to use ASCII mode for ftp transfers,
1210 instead of the default binary transfer. For win32 systems it does not set the
1211 stdout to binary mode. This option can be usable when transferring text data
1212 between systems with different views on certain characters, such as newlines
1215 <B>NOTE:</B> TclCurl does not do a complete ASCII conversion when doing ASCII
1216 transfers over FTP. This is a known limitation/flaw that nobody has
1217 rectified. TclCurl simply sets the mode to ascii and performs a standard
1220 <DT><B>-proxytransfermode</B>
1223 If set to 1, TclCurl sets the transfer mode (binary or ASCII) for FTP transfers
1224 done via an HTTP proxy, by appending ;type=a or ;type=i to the URL.
1225 Without this setting, or it being set to 0, the default, <B>-transfertext</B> has
1226 no effect when doing FTP via a proxy. Beware that not all proxies support this feature.
1231 Convert unix newlines to CRLF newlines on FTP transfers.
1236 Pass a string as parameter, which should contain the specified range you
1237 want. It should be in the format
1240 , where X or Y may be left out. HTTP
1241 transfers also support several intervals, separated with commas as in
1244 Using this kind of multiple intervals will cause the HTTP server to send the
1245 response document in pieces (using standard MIME separation techniques).
1247 Ranges only work on HTTP, FTP and FILE transfers.
1249 <DT><B>-resumefrom</B>
1252 Pass the offset in number of bytes that you want the transfer to start from.
1253 Set this option to 0 to make the transfer start from the beginning
1254 (effectively disabling resume).
1256 For FTP, set this option to -1 to make the transfer start from the end of the
1257 target file (useful to continue an interrupted upload).
1259 <DT><B>-customrequest</B>
1262 Pass a string as parameter. It will be used instead of GET or HEAD when doing
1263 the HTTP request. This is useful for doing DELETE or other more obscure HTTP
1264 requests. Do not do this at will, make sure your server supports the command first.
1266 Note that TclCurl will still act and assume the keyword it would use if you
1267 do not set your custom and it will act according to that. Thus, changing this
1268 to a HEAD when TclCurl otherwise would do a GET might cause TclCurl to act funny,
1269 and similar. To switch to a proper HEAD, use <B>-nobody</B>, to switch to a proper
1270 POST, use <B>-post</B> or <B>-postfields</B> and so on.
1272 <DT><B>-filetime</B>
1275 If you pass a 1, TclCurl will attempt to get the
1276 modification date of the remote document in this operation. This requires that
1277 the remote server sends the time or replies to a time querying command. The
1278 getinfo procedure with the
1281 argument can be used after a transfer to extract the received time (if any).
1286 A 1 tells the library not to include the body-part in the
1287 output. This is only relevant for protocols that have a separate header and
1288 body part. On HTTP(S) servers, this will make TclCurl do a HEAD request.
1290 To change request to GET, you should use <B>httpget</B>. Change request
1291 to POST with <B>post</B> etc.
1293 <DT><B>-infilesize</B>
1296 When uploading a file to a remote site, this option should be used to tell
1297 TclCurl what the expected size of the infile is.
1299 This option is mandatory for uploading using SCP.
1304 A 1 tells the library to prepare for an upload. The
1305 <B>-infile</B> and <B>-infilesize</B> options are also interesting for uploads.
1306 If the protocol is HTTP, uploading means using the PUT request unless you tell
1309 Using PUT with HTTP 1.1 implies the use of a "Expect: 100-continue" header.
1310 You can disable this header with <B>-httpheader</B> as usual.
1312 If you use PUT to a HTTP 1.1 server, you can upload data without knowing the
1313 size before starting the transfer if you use chunked encoding. You enable this
1314 by adding a header like "Transfer-Encoding: chunked" with <B>-httpheader</B>.
1315 With HTTP 1.0 or without chunked transfer, you must specify the size.
1317 <DT><B>-maxfilesize</B>
1320 This allows you to specify the maximum size (in bytes) of a file to download.
1321 If the file requested is larger than this value, the transfer will not start
1322 and error 'filesize exceeded' (63) will be returned.
1324 NOTE: The file size is not always known prior to download, and for such files
1325 this option has no effect even if the file transfer ends up being larger than
1326 this given limit. This concerns both FTP and HTTP transfers.
1328 <DT><B>-timecondition</B>
1331 This defines how the <B>timevalue</B> value is treated. You can set this
1332 parameter to <B>ifmodsince</B> or <B>ifunmodsince</B>. This feature applies to
1335 <DT><B>-timevalue</B>
1338 This should be the time in seconds since 1 jan 1970, and the time will be
1339 used in a condition as specified with <B>timecondition</B>.
1343 <A NAME="lbAO"> </A>
1344 <H2>Connection options</H2>
1351 Pass the maximum time in seconds that you allow
1352 the TclCurl transfer operation to take. Do note that normally, name lookups
1353 may take a considerable time and that limiting the operation to less than a
1354 few minutes risks aborting perfectly normal operations. This option will
1355 cause libcurl to use the SIGALRM to enable time-outing system calls.
1357 In unix-like systems, this might cause signals to be used unless
1358 <B>-nosignal</B> is used.
1360 <DT><B>-timeoutms</B>
1363 Like <B>timeout</B> but takes a number of milliseconds instead. If libcurl is
1364 built to use the standard system name resolver, that part will still use
1365 full-second resolution for timeouts.
1367 <DT><B>-lowspeedlimit</B>
1370 Pass the speed in bytes per second that the transfer should be below during
1373 seconds for the extension to consider it too slow and abort.
1375 <DT><B>-lowspeedtime</B>
1378 Pass the time in seconds that the transfer should be below the
1379 <B>lowspeedlimit</B>
1381 for the extension to consider it too slow and abort.
1383 <DT><B>-maxsendspeed</B>
1386 Pass a speed in bytes per seconds. If an upload exceeds this speed on cumulative
1387 average during the transfer, the transfer will pause to keep the average rate less
1388 than or equal to the parameter value. Defaults to unlimited speed.
1390 <DT><B>-maxrecvspeed</B>
1393 Pass a speed in bytes per second. If a download exceeds this speed on cumulative
1394 average during the transfer, the transfer will pause to keep the average rate less
1395 than or equal to the parameter value. Defaults to unlimited speed.
1397 <DT><B>-maxconnects</B>
1400 Sets the persistant connection cache size in all the protocols that support
1401 persistent conecctions. The set amount will be the maximum amount of simultaneous
1402 connections that TclCurl may cache in this easy handle. Default is 5, and there
1403 isn't much point in changing this value unless you are perfectly aware of how this
1404 work and changes TclCurl's behaviour.
1406 When reaching the maximum limit, TclCurl closes the oldest connection in the cache
1407 to prevent the number of open connections to increase.
1409 <B>Note</B>: if you have already performed transfers with this curl handle,
1413 than before may cause open connections to unnecessarily get closed.
1415 <B>Note</B> that if you add this easy handle to a multi handle, this setting is not
1416 being acknowledged, instead you must configure the multi handle its own
1417 <B>maxconnects</B> option.
1419 <DT><B>-connecttimeout</B>
1422 Maximum time in seconds that you allow the
1423 connection to the server to take. This only limits the connection phase, once
1424 it has connected, this option is of no more use. Set to zero to disable
1425 connection timeout (it will then only timeout on the internal timeouts).
1427 In unix-like systems, this might cause signals to be used unless
1428 <B>-nosignal</B> is set.
1430 <DT><B>-connecttimeoutms</B>
1433 Like <B>connecttimeout</B> but takes a number of milliseconds instead. If libcurl
1434 is built to use the standard system name resolver, that part will still use
1435 full-second resolution for timeouts.
1437 <DT><B>-ipresolve</B>
1440 Allows an application to select what kind of IP addresses to use when
1441 resolving host names. This is only interesting when using host names
1442 that resolve addresses using more than one version of IP. The allowed
1444 <DL COMPACT><DT><DD>
1449 Default, resolves addresses to all IP versions that your system allows.
1453 Resolve to ipv4 addresses.
1457 Resolve to ipv6 addresses.
1463 <A NAME="lbAP"> </A>
1464 <H2>SSL and security options</H2>
1471 Pass a string as parameter. The string should be the file name of your certificate.
1472 The default format is "PEM" and can be changed with <B>-sslcerttype</B>.
1474 With NSS this is the nickname of the certificate you wish to authenticate with.
1476 <DT><B>-sslcerttype</B>
1479 Pass a string as parameter. The string should be the format of your certificate.
1480 Supported formats are "PEM" and "DER".
1485 Pass a pointer to a zero terminated string as parameter. The string should be
1486 the file name of your private key. The default format is "PEM" and can be
1487 changed with <B>-sslkeytype</B>.
1489 <DT><B>-sslkeytype</B>
1492 Pass a pointer to a zero terminated string as parameter. The string should be
1493 the format of your private key. Supported formats are "PEM", "DER" and "ENG"
1495 <B>NOTE:</B>The format "ENG" enables you to load the private key from a crypto
1496 engine. in this case <B>-sslkey</B> is used as an identifier passed to
1497 the engine. You have to set the crypto engine with <B>-sslengine</B>. The "DER"
1498 format key file currently does not work because of a bug in OpenSSL.
1500 <DT><B>-keypasswd</B>
1503 Pass a string as parameter. It will be used as the password required to use the
1504 <B>-sslkey</B> or <B>-sshprivatekeyfile</B> private key.
1506 You never need a pass phrase to load a certificate but you need one to load you
1509 This option used to be known as <B>-sslkeypasswd</B> and <B>-sslcertpasswd</B>.
1511 <DT><B>-sslengine</B>
1514 Pass a string as parameter. It will be used as the identifier for the crypto
1515 engine you want to use for your private key.
1517 <B>NOTE:</B>If the crypto device cannot be loaded, an error will be returned.
1519 <DT><B>-sslenginedefault</B>
1522 Pass a 1 to set the actual crypto engine as the default for (asymmetric) crypto operations.
1524 <B>NOTE:</B>If the crypto device cannot be set, an error will be returned.
1526 <DT><B>-sslversion</B>
1529 Use it to set what version of SSL/TLS to use. The available options are:
1530 <DL COMPACT><DT><DD>
1535 The default action. This will attempt to figure out the remote SSL protocol version,
1536 i.e. either SSLv3 or TLSv1 (but not SSLv2, which became disabled by default with 7.18.1).
1553 <DT><B>-sslverifypeer</B>
1556 This option determines whether TclCurl verifies the authenticity of the peer's certificate.
1557 A 1 means it verifies; zero means it doesn't. The default is 1.
1559 When negotiating an SSL connection, the server sends a certificate indicating its identity.
1560 TclCurl verifies whether the certificate is authentic, i.e. that you can trust that the
1561 server is who the certificate says it is. This trust is based on a chain of digital signatures,
1562 rooted in certification authority (CA) certificates you supply.
1564 TclCurl uses a default bundle of CA certificates that comes with libcurl but you can specify
1565 alternate certificates with the <B>-cainfo</B> or the <B>-capath</B> options.
1567 When <B>-sslverifypeer</B> is nonzero, and the verification fails to prove that the certificate
1568 is authentic, the connection fails. When the option is zero, the connection succeeds regardless.
1570 Authenticating the certificate is not by itself very useful. You typically want to ensure
1571 that the server, as authentically identified by its certificate, is the server you mean to
1572 be talking to, use <B>-sslverifyhost</B> to control that.
1577 Pass a file naming holding the certificate to verify the peer with. This only
1578 makes sense when used in combination with the <B>-sslverifypeer</B> option, if
1579 it is set to zero <B>-cainfo</B> need not even indicate an accessible file.
1581 When built against NSS this is the directory that the NSS certificate database
1584 <DT><B>-issuercert</B>
1587 Pass a string naming a file holding a CA certificate in PEM format. If the option
1588 is set, an additional check against the peer certificate is performed to verify
1589 the issuer is indeed the one associated with the certificate provided by the option.
1590 This additional check is useful in multi-level PKI where one need to enforce the peer
1591 certificate is from a specific branch of the tree.
1593 This option makes sense only when used in combination with the <B>-sslverifypeer</B>
1594 option. Otherwise, the result of the check is not considered as failure.
1599 Pass the directory holding multiple CA certificates to verify the peer with.
1600 The certificate directory must be prepared using the openssl c_rehash utility.
1601 This only makes sense when used in combination with the <B>-sslverifypeer</B>
1602 option, if it is set to zero, <B>-capath</B> need not even indicate an accessible
1605 This option apparently does not work in Windows due to some limitation in openssl.
1607 This option is OpenSSL-specific and does nothing if libcurl is built to use GnuTLS.
1612 Pass a string naming a file with the concatenation of CRL (in PEM format) to use in
1613 the certificate validation that occurs during the SSL exchange.
1615 When libcurl is built to use NSS or GnuTLS, there is no way to influence the use of
1616 CRL passed to help in the verification process. When built with OpenSSL support,
1617 X509_V_FLAG_CRL_CHECK and X509_V_FLAG_CRL_CHECK_ALL are both set, requiring CRL
1618 check against all the elements of the certificate chain if a CRL file is passed.
1620 This option makes sense only when used in combination with the <B>-sslverifypeer</B>
1623 <DT><B>-randomfile</B>
1626 Pass a file name. The file will be used to read from to seed the random engine
1627 for SSL. The more random the specified file is, the more secure will the SSL
1630 <DT><B>-egdsocket</B>
1633 Pass a path name to the Entropy Gathering Daemon socket. It will be used to seed
1634 the random engine for SSL.
1636 <DT><B>-sslverifyhost</B>
1639 This option determines whether TclCurl verifies that the server claims to be
1640 who you want it to be.
1642 When negotiating an SSL connection, the server sends a certificate
1643 indicating its identity.
1645 When <B>-sslverifyhost</B> is set to 2, that certificate must indicate
1646 that the server is the server to which you meant to connect, or the
1649 TclCurl considers the server the intended one when the Common Name field
1650 or a Subject Alternate Name field in the certificate matches the host
1651 name in the URL to which you told Curl to connect.
1653 When set to 1, the certificate must contain a Common Name field,
1654 but it does not matter what name it says. (This is not ordinarily a
1657 When the value is 0, the connection succeeds regardless of the names in
1662 This option controls the identity that the server <I>claims</I>. The server
1663 could be lying. To control lying, see <B>sslverifypeer</B>.
1665 <DT><B>-sslcypherlist</B>
1668 Pass a string holding the ciphers to use for the SSL connection. The list must
1669 consists of one or more cipher strings separated by colons. Commas or spaces
1670 are also acceptable separators but colons are normally used, , - and + can be
1673 For OpenSSL and GnuTLS valid examples of cipher lists include 'RC4-SHA', 'SHA1+DES',
1676 You will find more details about cipher lists on this URL:
1677 <BR> <A HREF="http://www.openssl.org/docs/apps/ciphers.html">http://www.openssl.org/docs/apps/ciphers.html</A>
1679 For NSS valid examples of cipher lists include 'rsa_rc4_128_md5', 'rsa_aes_128_sha',
1680 etc. With NSS you don't add/remove ciphers. If you use this option then all known
1681 ciphers are disabled and only those passed in are enabled.
1683 You'll find more details about the NSS cipher lists on this URL:
1684 <BR> <A HREF="http://directory.fedora.redhat.com/docs/mod_nss.html">http://directory.fedora.redhat.com/docs/mod_nss.html</A>
1686 <DT><B>-sslsessionidcache</B>
1689 Pass a 0 to disable TclCurl's use of SSL session-ID caching or a 1 to enable it.
1690 By default all transfers are done using the cache. Note that while nothing ever
1691 should get hurt by attempting to reuse SSL session-IDs, there seem to be broken SSL
1692 implementations in the wild that may require you to disable this in order for you to
1695 <DT><B>-krblevel</B>
1698 Set the kerberos security level for FTP, this also enables kerberos awareness.
1699 This is a string, 'clear', 'safe', 'confidential' or 'private'. If the string
1700 is set but does not match one of these, 'private' will be used. Set the string
1701 to NULL to disable kerberos4. Set the string to "" to disable kerberos
1705 <A NAME="lbAQ"> </A>
1706 <H2>SSH options</H2>
1710 <DT><B>-sshauthtypes</B>
1713 The allowed types are:
1715 <DL COMPACT><DT><DD>
1717 <DT><B>publickey</B>
1732 To let TclCurl pick one
1737 <DT><B>-sshhostpublickeymd5</B>
1740 Pass a string containing 32 hexadecimal digits. The string should be the 128
1741 bit MD5 cheksum of the remote host public key, and TclCurl will reject the
1742 connection to the host unless the md5sums match. This option is only for SCP
1745 <DT><B>-publickeyfile</B>
1748 Pass the file name for your public key. If not used, TclCurl defaults to using <B>~/.ssh/id_dsa.pub</B>.
1750 <DT><B>-privatekeyfile</B>
1753 Pass the file name for your private key. If not used, TclCurl defaults to using <B>~/.ssh/id_dsa</B>.
1754 If the file is password-protected, set the password with <B>-keypasswd</B>.
1757 <A NAME="lbAR"> </A>
1758 <H2>Other options</H2>
1762 <DT><B>-headervar</B>
1765 Name of the Tcl array variable where TclCurl will store the headers returned
1768 When a server sends a chunked encoded transfer, it may contain a
1769 trailer. That trailer is identical to a HTTP header and if such a trailer is
1770 received it is passed to the application using this callback as well. There
1771 are several ways to detect it being a trailer and not an ordinary header: 1)
1772 it comes after the response-body. 2) it comes after the final header line (CR
1773 LF) 3) a Trailer: header among the response-headers mention what header to
1774 expect in the trailer.
1779 Name of the Tcl variable where TclCurl will store the file requested, the file
1780 may contain text or binary data.
1782 <DT><B>-canceltransvar</B>
1785 Name of a Tcl variable, in case you have defined a procedure to call with
1786 <B>-progressproc</B> setting this variable to '1' will cancel the transfer.
1791 Executes the given command after the transfer is done, since it only works
1792 with blocking transfers, it is pretty much useless.
1797 Pass a share handle as a parameter. The share handle must have been created by
1798 a previous call to <B>curl::shareinit</B>. Setting this option, will make this
1799 handle use the data from the shared handle instead of keeping the data to itself.
1800 See <I>tclcurl_share</I> for details.
1802 <DT><B>-newfileperms</B>
1805 Pass a number as a parameter, containing the value of the permissions that will
1806 be assigned to newly created files on the remote server. The default value is 0644,
1807 but any valid value can be used. The only protocols that can use this are <A HREF="sftp://,">sftp://,</A>
1808 scp:// and <A HREF="file://.">file://.</A>
1810 <DT><B>-newdirectoryperms</B>
1813 Pass a number as a parameter, containing the value of the permissions that will be
1814 assigned to newly created directories on the remote server. The default value is 0755,
1815 but any valid value can be used. The only protocols that can use this are <A HREF="sftp://,">sftp://,</A> scp://
1816 and <A HREF="file://.">file://.</A>
1819 <A NAME="lbAS"> </A>
1820 <H2>NOT SUPPORTED</H2>
1822 Some of the options libcurl offers are not supported, I don't think them
1823 worth supporting in TclCurl but if you need one of them don't forget to
1826 <B>CURLOPT_FRESH_CONNECT, CURLOPT_FORBID_REUSE, CURLOPT_PRIVATE,</B>
1828 <B>CURLOPT_SSL_CTX_FUNCTION, CURLOPT_SSL_CTX_DATA, CURLOPT_SSL_CTX_FUNCTION and</B>
1830 <B>CURLOPT_CONNECT_ONLY, CURLOPT_OPENSOCKETFUNCTION, CURLOPT_OPENSOCKETDATA.</B>
1833 <A NAME="lbAT"> </A>
1834 <H2>curlHandle perform</H2>
1836 This procedure is called after the
1842 calls are made, and will perform the transfer as described in the options.
1844 It must be called with the same
1845 <I>curlHandle</I> <B>curl::init</B> call returned.
1846 You can do any amount of calls to perform while using the same handle. If you
1847 intend to transfer more than one file, you are even encouraged to do
1848 so. TclCurl will then attempt to re-use the same connection for the following
1849 transfers, thus making the operations faster, less CPU intense and using less
1850 network resources. Just note that you will have to use
1853 between the invokes to set options for the following perform.
1855 You must never call this procedure simultaneously from two places using the
1856 same handle. Let it return first before invoking it another time. If
1857 you want parallel transfers, you must use several curl handles.
1859 <DT><B>RETURN VALUE</B>
1868 there will be a readable error message.
1869 The error codes are:
1871 Unsupported protocol. This build of TclCurl has no support for this protocol.
1873 Very early initialization code failed. This is likely to be and internal error
1876 URL malformat. The syntax was not correct.
1878 Couldn't resolve proxy. The given proxy host could not be resolved.
1880 Couldn't resolve host. The given remote host was not resolved.
1882 Failed to connect to host or proxy.
1884 FTP weird server reply. The server sent data TclCurl couldn't parse.
1885 The given remote server is probably not an OK FTP server.
1887 We were denied access to the resource given in the URL. For FTP, this occurs
1888 while trying to change to the remote directory.
1890 FTP weird PASS reply. TclCurl couldn't parse the reply sent to the PASS request.
1892 FTP weird PASV reply, TclCurl couldn't parse the reply sent to the PASV or EPSV
1895 FTP weird 227 format. TclCurl couldn't parse the 227-line the server sent.
1897 FTP can't get host. Couldn't resolve the host IP we got in the 227-line.
1899 FTP couldn't set type. Couldn't change transfer method to either binary or
1902 Partial file. Only a part of the file was transfered, this happens when
1903 the server first reports an expected transfer size and then delivers data
1904 that doesn't match the given size.
1906 FTP couldn't RETR file, we either got a weird reply to a 'RETR' command or
1907 a zero byte transfer.
1909 Quote error. A custom 'QUOTE' returned error code 400 or higher (for FTP) or
1910 otherwise indicated unsuccessful completion of the command.
1912 HTTP returned error. This return code only appears if <B>-failonerror</B> is
1913 used and the HTTP server returns an error code that is 400 or higher.
1915 Write error. TclCurl couldn't write data to a local filesystem or an error
1916 was returned from a write callback.
1918 Failed upload failed. For FTP, the server typcially denied the STOR
1919 command. The error buffer usually contains the server's explanation to this.
1921 Read error. There was a problem reading from a local file or an error was returned
1922 from the read callback.
1924 Out of memory. A memory allocation request failed. This should never happen unless
1925 something weird is going on in your computer.
1927 Operation timeout. The specified time-out period was reached according to the
1930 The FTP PORT command failed, not all FTP servers support the PORT command,
1931 try doing a transfer using PASV instead!.
1933 FTP couldn't use REST. This command is used for resumed FTP transfers.
1935 Range error. The server doesn't support or accept range requests.
1937 HTTP post error. Internal post-request generation error.
1939 SSL connect error. The SSL handshaking failed, the error buffer may have
1940 a clue to the reason, could be certificates, passwords, ...
1942 FTP bad download resume. Couldn't continue an earlier aborted download, probably
1943 because you are trying to resume beyond the file size.
1945 A file given with FILE:// couldn't be read. Did you checked the permissions?
1947 LDAP cannot bind. LDAP bind operation failed.
1951 A required zlib function was not found.
1953 Aborted by callback. An application told TclCurl to abort the operation.
1955 Internal error. A function was called with a bad parameter.
1957 Interface error. A specified outgoing interface could not be used.
1959 Too many redirects. When following redirects, TclCurl hit the maximum amount, set
1960 your limit with --maxredirs
1962 Unknown TELNET option specified.
1964 A telnet option string was illegally formatted.
1966 The remote peer's SSL certificate or SSH md5 fingerprint wasn't ok
1968 The server didn't reply anything, which here is considered an error.
1970 The specified crypto engine wasn't found.
1972 Failed setting the selected SSL crypto engine as default!
1974 Failed sending network data.
1976 Failure with receiving network data.
1978 Problem with the local client certificate.
1980 Couldn't use specified SSL cipher.
1982 Peer certificate cannot be authenticated with known CA certificates.
1984 Unrecognized transfer encoding.
1988 Maximum file size exceeded.
1992 Sending the data requires a rewind that failed, since TclCurl should
1993 take care of it for you, it means you found a bug.
1995 Failed to initialise ssl engine.
1997 Failed to login, user password or similar was not accepted.
1999 File not found on TFTP server.
2001 There is a permission problem with the TFTP request.
2003 The remote server has run out of space.
2005 Illegal TFTP operation.
2007 Unknown transfer ID.
2009 TFTP file already exists and will not be overwritten.
2011 No such user in the TFTP server and good behaving TFTP server
2012 should never return this.
2014 Character conversion failed.
2016 Problem with reading the SSL CA cert (path? access rights?).
2018 Remote file not found
2020 Error from the SSH layer
2022 Failed to shut down the SSL connection
2024 Failed to load CRL file
2029 <A NAME="lbAU"> </A>
2030 <H2>curlHandle getinfo option</H2>
2032 Request internal information from the curl session with this procedure.
2033 This procedure is intended to get used *AFTER* a performed transfer,
2034 and can be relied upon only if the <B>perform</B> returns 0. Use
2035 this function AFTER a performed transfer if you want to get
2036 transfer-oriented data.
2038 The following information can be extracted:
2041 <DT><B>effectiveurl</B>
2044 Returns the last used effective URL.
2046 <DT><B>responsecode</B>
2049 Returns the last received HTTP or FTP code. This will be zero if no server
2050 response code has been received. Note that a proxy's CONNECT response should
2051 be read with <B>httpconnectcode</B> and not this.
2053 <DT><B>httpconnectcode</B>
2056 Returns the last received proxy response code to a CONNECT request.
2061 Returns the remote time of the retrieved document (in number of seconds
2062 since 1 jan 1970 in the GMT/UTC time zone). If you get -1,
2063 it can be because of many reasons (unknown, the server hides it or the
2064 server doesn't support the command that tells document time etc) and the time
2065 of the document is unknown.
2067 In order for this to work you have to set the <B>-filetime</B> option before
2070 <DT><B>namelookuptime</B>
2073 Returns the time, in seconds, it took from the start until the name resolving
2076 <DT><B>connecttime</B>
2079 Returns the time, in seconds, it took from the start until the connect to the
2080 remote host (or proxy) was completed.
2082 <DT><B>appconnecttime</B>
2085 Returns the time, in seconds, it took from the start until the SSL/SSH
2086 connect/handshake to the remote host was completed. This time is most often very
2087 near to the PRETRANSFER time, except for cases such as HTTP pippelining where the
2088 pretransfer time can be delayed due to waits in line for the pipeline and more.
2090 <DT><B>pretransfertime</B>
2093 Returns the time, in seconds, it took from the start until the file transfer
2094 is just about to begin. This includes all pre-transfer commands and
2095 negotiations that are specific to the particular protocol(s) involved.
2097 <DT><B>starttransfertime</B>
2100 Returns the time, in seconds, it took from the start until the first byte
2101 is just about to be transfered. This includes the <B>pretransfertime</B>,
2102 and also the time the server needs to calculate the result.
2104 <DT><B>totaltime</B>
2107 Returns the total transaction time, in seconds, for the previous transfer,
2108 including name resolving, TCP connect etc.
2110 <DT><B>redirecturl</B>
2113 Returns the URL a redirect would take you to if you enable <B>followlocation</B>.
2114 This can come very handy if you think using the built-in libcurl redirect logic
2115 isn't good enough for you but you would still prefer to avoid implementing all
2116 the magic of figuring out the new URL.
2118 <DT><B>redirecttime</B>
2121 Returns the total time, in seconds, it took for all redirection steps
2122 including name lookup, connect, pretransfer and transfer before
2123 the final transaction was started, it returns the complete execution
2124 time for multiple redirections, so it returns zero if no redirections
2127 <DT><B>redirectcount</B>
2130 Returns the total number of redirections that were actually followed.
2132 <DT><B>numconnects</B>
2135 Returns how many new connections TclCurl had to create to achieve the
2136 previous transfer (only the successful connects are counted). Combined
2137 with <B>redirectcount</B> you are able to know how many times TclCurl
2138 successfully reused existing connection(s) or not. See the Connection
2139 Options of <B>setopt</B> to see how TclCurl tries to make persistent
2140 connections to save time.
2142 <DT><B>primaryip</B>
2145 Returns the IP address of the most recent connection done with this handle.
2146 This string may be IPv6 if that's enabled.
2148 <DT><B>sizeupload</B>
2151 Returns the total amount of bytes that were uploaded.
2153 <DT><B>sizedownload</B>
2156 Returns the total amount of bytes that were downloaded. The amount is only
2157 for the latest transfer and will be reset again for each new transfer.
2159 <DT><B>speeddownload</B>
2162 Returns the average download speed, measured in bytes/second, for the complete download.
2164 <DT><B>speedupload</B>
2167 Returns the average upload speed, measured in bytes/second, for the complete upload.
2169 <DT><B>headersize</B>
2172 Returns the total size in bytes of all the headers received.
2174 <DT><B>requestsize</B>
2177 Returns the total size of the issued requests. This is so far only for HTTP
2178 requests. Note that this may be more than one request if followLocation is true.
2180 <DT><B>sslverifyresult</B>
2183 Returns the result of the certification verification that was requested
2184 (using the -sslverifypeer option to configure).
2186 <DT><B>sslengines</B>
2189 Returns a <B>list</B> of the OpenSSL crypto-engines supported. Note that engines are
2190 normally implemented in separate dynamic libraries. Hence not all the returned
2191 engines may be available at run-time.
2193 <DT><B>contentlengthdownload</B>
2196 Returns the content-length of the download. This is the value read from the
2197 <B>Content-Length:</B>
2201 <DT><B>contentlengthupload</B>
2204 Returns the specified size of the upload.
2206 <DT><B>contenttype</B>
2209 Returns the content-type of the downloaded object. This is the value
2210 read from the Content-Type: field. If you get an empty string, it means
2211 the server didn't send a valid Content-Type header or that the protocol
2212 used doesn't support this.
2214 <DT><B>httpauthavail</B>
2217 Returns a list with the authentication method(s) available.
2219 <DT><B>proxyauthavail</B>
2222 Returns a list with the authentication method(s) available for your
2223 proxy athentication.
2228 Returns the errno value from a connect failure.
2230 <DT><B>cookielist</B>
2233 Returns a list of all cookies TclCurl knows (expired ones, too). If there
2234 are no cookies (cookies for the handle have not been enabled or simply
2235 none have been received) the list will be empty.
2237 <DT><B>ftpentrypath </B>
2240 Returns a string holding the path of the entry path. That is the initial path
2241 TclCurl ended up in when logging on to the remote FTP server. Returns an empty
2242 string if something is wrong.
2245 <A NAME="lbAV"> </A>
2246 <H2>curlHandle cleanup</H2>
2248 This procedure must be the last one to call for a curl session. It is the
2252 procedure and must be called with the same
2255 as input as the curl::init call returned.
2256 This will effectively close all connections TclCurl has used and possibly
2257 has kept open until now. Don't call this procedure if you intend to transfer
2260 <A NAME="lbAW"> </A>
2261 <H2>curlHandle reset</H2>
2264 Re-initializes all options previously set on a specified handle to the
2267 This puts back the handle to the same state as it was in when it was just
2268 created with curl::init.
2270 It does not change the following information kept in the handle: live
2271 connections, the Session ID cache, the DNS cache, the cookies and shares.
2273 <A NAME="lbAX"> </A>
2274 <H2>curlHandle duphandle</H2>
2276 This procedure will return a new curl handle, a duplicate,
2277 using all the options previously set in the input curl handle.
2278 Both handles can subsequently be used independently and
2279 they must both be freed with
2282 The new handle will not inherit any state information,
2283 connections, SSL sessions or cookies.
2285 <DT><B>RETURN VALUE</B>
2288 A new curl handle or an error message if the copy fails.
2291 <A NAME="lbAY"> </A>
2292 <H2>curlHandle pause</H2>
2294 You can use this command from within a progress callback procedure
2295 to pause the transfer.
2297 <A NAME="lbAZ"> </A>
2298 <H2>curlHandle resume</H2>
2300 Resumes a transfer paused with <B>curlhandle pause</B>
2302 <A NAME="lbBA"> </A>
2303 <H2>curl::transfer</H2>
2305 In case you do not want to use persistant connections you can use this
2306 command, it takes the same arguments as the <I>curlHandle</I> <B>configure</B>
2307 and will init, configure, perform and cleanup a connection for you.
2309 You can also get the <I>getinfo</I> information by using <I>-infooption variable</I>
2310 pairs, after the transfer <I>variable</I> will contain the value that would have
2311 been returned by <I>$curlHandle getinfo option</I>.
2313 <DT><B>RETURN VALUE</B>
2316 The same error code <B>perform</B> would return.
2319 <A NAME="lbBB"> </A>
2320 <H2>curl::version</H2>
2322 Returns a string with the version number of tclcurl, libcurl and some of
2323 its important components (like OpenSSL version).
2325 <DT><B>RETURN VALUE</B>
2328 The string with the version info.
2331 <A NAME="lbBC"> </A>
2332 <H2>curl::escape url</H2>
2334 This procedure will convert the given input string to an URL encoded string and
2335 return that. All input characters that are not a-z,
2336 A-Z or 0-9 will be converted to their "URL escaped" version (%NN where NN is a
2337 two-digit hexadecimal number)
2339 <DT><B>RETURN VALUE</B>
2342 The converted string.
2344 <A NAME="lbBD"> </A>
2345 <H2>curl::unescape url</H2>
2347 This procedure will convert the given URL encoded input string to a "plain
2348 string" and return that. All input characters that
2349 are URL encoded (%XX where XX is a two-digit hexadecimal number) will be
2350 converted to their plain text versions.
2352 <DT><B>RETURN VALUE</B>
2355 The string unencoded.
2358 <A NAME="lbBE"> </A>
2359 <H2>curl::curlConfig option</H2>
2361 Returns some information about how you have
2370 Returns the directory root where you installed
2376 Returns a list containing particular main features the installed
2379 was built with. The list may include SSL, KRB4 or IPv6, do not
2380 assume any particular order.
2384 Outputs version information about the installed libcurl, in
2385 numerical mode. This outputs the version number, in hexadecimal,
2386 with 8 bits for each part; major, minor, patch. So that libcurl
2387 7.7.4 would appear as 070704 and libcurl 12.13.14 would appear as
2391 <A NAME="lbBF"> </A>
2392 <H2>curl::versioninfo option</H2>
2394 Returns information about various run-time features in TclCurl.
2396 Applications should use this information to judge if things are possible to do
2397 or not, instead of using compile-time checks, as dynamic/DLL libraries can be
2398 changed independent of applications.
2404 Returns the version of libcurl we are using.
2406 <DT><B>-versionnum</B>
2409 Retuns the version of libcurl we are using in hexadecimal with 8 bits for each
2410 part; major, minor, patch. So that libcurl 7.7.4 would appear as 070704 and
2411 libcurl 12.13.14 would appear as 0c0d0e... Note that the initial zero might be
2417 Returns a string with the host information as discovered by a configure
2418 script or set by the build environment.
2420 <DT><B>-features</B>
2423 Returns a list with the features compiled into libcurl, the possible elements are:
2424 <DL COMPACT><DT><DD>
2426 <DT><B>ASYNCHDNS</B>
2429 Libcurl was built with support for asynchronous name lookups, which allows
2430 more exact timeouts (even on Windows) and less blocking when using the multi
2435 Libcurl was built with support for character conversions.
2439 Libcurl was built with extra debug capabilities built-in. This is mainly of
2440 interest for libcurl hackers.
2441 <DT><B>GSSNEGOTIATE</B>
2444 Supports HTTP GSS-Negotiate.
2448 Supports IDNA, domain names with international letters.
2453 <DT><B>KERBEROS4</B>
2456 Supports kerberos4 (when using FTP).
2457 <DT><B>LARGEFILE</B>
2460 Libcurl was built with support for large files.
2464 Supports HTTP deflate using libz.
2472 Libcurl was built with support for SPNEGO authentication (Simple and Protected
2473 GSS-API Negotiation Mechanism, defined in RFC 2478)
2477 Supports SSL (HTTPS/FTPS)
2481 Libcurl was built with support for SSPI. This is only available on Windows and
2482 makes libcurl use Windows-provided functions for NTLM authentication. It also
2483 allows libcurl to use the current user and the current user's password without
2484 the app having to pass them on.
2488 Do not assume any particular order.
2490 <DT><B>-sslversion</B>
2493 Returns a string with the OpenSSL version used, like OpenSSL/0.9.6b.
2495 <DT><B>-sslversionnum</B>
2498 Returns the numerical OpenSSL version value as defined by the OpenSSL project.
2499 If libcurl has no SSL support, this is 0.
2501 <DT><B>-libzversion</B>
2504 Returns a string, there is no numerical version, for example: 1.1.3.
2506 <DT><B>-protocols</B>
2509 Lists what particular protocols the installed TclCurl was built to support.
2510 At the time of writing, this list may include HTTP, HTTPS, FTP, FTPS,
2511 FILE, TELNET, LDAP, DICT. Do not assume any particular order. The protocols
2512 will be listed using uppercase. There may be none, one or several protocols
2516 <A NAME="lbBG"> </A>
2517 <H2>curl::easystrerror errorCode</H2>
2519 This procedure returns a string describing the error code passed in the argument.
2521 <A NAME="lbBH"> </A>
2524 <I>curl, <A HREF="http://curl.haxx.se/docs/httpscripting.html">The art of HTTP scripting</A> RFC 2396,</I>
2529 <A NAME="index"> </A><H2>Index</H2>
2531 <DT><A HREF="#lbAB">NAME</A><DD>
2532 <DT><A HREF="#lbAC">SYNOPSIS</A><DD>
2533 <DT><A HREF="#lbAD">DESCRIPTION</A><DD>
2534 <DT><A HREF="#lbAE">curl::init</A><DD>
2535 <DT><A HREF="#lbAF">curlHandle configure ?options?</A><DD>
2536 <DT><A HREF="#lbAG">Behaviour options</A><DD>
2537 <DT><A HREF="#lbAH">Callback options</A><DD>
2538 <DT><A HREF="#lbAI">Error Options</A><DD>
2539 <DT><A HREF="#lbAJ">Network options</A><DD>
2540 <DT><A HREF="#lbAK">Names and Passwords options</A><DD>
2541 <DT><A HREF="#lbAL">HTTP options</A><DD>
2542 <DT><A HREF="#lbAM">FTP options</A><DD>
2543 <DT><A HREF="#lbAN">Protocol options</A><DD>
2544 <DT><A HREF="#lbAO">Connection options</A><DD>
2545 <DT><A HREF="#lbAP">SSL and security options</A><DD>
2546 <DT><A HREF="#lbAQ">SSH options</A><DD>
2547 <DT><A HREF="#lbAR">Other options</A><DD>
2548 <DT><A HREF="#lbAS">NOT SUPPORTED</A><DD>
2549 <DT><A HREF="#lbAT">curlHandle perform</A><DD>
2550 <DT><A HREF="#lbAU">curlHandle getinfo option</A><DD>
2551 <DT><A HREF="#lbAV">curlHandle cleanup</A><DD>
2552 <DT><A HREF="#lbAW">curlHandle reset</A><DD>
2553 <DT><A HREF="#lbAX">curlHandle duphandle</A><DD>
2554 <DT><A HREF="#lbAY">curlHandle pause</A><DD>
2555 <DT><A HREF="#lbAZ">curlHandle resume</A><DD>
2556 <DT><A HREF="#lbBA">curl::transfer</A><DD>
2557 <DT><A HREF="#lbBB">curl::version</A><DD>
2558 <DT><A HREF="#lbBC">curl::escape url</A><DD>
2559 <DT><A HREF="#lbBD">curl::unescape url</A><DD>
2560 <DT><A HREF="#lbBE">curl::curlConfig option</A><DD>
2561 <DT><A HREF="#lbBF">curl::versioninfo option</A><DD>
2562 <DT><A HREF="#lbBG">curl::easystrerror errorCode</A><DD>
2563 <DT><A HREF="#lbBH">SEE ALSO</A><DD>
2566 This document was created by man2html,
2567 using the manual pages.<BR>
projects / sven / tclcurl.git / blob