X-Git-Url: http://git.sven.stormbind.net/?a=blobdiff_plain;f=doc%2Ftclcurl.n;fp=doc%2Ftclcurl.n;h=cb51d822f2cc2a79b768e11196e60b9aa74ea4fb;hb=b0e6fb6e4379fb87fa2854b84a56c5ad49c644da;hp=0000000000000000000000000000000000000000;hpb=c9a5bcd9d76f699909b24e71a2a216d36062ab0b;p=sven%2Ftclcurl.git diff --git a/doc/tclcurl.n b/doc/tclcurl.n new file mode 100644 index 0000000..cb51d82 --- /dev/null +++ b/doc/tclcurl.n @@ -0,0 +1,2078 @@ +.\" You can view this file with: +.\" nroff -man [file] +.\" Adapted from libcurl docs by fandom@telefonica.net +.TH TclCurl n "8 September 2008" "TclCurl 7.19.0 "TclCurl Easy Interface" +.SH NAME +TclCurl: - get a URL with FTP, FTPS, HTTP, HTTPS, SCP, SFTP, TFTP, TELNET, DICT, FILE or LDAP syntax. +.SH SYNOPSIS +.BI "curl::init" +.sp +.IB curlHandle " configure " "?options?" +.sp +.IB curlHandle " perform" +.sp +.IB curlHandle " getinfo " curlinfo_option +.sp +.IB curlhandle " cleanup" +.sp +.IB curlhandle " reset" +.sp +.IB curlHandle " duhandle" +.sp +.IB curlHandle " pause" +.sp +.IB curlHandle " resume" +.sp +.BI curl::transfer " ?options?" +.sp +.BI curl::version +.sp +.BI "curl::escape " url +.sp +.BI "curl::unescape " url +.sp +.BI "curl::curlConfig " option +.sp +.BI "curl::versioninfo " option +.sp +.BI "curl::easystrerror " errorCode + +.SH DESCRIPTION +The TclCurl extension gives Tcl programmers access to the libcurl +library written by \fBDaniel Stenberg\fP, with it you can download urls, +upload them and many other neat tricks, for more information check +.I http://curl.haxx.se +.SH curl::init +This procedure must be the first one to call, it returns a +.I curlHandle +that you need to use to invoke TclCurl procedures. The init calls intializes +curl and this call MUST have a corresponding call to +.I cleanup +when the operation is completed. +You should perform all your sequential file transfers using the same +curlHandle. This enables TclCurl to use persistant connections when +possible. +.sp +.B RETURN VALUE +.sp +.I curlHandle +to use. +.SH curlHandle configure ?options? +.sp +.B configure +is called to set the options for the transfer. Most operations in TclCurl +have default actions, and by using the appropriate options you can +make them behave differently (as documented). All options are set with +the \fIoption\fP followed by a parameter. +.sp +.B Notes: +the options set with this procedure are valid for the +forthcoming data transfers that are performed when you invoke +.I perform +.sp +The options are not reset between transfers (except where noted), so if +you want subsequent transfers with different options, you must change them +between the transfers. You can optionally reset all options back to the internal +default with \fBcurlHandle reset\fP. +.sp +.I "curlHandle" +is the return code from the +.I "curl::init" +call. +.sp + +.B OPTIONS +.sp +.SH Behaviour options + +.TP +.B -verbose +Set the parameter to 1 to get the library to display a lot of verbose +information about its operations. Very useful for libcurl and/or protocol +debugging and understanding. + +You hardly ever want this set in production use, you will almost always want +this when you debug/report problems. Another neat option for debugging is +.B -debugproc + +.TP +.B -header +A 1 tells the extension to include the headers in the body output. This is +only relevant for protocols that actually have headers preceding the data (like HTTP). + +.TP +.B -noprogress +A 1 tells the extension to turn on the built-in progress meter. +Nowadays it is turn off by default. + +.TP +.B -nosignal +A 1 tells TclCurl not use any functions that install signal +handlers or any functions that cause signals to be sent to the process. This +option is mainly here to allow multi-threaded unix applications to still +set/use all timeout options etc, without risking getting signals. + + +.SH Callback options + +.TP +.B -writeproc +Use it to set a Tcl procedure that will be invoked by TclCurl as soon as +there is received data that needs to be saved. The procedure will receive +a single parameter with the data to be saved. + +NOTE: you will be passed as much data as possible in all invokes, but you +cannot possibly make any assumptions. It may be nothing if the file is +empty or it may be thousands of bytes. + +.TP +.B -file +File in which the transfered data will be saved. + +.TP +.B -readproc +Sets a Tcl procedure to be called by TclCurl as soon as it needs to read +data in order to send it to the peer. The procedure has to take one +parameter, which will contain the maximun numbers of bytes to read. It +should return the actual number of bytes read, or '0' if you want to +stop the transfer. + +.TP +.B -infile +File from which the data will be transfered. + +.TP +.B -progressproc +Name of the Tcl procedure that will invoked by TclCurl with a frequent +interval during operation (roughly once per second), no matter if data +is being transfered or not. Unknown/unused +argument values passed to the callback will be set to zero (like if you +only download data, the upload size will remain 0), the prototype of the +procedure must be: +.sp +.B proc ProgressCallback {dltotal dlnow ultotal ulnow} +.sp +In order to this option to work you have to set the \fBnoprogress\fP +option to '0'. Setting this option to the empty string will restore the +original progress function. + +If you transfer data with the multi interface, this procedure will not be +called during periods of idleness unless you call the appropriate procedure +that performs transfers. + +You can pause and resume a transfer from within this procedure using the +\fBpause\fP and \fBresume\fP commands. + +.TP +.B -writeheader +Pass a the file name to be used to write the header part of the received data to. +The headers are guaranteed to be written one-by-one to this file and +only complete lines are written. Parsing headers should be easy enough using +this. + +.TP +.B -debugproc +Name of the procedure that will receive the debug data produced by the +.B -verbose +option, it should match the following prototype: +.sp +.B debugProc {infoType data} +.sp +where \fBinfoType\fP specifies what kind of information it is (0 text, +1 incoming header, 2 outgoing header, 3 incoming data, 4 outgoing data, +5 incoming SSL data, 6 outgoing SSL data). + +.SH Error Options + +.TP +.B -errorbuffer +Pass a variable name where TclCurl may store human readable error +messages in. This may be more helpful than just the return code from the +command. + +.TP +.B -stderr +Pass a file name as parameter. This is the stream to use internally instead +of stderr when reporting errors. +.TP +.B -failonerror +A 1 parameter tells the extension to fail silently if the HTTP code +returned is equal or larger than 400. The default action would be to return +the page normally, ignoring that code. + +This method is not fail-safe and there are occasions where non-successful response +codes will slip through, especially when authentication is involved +(response codes 401 and 407). + +You might get some amounts of headers transferred before this situation is detected, +like for when a "100-continue" is received as a response to a POST/PUT and a 401 +or 407 is received immediately afterwards. + +.SH Network options + +.TP +.B -url +The actual URL to deal with. + +If the given URL lacks the protocol part ("http://" or "ftp://" etc), it will +attempt to guess which protocol to use based on the given host name. If the +given protocol of the set URL is not supported, TclCurl will return the +\fBunsupported protocol\fP error when you call \fBperform\fP. Use +\fBcurl::versioninfo\fP for detailed info on which protocols that are supported. + +\fBNOTE\fP: this the one option required to be set +before +.B perform +is called. + +.TP +.B -proxy +If you need to use a http proxy to access the outside world, set the +proxy string with this option. To specify port number in this string, +append :[port] to the end of the host name. The proxy string may be +prefixed with [protocol]:// since any such prefix will be ignored. + +When you tell the extension to use a HTTP proxy, TclCurl will +transparently convert operations to HTTP even if you specify a FTP +URL etc. This may have an impact on what other features of the library +you can use, such as +.B quote +and similar FTP specifics that will not work unless you tunnel through +the HTTP proxy. Such tunneling is activated with +.B proxytunnel + +TclCurl respects the environment variables http_proxy, ftp_proxy, +all_proxy etc, if any of those are set. The use of this option does +however override any possibly set environment variables. + +Setting the proxy string to "" (an empty string) will explicitly disable +the use of a proxy, even if there is an environment variable set for it. + +The proxy host string can be specified the exact same way as the proxy +environment variables, include protocol prefix (http://) and embedded +user + password. + +.TP +.B -proxyport +Use this option to set the proxy port to use unless it is specified in +the proxy string by \fB-proxy\fP. + +.TP +.B -proxytype +Pass the type of the proxy. Available options are 'http', 'socks4', 'socks4a' +and 'socks5', with the HTTP one being default. + +.TP +.B -httpproxytunnel +Set the parameter to 1 to get the extension to tunnel all non-HTTP +operations through the given HTTP proxy. Do note that there is a big +difference between using a proxy and tunneling through it. If you don't know what +this means, you probably don't want this tunnel option. + +.TP +.B -interface +Pass the interface name to use as outgoing +network interface. The name can be an interface name, an IP address or a host +name. + +.TP +.B -localport +This sets the local port number of the socket used for connection. This can +be used in combination with \fB-interface\fP and you are recommended to use +\fBlocalportrange\fP as well when this is set. Note the only valid port numbers +are 1 - 65535. + +.TP +.B -localportrange +This is the number of attempts TclCurl should do to find a working local port +number. It starts with the given \fB-localport\fP and adds +one to the number for each retry. Setting this value to 1 or below will make +TclCurl do only one try for exact port number. Note that port numbers by nature +are a scarce resource that will be busy at times so setting this value to something +too low might cause unnecessary connection setup failures. + +.TP +.B -dnscachetimeout +Pass the timeout in seconds. Name resolves will be kept in memory for this number +of seconds. Set to '0' to completely disable caching, or '-1' to make the +cached entries remain forever. By default, TclCurl caches this info for 60 seconds. + +.TP +.B -dnsuseglobalcache +If the value passed is 1, it tells TclCurl to use a global DNS cache that +will survive between curl handles creations and deletions. This is not thread-safe +as it uses a global varible. + +\fBWARNING:\fP this option is considered obsolete. Stop using it. Switch over +to using the share interface instead! See \fItclcurl_share\fP. + +.TP +.B -buffersize +Pass your prefered size for the receive buffer in TclCurl. The main point of this +would be that the write callback gets called more often and with smaller chunks. +This is just treated as a request, not an order. You cannot be guaranteed to +actually get the given size. + +.TP +.B -port + +Pass the number specifying what remote port to connect to, instead of the one specified +in the URL or the default port for the used protocol. + +.TP +.B -tcpnodelay + +Pass a number to specify whether the TCP_NODELAY option should be set or cleared (1 = set, 0 = clear). +The option is cleared by default. This will have no effect after the connection has been established. + +Setting this option will disable TCP's Nagle algorithm. The purpose of this algorithm is to try to +minimize the number of small packets on the network (where "small packets" means TCP segments less +than the Maximum Segment Size (MSS) for the network). + +Maximizing the amount of data sent per TCP segment is good because it amortizes the overhead of the +send. However, in some cases (most notably telnet or rlogin) small segments may need to be sent without +delay. This is less efficient than sending larger amounts of data at a time, and can contribute to +congestion on the network if overdone. + +.TP +.B -addressscope +Pass a number specifying the scope_id value to use when connecting to IPv6 link-local or site-local +addresses. + +.SH Names and Passwords options + +.TP +.B -netrc +A 1 parameter tells the extension to scan your +.B ~/.netrc +file to find user name and password for the remote site you are about to +access. Do note that TclCurl does not verify that the file has the correct +properties set (as the standard unix ftp client does), and that only machine +name, user name and password is taken into account (init macros and similar +things are not supported). + +You can set it to the following values: +.RS +.TP 5 +.B optional +The use of your ~/.netrc file is optional, and information in the URL is to +be preferred. The file will be scanned with the host and user name (to find +the password only) or with the host only, to find the first user name and +password after that machine, which ever information is not specified in +the URL. + +Undefined values of the option will have this effect. +.TP +.B ignored +The extension will ignore the file and use only the information in the URL. +This is the default. +.TP +.B required +This value tells the library that use of the file is required, to ignore +the information in the URL, and to search the file with the host only. +.RE + +.TP +.B -netrcfile +Pass a string containing the full path name to the file you want to use as .netrc +file. For the option to work, you have to set the \fBnetrc\fP option to +\fBrequired\fP. If this option is omitted, and \fBnetrc\fP is set, TclCurl +will attempt to find the a .netrc file in the current user's home directory. + +.TP +.B -userpwd +Pass a string as parameter, which should be [username]:[password] to use for +the connection. Use \fBhttpauth\fP to decide authentication method. + +When using NTLM, you can set domain by prepending it to the user name and +separating the domain and name with a forward (/) or backward slash (\\). Like +this: "domain/user:password" or "domain\\user:password". Some HTTP servers (on +Windows) support this style even for Basic authentication. + +When using HTTP and \fB-followlocation\fP, TclCurl might perform several +requests to possibly different hosts. TclCurl will only send this user and +password information to hosts using the initial host name (unless +\fB-unrestrictedauth\fP is set), so if TclCurl follows locations to other +hosts it will not send the user and password to those. This is enforced to +prevent accidental information leakage. + +.TP +.B -proxyuserpwd +Pass a string as parameter, which should be [username]:[password] to use for +the connection to the HTTP proxy. + +.TP +.B -httpauth +Set to the authentication method you want, the available ones are: +.RS +.TP 5 +.B basic +HTTP Basic authentication. This is the default choice, and the only +method that is in widespread use and supported virtually everywhere. +It sends the user name and password over the network in plain text, +easily captured by others. + +.TP +.B digest +HTTP Digest authentication. Digest authentication is a more secure +way to do authentication over public networks than the regular +old-fashioned Basic method. + +.TP +.B gssnegotiate +HTTP GSS-Negotiate authentication. The GSS-Negotiate method, also known as +plain "Negotiate",was designed by Microsoft and is used in their web +applications. It is primarily meant as a support for Kerberos5 authentication +but may be also used along with another authentication methods. + +.TP +.B ntlm +HTTP NTLM authentication. A proprietary protocol invented and used by Microsoft. +It uses a challenge-response and hash concept similar to Digest, to prevent the +password from being eavesdropped. + +.TP +.B any +TclCurl will automatically select the one it finds most secure. + +.TP +.B anysafe +It may use anything but basic, TclCurl will automaticly select the +one it finds most secure. +.RE + +.TP +.B -proxyauth +Use it to tell TclCurl which authentication method(s) you want it to use for +your proxy authentication. Note that for some methods, this will induce an +extra network round-trip. Set the actual name and password with the +\fBproxyuserpwd\fP option. + +The methods are those listed above for the \fBhttpauth\fP option. As of this +writing, only Basic and NTLM work. + +.SH HTTP options + +.TP +.B -autoreferer +Pass an 1 parameter to enable this. When enabled, TclCurl will +automatically set the Referer: field in requests where it follows a Location: +redirect. + +.TP +.B -encoding +Sets the contents of the Accept-Encoding: header sent in an HTTP +request, and enables decoding of a response when a Content-Encoding: +header is received. Three encodings are supported: \fIidentity\fP, +which does nothing, \fIdeflate\fP which requests the server to +compress its response using the zlib algorithm, and \fIgzip\fP which +requests the gzip algorithm. Use \fIall\fP to send an +Accept-Encoding: header containing all supported encodings. + +This is a request, not an order; the server may or may not do it. This +option must be set or else any unsolicited +encoding done by the server is ignored. See the special file +lib/README.encoding in libcurl docs for details. + +.TP +.B -followlocation +An 1 tells the library to follow any +.B Location: header +that the server sends as part of a HTTP header. + +\fBNOTE\fP: this means that the extension will re-send the same +request on the new location and follow new \fBLocation: headers\fP +all the way until no more such headers are returned. +\fB-maxredirs\fP can be used to limit the number of redirects +TclCurl will follow. + +.TP +.B -unrestrictedauth +An 1 parameter tells the extension it can continue +to send authentication (user+password) when following +locations, even when hostname changed. Note that this +is meaningful only when setting \fB-followlocation\fP. + +.TP +.B -maxredirs +Sets the redirection limit. If that many redirections have been followed, +the next redirect will cause an error. This option only makes sense if the +\fB-followlocation\fP option is used at the same time. Setting the limit +to 0 will make libcurl refuse any redirect. Set it to -1 for an infinite +number of redirects (which is the default) + +.TP +.B -post301 +An 1 tells TclCurl to respect RFC 2616/10.3.2 and not +convert POST requests into GET requests when following a 301 redirection. The +non-RFC behaviour is ubiquitous in web browsers, so the conversion is done +by default to maintain consistency. However, a server may require +a POST to remain a POST after such a redirection. This option is meaningful +only when setting \fB-followlocation\fP. + +.TP +.B -put +An 1 parameter tells the extension to use HTTP PUT a file. The file to put +must be set with \fB-infile\fP and \fB-infilesize\fP. + +This option is deprecated starting with version 0.12.1, you should use \fB-upload\fP. + +.TP +.B -post +An 1 parameter tells the library to do a regular HTTP post. This is a +normal application/x-www-form-urlencoded kind, which is the most commonly used +one by HTML forms. See the \fB-postfields\fP option for how to specify the +data to post and \fB-postfieldsize\fP about how to set the data size. + +Use the \fB-postfields\fP option to specify what data to post and \fB-postfieldsize\fP +to set the data size. Optionally, you can provide data to POST using the \fB-readproc\fP +options. + +You can override the default POST Content-Type: header by setting your own with +\fB-httpheader\fP. + +Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header. +You can disable this header with \fB-httpheader\fP as usual. + +If you use POST to a HTTP 1.1 server, you can send data without knowing the +size before starting the POST if you use chunked encoding. You enable this +by adding a header like "Transfer-Encoding: chunked" with \fB-httpheader\fP. +With HTTP 1.0 or without chunked transfer, you must specify the size in the +request. + +When setting \fBpost\fP to an 1 value, it will automatically set +\fBnobody\fP to 0. + +NOTE: if you have issued a POST request and want to make a HEAD or GET instead, you must +explicitly pick the new request type using \fB-nobody\fP or \fB-httpget\fP or similar. + +.TP +.B -postfields +Pass a string as parameter, which should be the full data to post in a HTTP +POST operation. You must make sure that the data is formatted the way you +want the server to receive it. TclCurl will not convert or encode it for you. +Most web servers will assume this data to be url-encoded. + +This is a normal application/x-www-form-urlencoded kind, +which is the most commonly used one by HTML forms. + +If you want to do a zero-byte POST, you need to set +\fB-postfieldsize\fP explicitly to zero, as simply setting +\fB-postfields\fP to NULL or "" just effectively disables the sending +of the specified string. TclCurl will instead assume that the POST +data will be send using the read callback! + +Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header. +You can disable this header with \fB-httpheader\fP as usual. + +\fBNote\fP: to make multipart/formdata posts (aka rfc1867-posts), check out +\fB-httppost\fP option. + +.TP +.B -postfieldsize +If you want to post data to the server without letting TclCurl do a strlen() +to measure the data size, this option must be used. Also, when this option is +used, you can post fully binary data which otherwise is likely to fail. If +this size is set to zero, the library will use strlen() to get the data +size. + +.TP +.B -httppost +Tells TclCurl you want a multipart/formdata HTTP POST to be made and you +instruct what data to pass on to the server through a +.B Tcl list. + +\fBThis is the only case where the data is reset after a transfer.\fP + +First, there are some basics you need to understand about multipart/formdata +posts. Each part consists of at least a \fBNAME\fP and a \fBCONTENTS\fP part. If the part +is made for file upload, there are also a stored \fBCONTENT-TYPE\fP and a +\fBFILENAME\fP. Below, we'll discuss on what options you use to set these +properties in the parts you want to add to your post. + +The list must contain a \fB'name'\fP tag with the name of the section followed +by a string with the name, there are three tags to indicate the value of +the section: \fB'value'\fP followed by a string with the data to post, \fB'file'\fP +followed by the name of the file to post and \fB'contenttype'\fP with the +type of the data (text/plain, image/jpg, ...), you can also indicate a \fIfalse\fP +file name with \fB'filename'\fP, this is useful in case the server checks if the given +file name is valid, for example, by testing if it starts with 'c:\\' as any real file +name does or if you want to include the full path of the file to post. You can also post +the content of a variable as if it were a file with the options \fB'bufferName'\fP and +\fB'buffer'\fP or use \fB'filecontent'\fP followed by a file name to read that file and +use the contents as data. + +Should you need to specify extra headers for the form POST section, use +\fB'contentheader\fP' followed by a list with the headers to post. + +Please see 'httpPost.tcl' and 'httpBufferPost.tcl' for examples. + +If TclCurl can't set the data to post an error will be returned: +.RS +.TP 5 +.B 1 +If the memory allocation fails. +.TP +.B 2 +If one option is given twice for one form. +.TP +.B 3 +If an empty string was given. +.TP +.B 4 +If an unknown option was used. +.TP +.B 5 +If the some form info is not complete (or error) +.TP +.B 6 +If an illegal option is used in an array. +.TP +.B 7 +TclCurl has no http support. +.RE + +.TP +.B -referer +Pass a string as parameter. It will be used to set the +.B referer +header in the http request sent to the remote server. This can be used to +fool servers or scripts. You can also set any custom header with +.B -httpheader. + +.TP +.B -useragent +Pass a string as parameter. It will be used to set the +.B user-agent: +header in the http request sent to the remote server. This can be used to fool +servers or scripts. You can also set any custom header with +.B -httpheader. + +.TP +.B -httpheader +Pass a +.B list +with the HTTP headers to pass to the server in your request. +If you add a header that is otherwise generated +and used by TclCurl internally, your added one will be used instead. If you +add a header with no contents as in 'Accept:', the internally used header will +just get disabled. Thus, using this option you can add new headers, replace +and remove internal headers. + +The headers included in the linked list must not be CRLF-terminated, because +TclCurl adds CRLF after each header item. Failure to comply with this will +result in strange bugs because the server will most likely ignore part of the +headers you specified. + +The first line in a request (containing the method, usually a GET or POST) is +not a header and cannot be replaced using this option. Only the lines +following the request-line are headers. Adding this method line in this list +of headers will only cause your request to send an invalid header. + +\fBNOTE\fP:The most commonly replaced headers have "shortcuts" in the options: +.B cookie, useragent, +and +.B referer. + +.TP +.B -http200aliases +Pass a list of aliases to be treated as valid HTTP 200 responses. Some servers +respond with a custom header response line. For example, IceCast servers respond +with "ICY 200 OK". By including this string in your list of aliases, the +response will be treated as a valid HTTP header line such as "HTTP/1.0 200 OK". + +\fBNOTE\fP:The alias itself is not parsed for any version strings. Before version +7.16.3, TclCurl used the value set by option \fBhttpversion\fP, but starting with +7.16.3 the protocol is assumed to match HTTP 1.0 when an alias matched. + +.TP +.B -cookie +Pass a string as parameter. It will be used to +set a cookie in the http request. The format of the string should be +'[NAME]=[CONTENTS];'. Where NAME is the cookie name and CONTENTS is +what the cookie should contain. + +If you need to set mulitple cookies, you need to set them all using +a single option and thus you need to concatenate them all in one single string. +Set multiple cookies in one string like this: "name1=content1; name2=content2;" +etc. + +Note that this option sets the cookie header explictly in the outgoing request(s). +If multiple requests are done due to authentication, followed redirections or similar, +they will all get this cookie passed on. + +Using this option multiple times will only make the latest string override +the previous ones. + +.TP +.B -cookiefile +Pass a string as parameter. It should contain the name of your file holding +cookie data. The cookie data may be in netscape cookie data format or just +regular HTTP-style headers dumped to a file. + +Given an empty or non-existing file, this option will enable cookies for this +curl handle, making it understand and parse received cookies and then use +matching cookies in future requests. + +If you use this option multiple times, you add more files to read. + +.TP +.B -cookiejar +Pass a file name in which TclCurl will dump all internally known cookies +when +.B curlHandle cleanup +is called. If no cookies are known, no file will be created. +Specify "-" to have the cookies written to stdout. + +Using this option also enables cookies for this session, so if you, for +example, follow a location it will make matching cookies get sent accordingly. + +TclCurl will not and cannot report an error for this. Using '\fBverbose\fP' +will get a warning to display, but that is the only visible feedback you get +about this possibly lethal situation. + +.TP +.B -cookiesession +Pass an 1 to mark this as a new cookie "session". It will +force TclCurl to ignore all cookies it is about to load that are "session +cookies" from the previous session. By default, TclCurl always stores and +loads all cookies, independent of whether they are session cookies are not. +Session cookies are cookies without expiry date and they are meant to be +alive and existing for this "session" only. + +.TP +.B -cookielist +Pass a string with a cookie. The cookie can be either in Netscape / Mozilla +format or just regular HTTP-style header (Set-Cookie: ...) format. If the +cookie engine was not enabled it will be enabled. Passing a +magic string "ALL" will erase all known cookies while "FLUSH" will write +all cookies known by TclCurl to the file specified by \fB-cookiejar\fP. + +.TP +.B -httpget +If set to 1 forces the HTTP request to get back to GET, usable if +POST, PUT or a custom request have been used previously with the +same handle. + +When setting \fBhttpget\fP to 1, \fBnobody\fP will automatically be set to 0. + +.TP +.B -httpversion +Set to one of the values decribed below, they force TclCurl to use the +specific http versions. It should only be used if you really MUST do +that because of a silly remote server. +.RS +.TP 5 +.B none +We do not care about what version the library uses. TclCurl will use whatever +it thinks fit. +.TP +.B 1.0 +Enforce HTTP 1.0 requests. +.TP +.B 1.1 +Enforce HTTP 1.1 requests. +.RE + +.TP +.B -ignorecontentlength +Ignore the Content-Length header. This is useful for Apache 1.x (and similar +servers) which will report incorrect content length for files over 2 +gigabytes. If this option is used, TclCurl will not be able to accurately +report progress, and will simply stop the download when the server ends the +connection. + +.TP +.B -httpcontentdecoding +Set to zero to disable content decoding. If set to 1 it is enabled. Note however +that TclCurl has no default content decoding but requires you to use \fBencoding\fP for that. + +.TP +.B -httptransferencoding +Set to zero to disable transfer decoding, if set to 1 it is enabled (default). TclCurl does +chunked transfer decoding by default unless this option is set to zero. + +.SH FTP options + +.TP +.B -ftpport +Pass a string as parameter. It will be used to +get the IP address to use for the ftp PORT instruction. The PORT instruction +tells the remote server to connect to our specified IP address. The string may +be a plain IP address, a host name, a network interface name (under unix) or +just a '-' to let the library use your systems default IP address. Default FTP +operations are passive, and thus will not use PORT. + +.TP +.B -quote +Pass a \fBlist\fP list with the FTP or SFTP commands to pass to the server prior to your +ftp request. This will be done before any other FTP commands are issued (even +before the CWD command).If you do not want to transfer any files, set +\fBnobody\fP to '1' and \fBheader\fP to '0'. + +Keep in mind the commands to send must be 'raw' ftp commands, for example, to +create a directory you need to send \fBmkd Test\fP, not \fBmkdir Test\fP. + +Valid SFTP commands are: chgrp, chmod, chown, ln, mkdir, pwd, rename, rm, +rmdir and symlink. + +.TP +.B -postquote +Pass a \fBlist\fP with the FTP commands to pass to the server after your +ftp transfer request. If you do not want to transfer any files, set +\fBnobody\fP to '1' and \fBheader\fP to '0'. + +.TP +.B -prequote +Pass a \fBlist\fP of FTP or SFTP commands to pass to the server after the +transfer type is set. + +.TP +.B -dirlistonly +A 1 tells the library to just list the names of files in a +directory, instead of doing a full directory listing that would include file +sizes, dates etc. It works with both FTP and SFTP urls. + +This causes an FTP NLST command to be sent. Beware that some FTP servers list +only files in their response to NLST, they might not include subdirectories +and symbolic links. + +.TP +.B -append +A 1 parameter tells the extension to append to the remote file instead of +overwriting it. This is only useful when uploading to a ftp site. + +.TP +.B -ftpuseeprt +Set to 1 to tell TclCurl to use the EPRT (and LPRT) command when doing +active FTP downloads (which is enabled by '\fBftpport\fP'). Using EPRT means +that it will first attempt to use EPRT and then LPRT before using PORT, if +you pass zero to this option, it will not try using EPRT or LPRT, only plain PORT. + +.TP +.B -ftpuseepvs +Set to one to tell TclCurl to use the EPSV command when doing passive FTP +downloads (which it always does by default). Using EPSV means that it will +first attempt to use EPSV before using PASV, but if you pass a zero to this +option, it will not try using EPSV, only plain PASV. + +.TP +.B -ftpcreatemissingdirs +If set to 1, TclCurl will attempt to create any remote directory that it +fails to CWD into. CWD is the command that changes working directory. + +This setting also applies to SFTP-connections. TclCurl will attempt to create +the remote directory if it can't obtain a handle to the target-location. The +creation will fail if a file of the same name as the directory to create +already exists or lack of permissions prevents creation. + +.TP +.B -ftpresponsetimeout +Causes TclCurl to set a timeout period (in seconds) on the amount of time that +the server is allowed to take in order to generate a response message for a +command before the session is considered hung. Note that while TclCurl is waiting +for a response, this value overrides \fBtimeout\fP. It is recommended that if used +in conjunction with \fBtimeout\fP, you set it to a value smaller than \fBtimeout\fP. + +.TP +.B -ftpalternativetouser +Pass a string which will be used to authenticate if the usual FTP "USER user" and +"PASS password" negotiation fails. This is currently only known to be required when +connecting to Tumbleweed's Secure Transport FTPS server using client certificates for +authentication. + +.TP +.B -ftpskippasvip +If set to 1, it instructs TclCurl not to use the IP address the +server suggests in its 227-response to TclCurl's PASV command when TclCurl +connects the data connection. Instead TclCurl will re-use the same IP address +it already uses for the control connection. But it will use the port number +from the 227-response. + +This option has no effect if PORT, EPRT or EPSV is used instead of PASV. + +.TP +.B -usessl +You can use ftps:// URLs to explicitly switch on SSL/TSL for the control +connection and the data connection. + +Alternatively, and what seems to be the recommended way, you can set the +option to one of these values: + +.RS +.TP 5 +.B nope +Do not attempt to use SSL +.TP +.B try +Try using SSL, proceed anyway otherwise. +.TP +.B control +Use SSL for the control conecction or fail with "use ssl failed" (64). +.TP +.B all +Use SSL for all communication or fail with "use ssl failed" (64). +.RE + +.TP +.B -ftpsslauth + +Pass TclCurl one of the values from below, to alter how TclCurl issues +"AUTH TLS" or "AUTH SSL" when FTP over SSL is activated (see \fB-ftpssl\fP). + +You may need this option because of servers like BSDFTPD-SSL from +http://bsdftpd-ssl.sc.ru/ "which won't work properly when "AUTH SSL" is issued +(although the server responds fine and everything) but requires "AUTH TLS" +instead". + +.RS +.TP 5 +.B default +Allows TclCurl to decide. +.TP +.B ssl +Try "AUTH SSL" first, and only if that fails try "AUTH TLS". +.TP +.B tls +Try "AUTH TLS" first, and only if that fails try "AUTH SSL". +.RE + +.TP +.B -ftpsslccc +Set it to make TclCurl use CCC (Clear Command Channel). It shuts down the +SSL/TLS layer after authenticating. The rest of the control channel +communication will be unencrypted. This allows NAT routers to follow the +FTP transaction. Possible values are: + +.RS +.TP 5 +.B none +Do not attempt to use CCC. +.TP +.B passive +Do not initiate the shutdown, wait for the server to do it. Do not send a reply. +.TP +.B active +Initiate the shutdown and wait for a reply. +.RE + +.TP +.B -ftpaccount +Pass string (or "" to disable). When an FTP server asks for "account data" after +user name and password has been provided, this data is sent off using the ACCT +command. + +.TP +.B -ftpfilemethod +It allows three values: +.RS +.TP 5 +.B multicwd +The default, TclCurl will do a single CWD operation for each path part in the given +URL. For deep hierarchies this means very many commands. This is how RFC1738 says it +should be done. +.TP +.B nocwd +No CWD at all is done, TclCurl will do SIZE, RETR, STOR, etc and give a full path to +the server. +.TP +.B singlecwd +Make one CWD with the full target directory and then operate on the file "normally". +This is somewhat more standards compliant than 'nocwd' but without the full penalty of 'multicwd'. +.RE + +.SH Protocol options + +.TP +.B -transfertext +A 1 tells the extension to use ASCII mode for ftp transfers, +instead of the default binary transfer. For win32 systems it does not set the +stdout to binary mode. This option can be usable when transferring text data +between systems with different views on certain characters, such as newlines +or similar. + +\fBNOTE:\fP TclCurl does not do a complete ASCII conversion when doing ASCII +transfers over FTP. This is a known limitation/flaw that nobody has +rectified. TclCurl simply sets the mode to ascii and performs a standard +transfer. + +.TP +.B -proxytransfermode +If set to 1, TclCurl sets the transfer mode (binary or ASCII) for FTP transfers +done via an HTTP proxy, by appending ;type=a or ;type=i to the URL. +Without this setting, or it being set to 0, the default, \fB-transfertext\fP has +no effect when doing FTP via a proxy. Beware that not all proxies support this feature. + +.TP +.B -crlf +Convert unix newlines to CRLF newlines on FTP transfers. + +.TP +.B -range +Pass a string as parameter, which should contain the specified range you +want. It should be in the format +.I "X-Y" +, where X or Y may be left out. HTTP +transfers also support several intervals, separated with commas as in +.I "X-Y,N-M" +Using this kind of multiple intervals will cause the HTTP server to send the +response document in pieces (using standard MIME separation techniques). + +Ranges only work on HTTP, FTP and FILE transfers. + +.TP +.B -resumefrom +Pass the offset in number of bytes that you want the transfer to start from. +Set this option to 0 to make the transfer start from the beginning +(effectively disabling resume). + +For FTP, set this option to -1 to make the transfer start from the end of the +target file (useful to continue an interrupted upload). + +.TP +.B -customrequest +Pass a string as parameter. It will be used instead of GET or HEAD when doing +the HTTP request. This is useful for doing DELETE or other more obscure HTTP +requests. Do not do this at will, make sure your server supports the command first. + +Note that TclCurl will still act and assume the keyword it would use if you +do not set your custom and it will act according to that. Thus, changing this +to a HEAD when TclCurl otherwise would do a GET might cause TclCurl to act funny, +and similar. To switch to a proper HEAD, use \fB-nobody\fP, to switch to a proper +POST, use \fB-post\fP or \fB-postfields\fP and so on. + +.TP +.B -filetime +If you pass a 1, TclCurl will attempt to get the +modification date of the remote document in this operation. This requires that +the remote server sends the time or replies to a time querying command. The +getinfo procedure with the +.I filetime +argument can be used after a transfer to extract the received time (if any). + +.TP +.B -nobody +A 1 tells the library not to include the body-part in the +output. This is only relevant for protocols that have a separate header and +body part. On HTTP(S) servers, this will make TclCurl do a HEAD request. + +To change request to GET, you should use \fBhttpget\fP. Change request +to POST with \fBpost\fP etc. + +.TP +.B -infilesize +When uploading a file to a remote site, this option should be used to tell +TclCurl what the expected size of the infile is. + +This option is mandatory for uploading using SCP. + +.TP +.B -upload +A 1 tells the library to prepare for an upload. The +\fB-infile\fP and \fB-infilesize\fP options are also interesting for uploads. +If the protocol is HTTP, uploading means using the PUT request unless you tell +TclCurl otherwise. + +Using PUT with HTTP 1.1 implies the use of a "Expect: 100-continue" header. +You can disable this header with \fB-httpheader\fP as usual. + +If you use PUT to a HTTP 1.1 server, you can upload data without knowing the +size before starting the transfer if you use chunked encoding. You enable this +by adding a header like "Transfer-Encoding: chunked" with \fB-httpheader\fP. +With HTTP 1.0 or without chunked transfer, you must specify the size. + +.TP +.B -maxfilesize +This allows you to specify the maximum size (in bytes) of a file to download. +If the file requested is larger than this value, the transfer will not start +and error 'filesize exceeded' (63) will be returned. + +NOTE: The file size is not always known prior to download, and for such files +this option has no effect even if the file transfer ends up being larger than +this given limit. This concerns both FTP and HTTP transfers. + +.TP +.B -timecondition +This defines how the \fBtimevalue\fP value is treated. You can set this +parameter to \fBifmodsince\fP or \fBifunmodsince\fP. This feature applies to +HTTP and FTP. + +.TP +.B -timevalue +This should be the time in seconds since 1 jan 1970, and the time will be +used in a condition as specified with \fBtimecondition\fP. + + +.SH Connection options + +.TP +.B -timeout +Pass the maximum time in seconds that you allow +the TclCurl transfer operation to take. Do note that normally, name lookups +may take a considerable time and that limiting the operation to less than a +few minutes risks aborting perfectly normal operations. This option will +cause libcurl to use the SIGALRM to enable time-outing system calls. + +In unix-like systems, this might cause signals to be used unless +\fB-nosignal\fP is used. + +.TP +.B -timeoutms +Like \fBtimeout\fP but takes a number of milliseconds instead. If libcurl is +built to use the standard system name resolver, that part will still use +full-second resolution for timeouts. + +.TP +.B -lowspeedlimit +Pass the speed in bytes per second that the transfer should be below during +.B lowspeedtime +seconds for the extension to consider it too slow and abort. + +.TP +.B -lowspeedtime +Pass the time in seconds that the transfer should be below the +.B lowspeedlimit +for the extension to consider it too slow and abort. + +.TP +.B -maxsendspeed +Pass a speed in bytes per seconds. If an upload exceeds this speed on cumulative +average during the transfer, the transfer will pause to keep the average rate less +than or equal to the parameter value. Defaults to unlimited speed. + +.TP +.B -maxrecvspeed +Pass a speed in bytes per second. If a download exceeds this speed on cumulative +average during the transfer, the transfer will pause to keep the average rate less +than or equal to the parameter value. Defaults to unlimited speed. + +.TP +.B -maxconnects +Sets the persistant connection cache size in all the protocols that support +persistent conecctions. The set amount will be the maximum amount of simultaneous +connections that TclCurl may cache in this easy handle. Default is 5, and there +isn't much point in changing this value unless you are perfectly aware of how this +work and changes TclCurl's behaviour. + +When reaching the maximum limit, TclCurl closes the oldest connection in the cache +to prevent the number of open connections to increase. + +\fBNote\fP: if you have already performed transfers with this curl handle, +setting a smaller +.B maxconnects +than before may cause open connections to unnecessarily get closed. + +\fBNote\fP that if you add this easy handle to a multi handle, this setting is not +being acknowledged, instead you must configure the multi handle its own +\fBmaxconnects\fP option. + +.TP +.B -connecttimeout +Maximum time in seconds that you allow the +connection to the server to take. This only limits the connection phase, once +it has connected, this option is of no more use. Set to zero to disable +connection timeout (it will then only timeout on the internal timeouts). + +In unix-like systems, this might cause signals to be used unless +\fB-nosignal\fP is set. + +.TP +.B -connecttimeoutms +Like \fBconnecttimeout\fP but takes a number of milliseconds instead. If libcurl +is built to use the standard system name resolver, that part will still use +full-second resolution for timeouts. + +.TP +.B -ipresolve +Allows an application to select what kind of IP addresses to use when +resolving host names. This is only interesting when using host names +that resolve addresses using more than one version of IP. The allowed +values are: +.RS +.TP 5 +.B whatever +Default, resolves addresses to all IP versions that your system allows. +.TP +.B v4 +Resolve to ipv4 addresses. +.TP +.B v6 +Resolve to ipv6 addresses. +.RE + +.SH SSL and security options + +.TP +.B -sslcert +Pass a string as parameter. The string should be the file name of your certificate. +The default format is "PEM" and can be changed with \fB-sslcerttype\fP. + +With NSS this is the nickname of the certificate you wish to authenticate with. + +.TP +.B -sslcerttype +Pass a string as parameter. The string should be the format of your certificate. +Supported formats are "PEM" and "DER". + +.TP +.B -sslkey +Pass a pointer to a zero terminated string as parameter. The string should be +the file name of your private key. The default format is "PEM" and can be +changed with \fB-sslkeytype\fP. + +.TP +.B -sslkeytype +Pass a pointer to a zero terminated string as parameter. The string should be +the format of your private key. Supported formats are "PEM", "DER" and "ENG" + +\fBNOTE:\fPThe format "ENG" enables you to load the private key from a crypto +engine. in this case \fB-sslkey\fP is used as an identifier passed to +the engine. You have to set the crypto engine with \fB-sslengine\fP. The "DER" +format key file currently does not work because of a bug in OpenSSL. + +.TP +.B -keypasswd +Pass a string as parameter. It will be used as the password required to use the +\fB-sslkey\fP or \fB-sshprivatekeyfile\fP private key. + +You never need a pass phrase to load a certificate but you need one to load you +private key. + +This option used to be known as \fB-sslkeypasswd\fP and \fB-sslcertpasswd\fP. + +.TP +.B -sslengine +Pass a string as parameter. It will be used as the identifier for the crypto +engine you want to use for your private key. + +\fBNOTE:\fPIf the crypto device cannot be loaded, an error will be returned. + +.TP +.B -sslenginedefault +Pass a 1 to set the actual crypto engine as the default for (asymmetric) crypto operations. + +\fBNOTE:\fPIf the crypto device cannot be set, an error will be returned. + +.TP +.B -sslversion +Use it to set what version of SSL/TLS to use. The available options are: +.RS +.TP 5 +.B default +The default action. This will attempt to figure out the remote SSL protocol version, +i.e. either SSLv3 or TLSv1 (but not SSLv2, which became disabled by default with 7.18.1). +.TP +.B tlsv1 +Force TLSv1 +.TP +.B sslv2 +Force SSLv2 +.TP +.B sslv3 +Force SSLv3 +.RE + +.TP +.B -sslverifypeer +This option determines whether TclCurl verifies the authenticity of the peer's certificate. +A 1 means it verifies; zero means it doesn't. The default is 1. + +When negotiating an SSL connection, the server sends a certificate indicating its identity. +TclCurl verifies whether the certificate is authentic, i.e. that you can trust that the +server is who the certificate says it is. This trust is based on a chain of digital signatures, +rooted in certification authority (CA) certificates you supply. + +TclCurl uses a default bundle of CA certificates that comes with libcurl but you can specify +alternate certificates with the \fB-cainfo\fP or the \fB-capath\fP options. + +When \fB-sslverifypeer\fP is nonzero, and the verification fails to prove that the certificate +is authentic, the connection fails. When the option is zero, the connection succeeds regardless. + +Authenticating the certificate is not by itself very useful. You typically want to ensure +that the server, as authentically identified by its certificate, is the server you mean to +be talking to, use \fB-sslverifyhost\fP to control that. + +.TP +.B -cainfo +Pass a file naming holding the certificate to verify the peer with. This only +makes sense when used in combination with the \fB-sslverifypeer\fP option, if +it is set to zero \fB-cainfo\fP need not even indicate an accessible file. + +When built against NSS this is the directory that the NSS certificate database +resides in. + +.TP +.B -issuercert +Pass a string naming a file holding a CA certificate in PEM format. If the option +is set, an additional check against the peer certificate is performed to verify +the issuer is indeed the one associated with the certificate provided by the option. +This additional check is useful in multi-level PKI where one need to enforce the peer +certificate is from a specific branch of the tree. + +This option makes sense only when used in combination with the \fB-sslverifypeer\fP +option. Otherwise, the result of the check is not considered as failure. + +.TP +.B -capath +Pass the directory holding multiple CA certificates to verify the peer with. +The certificate directory must be prepared using the openssl c_rehash utility. +This only makes sense when used in combination with the \fB-sslverifypeer\fP +option, if it is set to zero, \fB-capath\fP need not even indicate an accessible +path. + +This option apparently does not work in Windows due to some limitation in openssl. + +This option is OpenSSL-specific and does nothing if libcurl is built to use GnuTLS. + +.TP +.B -crlfile +Pass a string naming a file with the concatenation of CRL (in PEM format) to use in +the certificate validation that occurs during the SSL exchange. + +When libcurl is built to use NSS or GnuTLS, there is no way to influence the use of +CRL passed to help in the verification process. When built with OpenSSL support, +X509_V_FLAG_CRL_CHECK and X509_V_FLAG_CRL_CHECK_ALL are both set, requiring CRL +check against all the elements of the certificate chain if a CRL file is passed. + +This option makes sense only when used in combination with the \fB-sslverifypeer\fP +option. + +.TP +.B -randomfile +Pass a file name. The file will be used to read from to seed the random engine +for SSL. The more random the specified file is, the more secure will the SSL +connection become. + +.TP +.B -egdsocket +Pass a path name to the Entropy Gathering Daemon socket. It will be used to seed +the random engine for SSL. + +.TP +.B -sslverifyhost +This option determines whether TclCurl verifies that the server claims to be +who you want it to be. + +When negotiating an SSL connection, the server sends a certificate +indicating its identity. + +When \fB-sslverifyhost\fP is set to 2, that certificate must indicate +that the server is the server to which you meant to connect, or the +connection fails. + +TclCurl considers the server the intended one when the Common Name field +or a Subject Alternate Name field in the certificate matches the host +name in the URL to which you told Curl to connect. + +When set to 1, the certificate must contain a Common Name field, +but it does not matter what name it says. (This is not ordinarily a +useful setting). + +When the value is 0, the connection succeeds regardless of the names in +the certificate. + +The default is 2. + +This option controls the identity that the server \fIclaims\fP. The server +could be lying. To control lying, see \fBsslverifypeer\fP. + +.TP +.B -sslcypherlist +Pass a string holding the ciphers to use for the SSL connection. The list must +consists of one or more cipher strings separated by colons. Commas or spaces +are also acceptable separators but colons are normally used, , - and + can be +used as operators. + +For OpenSSL and GnuTLS valid examples of cipher lists include 'RC4-SHA', 'SHA1+DES', +'TLSv1' and 'DEFAULT'. The default list is normally set when you compile OpenSSL. + +You will find more details about cipher lists on this URL: + http://www.openssl.org/docs/apps/ciphers.html + +For NSS valid examples of cipher lists include 'rsa_rc4_128_md5', 'rsa_aes_128_sha', +etc. With NSS you don't add/remove ciphers. If you use this option then all known +ciphers are disabled and only those passed in are enabled. + +You'll find more details about the NSS cipher lists on this URL: + http://directory.fedora.redhat.com/docs/mod_nss.html + +.TP +.B -sslsessionidcache +Pass a 0 to disable TclCurl's use of SSL session-ID caching or a 1 to enable it. +By default all transfers are done using the cache. Note that while nothing ever +should get hurt by attempting to reuse SSL session-IDs, there seem to be broken SSL +implementations in the wild that may require you to disable this in order for you to +succeed. + +.TP +.B -krblevel +Set the kerberos security level for FTP, this also enables kerberos awareness. +This is a string, 'clear', 'safe', 'confidential' or 'private'. If the string +is set but does not match one of these, 'private' will be used. Set the string +to NULL to disable kerberos4. Set the string to "" to disable kerberos +support for FTP. + +.SH SSH options + +.TP +.B -sshauthtypes +The allowed types are: + +.RS +.TP 5 +.B publickey +.TP +.B password +.TP +.B host +.TP +.B keyboard +.TP +.B any +To let TclCurl pick one +.RE + +.TP +.B -sshhostpublickeymd5 +Pass a string containing 32 hexadecimal digits. The string should be the 128 +bit MD5 cheksum of the remote host public key, and TclCurl will reject the +connection to the host unless the md5sums match. This option is only for SCP +and SFTP transfers. + +.TP +.B -publickeyfile +Pass the file name for your public key. If not used, TclCurl defaults to using \fB~/.ssh/id_dsa.pub\fP. + +.TP +.B -privatekeyfile +Pass the file name for your private key. If not used, TclCurl defaults to using \fB~/.ssh/id_dsa\fP. +If the file is password-protected, set the password with \fB-keypasswd\fP. + +.SH Other options + +.TP +.B -headervar +Name of the Tcl array variable where TclCurl will store the headers returned +by the server. + +When a server sends a chunked encoded transfer, it may contain a +trailer. That trailer is identical to a HTTP header and if such a trailer is +received it is passed to the application using this callback as well. There +are several ways to detect it being a trailer and not an ordinary header: 1) +it comes after the response-body. 2) it comes after the final header line (CR +LF) 3) a Trailer: header among the response-headers mention what header to +expect in the trailer. + +.TP +.B -bodyvar +Name of the Tcl variable where TclCurl will store the file requested, the file +may contain text or binary data. + +.TP +.B -canceltransvar +Name of a Tcl variable, in case you have defined a procedure to call with +\fB-progressproc\fP setting this variable to '1' will cancel the transfer. + +.TP +.B -command +Executes the given command after the transfer is done, since it only works +with blocking transfers, it is pretty much useless. + +.TP +.B -share +Pass a share handle as a parameter. The share handle must have been created by +a previous call to \fBcurl::shareinit\fP. Setting this option, will make this +handle use the data from the shared handle instead of keeping the data to itself. +See \fItclcurl_share\fP for details. + +.TP +.B -newfileperms +Pass a number as a parameter, containing the value of the permissions that will +be assigned to newly created files on the remote server. The default value is 0644, +but any valid value can be used. The only protocols that can use this are sftp://, +scp:// and file://. + +.TP +.B -newdirectoryperms +Pass a number as a parameter, containing the value of the permissions that will be +assigned to newly created directories on the remote server. The default value is 0755, +but any valid value can be used. The only protocols that can use this are sftp://, scp:// +and file://. + +.SH NOT SUPPORTED +Some of the options libcurl offers are not supported, I don't think them +worth supporting in TclCurl but if you need one of them don't forget to +complain: +.sp +.B CURLOPT_FRESH_CONNECT, CURLOPT_FORBID_REUSE, CURLOPT_PRIVATE, +.B CURLOPT_SSL_CTX_FUNCTION, CURLOPT_SSL_CTX_DATA, CURLOPT_SSL_CTX_FUNCTION and +.B CURLOPT_CONNECT_ONLY, CURLOPT_OPENSOCKETFUNCTION, CURLOPT_OPENSOCKETDATA. + +.SH curlHandle perform +This procedure is called after the +.B init +and all the +.B configure +calls are made, and will perform the transfer as described in the options. +.sp +It must be called with the same +\fIcurlHandle\fP \fBcurl::init\fP call returned. +You can do any amount of calls to perform while using the same handle. If you +intend to transfer more than one file, you are even encouraged to do +so. TclCurl will then attempt to re-use the same connection for the following +transfers, thus making the operations faster, less CPU intense and using less +network resources. Just note that you will have to use +.I configure +between the invokes to set options for the following perform. +.sp +You must never call this procedure simultaneously from two places using the +same handle. Let it return first before invoking it another time. If +you want parallel transfers, you must use several curl handles. +.TP +.B RETURN VALUE +'0' if all went well, non-zero if it didn't. In case of error, if the +.I errorbuffer +was set with +.I configure +there will be a readable error message. +The error codes are: +.IP 1 +Unsupported protocol. This build of TclCurl has no support for this protocol. +.IP 2 +Very early initialization code failed. This is likely to be and internal error +or problem. +.IP 3 +URL malformat. The syntax was not correct. +.IP 5 +Couldn't resolve proxy. The given proxy host could not be resolved. +.IP 6 +Couldn't resolve host. The given remote host was not resolved. +.IP 7 +Failed to connect to host or proxy. +.IP 8 +FTP weird server reply. The server sent data TclCurl couldn't parse. +The given remote server is probably not an OK FTP server. +.IP 9 +We were denied access to the resource given in the URL. For FTP, this occurs +while trying to change to the remote directory. +.IP 11 +FTP weird PASS reply. TclCurl couldn't parse the reply sent to the PASS request. +.IP 13 +FTP weird PASV reply, TclCurl couldn't parse the reply sent to the PASV or EPSV +request. +.IP 14 +FTP weird 227 format. TclCurl couldn't parse the 227-line the server sent. +.IP 15 +FTP can't get host. Couldn't resolve the host IP we got in the 227-line. +.IP 17 +FTP couldn't set type. Couldn't change transfer method to either binary or +ascii. +.IP 18 +Partial file. Only a part of the file was transfered, this happens when +the server first reports an expected transfer size and then delivers data +that doesn't match the given size. +.IP 19 +FTP couldn't RETR file, we either got a weird reply to a 'RETR' command or +a zero byte transfer. +.IP 21 +Quote error. A custom 'QUOTE' returned error code 400 or higher (for FTP) or +otherwise indicated unsuccessful completion of the command. +.IP 22 +HTTP returned error. This return code only appears if \fB-failonerror\fP is +used and the HTTP server returns an error code that is 400 or higher. +.IP 23 +Write error. TclCurl couldn't write data to a local filesystem or an error +was returned from a write callback. +.IP 25 +Failed upload failed. For FTP, the server typcially denied the STOR +command. The error buffer usually contains the server's explanation to this. +.IP 26 +Read error. There was a problem reading from a local file or an error was returned +from the read callback. +.IP 27 +Out of memory. A memory allocation request failed. This should never happen unless +something weird is going on in your computer. +.IP 28 +Operation timeout. The specified time-out period was reached according to the +conditions. +.IP 30 +The FTP PORT command failed, not all FTP servers support the PORT command, +try doing a transfer using PASV instead!. +.IP 31 +FTP couldn't use REST. This command is used for resumed FTP transfers. +.IP 33 +Range error. The server doesn't support or accept range requests. +.IP 34 +HTTP post error. Internal post-request generation error. +.IP 35 +SSL connect error. The SSL handshaking failed, the error buffer may have +a clue to the reason, could be certificates, passwords, ... +.IP 36 +FTP bad download resume. Couldn't continue an earlier aborted download, probably +because you are trying to resume beyond the file size. +.IP 37 +A file given with FILE:// couldn't be read. Did you checked the permissions? +.IP 38 +LDAP cannot bind. LDAP bind operation failed. +.IP 39 +LDAP search failed. +.IP 41 +A required zlib function was not found. +.IP 42 +Aborted by callback. An application told TclCurl to abort the operation. +.IP 43 +Internal error. A function was called with a bad parameter. +.IP 45 +Interface error. A specified outgoing interface could not be used. +.IP 47 +Too many redirects. When following redirects, TclCurl hit the maximum amount, set +your limit with --maxredirs +.IP 48 +Unknown TELNET option specified. +.IP 49 +A telnet option string was illegally formatted. +.IP 51 +The remote peer's SSL certificate or SSH md5 fingerprint wasn't ok +.IP 52 +The server didn't reply anything, which here is considered an error. +.IP 53 +The specified crypto engine wasn't found. +.IP 54 +Failed setting the selected SSL crypto engine as default! +.IP 55 +Failed sending network data. +.IP 56 +Failure with receiving network data. +.IP 58 +Problem with the local client certificate. +.IP 59 +Couldn't use specified SSL cipher. +.IP 60 +Peer certificate cannot be authenticated with known CA certificates. +.IP 61 +Unrecognized transfer encoding. +.IP 62 +Invalid LDAP URL. +.IP 63 +Maximum file size exceeded. +.IP 64 +SSL use failed. +.IP 65 +Sending the data requires a rewind that failed, since TclCurl should +take care of it for you, it means you found a bug. +.IP 66 +Failed to initialise ssl engine. +.IP 67 +Failed to login, user password or similar was not accepted. +.IP 68 +File not found on TFTP server. +.IP 69 +There is a permission problem with the TFTP request. +.IP 70 +The remote server has run out of space. +.IP 71 +Illegal TFTP operation. +.IP 72 +Unknown transfer ID. +.IP 73 +TFTP file already exists and will not be overwritten. +.IP 74 +No such user in the TFTP server and good behaving TFTP server +should never return this. +.IP 75 +Character conversion failed. +.IP 77 +Problem with reading the SSL CA cert (path? access rights?). +.IP 78 +Remote file not found +.IP 79 +Error from the SSH layer +.IP 80 +Failed to shut down the SSL connection +.IP 82 +Failed to load CRL file +.IP 83 +Issuer check failed + +.SH curlHandle getinfo option +Request internal information from the curl session with this procedure. +This procedure is intended to get used *AFTER* a performed transfer, +and can be relied upon only if the \fBperform\fP returns 0. Use +this function AFTER a performed transfer if you want to get +transfer-oriented data. + +The following information can be extracted: + +.TP +.B effectiveurl +Returns the last used effective URL. + +.TP +.B responsecode +Returns the last received HTTP or FTP code. This will be zero if no server +response code has been received. Note that a proxy's CONNECT response should +be read with \fBhttpconnectcode\fP and not this. + +.TP +.B httpconnectcode +Returns the last received proxy response code to a CONNECT request. + +.TP +.B filetime +Returns the remote time of the retrieved document (in number of seconds +since 1 jan 1970 in the GMT/UTC time zone). If you get -1, +it can be because of many reasons (unknown, the server hides it or the +server doesn't support the command that tells document time etc) and the time +of the document is unknown. +.sp +In order for this to work you have to set the \fB-filetime\fP option before +the transfer. + +.TP +.B namelookuptime +Returns the time, in seconds, it took from the start until the name resolving +was completed. + +.TP +.B connecttime +Returns the time, in seconds, it took from the start until the connect to the +remote host (or proxy) was completed. + +.TP +.B appconnecttime +Returns the time, in seconds, it took from the start until the SSL/SSH +connect/handshake to the remote host was completed. This time is most often very +near to the PRETRANSFER time, except for cases such as HTTP pippelining where the +pretransfer time can be delayed due to waits in line for the pipeline and more. + +.TP +.B pretransfertime +Returns the time, in seconds, it took from the start until the file transfer +is just about to begin. This includes all pre-transfer commands and +negotiations that are specific to the particular protocol(s) involved. + +.TP +.B starttransfertime +Returns the time, in seconds, it took from the start until the first byte +is just about to be transfered. This includes the \fBpretransfertime\fP, +and also the time the server needs to calculate the result. + +.TP +.B totaltime +Returns the total transaction time, in seconds, for the previous transfer, +including name resolving, TCP connect etc. + +.TP +.B redirecturl +Returns the URL a redirect would take you to if you enable \fBfollowlocation\fP. +This can come very handy if you think using the built-in libcurl redirect logic +isn't good enough for you but you would still prefer to avoid implementing all +the magic of figuring out the new URL. + +.TP +.B redirecttime +Returns the total time, in seconds, it took for all redirection steps +including name lookup, connect, pretransfer and transfer before +the final transaction was started, it returns the complete execution +time for multiple redirections, so it returns zero if no redirections +were needed. + +.TP +.B redirectcount +Returns the total number of redirections that were actually followed. + +.TP +.B numconnects +Returns how many new connections TclCurl had to create to achieve the +previous transfer (only the successful connects are counted). Combined +with \fBredirectcount\fP you are able to know how many times TclCurl +successfully reused existing connection(s) or not. See the Connection +Options of \fBsetopt\fP to see how TclCurl tries to make persistent +connections to save time. + +.TP +.B primaryip +Returns the IP address of the most recent connection done with this handle. +This string may be IPv6 if that's enabled. + +.TP +.B sizeupload +Returns the total amount of bytes that were uploaded. + +.TP +.B sizedownload +Returns the total amount of bytes that were downloaded. The amount is only +for the latest transfer and will be reset again for each new transfer. + +.TP +.B speeddownload +Returns the average download speed, measured in bytes/second, for the complete download. + +.TP +.B speedupload +Returns the average upload speed, measured in bytes/second, for the complete upload. + +.TP +.B headersize +Returns the total size in bytes of all the headers received. + +.TP +.B requestsize +Returns the total size of the issued requests. This is so far only for HTTP +requests. Note that this may be more than one request if followLocation is true. + +.TP +.B sslverifyresult +Returns the result of the certification verification that was requested +(using the -sslverifypeer option to configure). + +.TP +.B sslengines +Returns a \fBlist\fP of the OpenSSL crypto-engines supported. Note that engines are +normally implemented in separate dynamic libraries. Hence not all the returned +engines may be available at run-time. + +.TP +.B contentlengthdownload +Returns the content-length of the download. This is the value read from the +.B Content-Length: +field. + +.TP +.B contentlengthupload +Returns the specified size of the upload. + +.TP +.B contenttype +Returns the content-type of the downloaded object. This is the value +read from the Content-Type: field. If you get an empty string, it means +the server didn't send a valid Content-Type header or that the protocol +used doesn't support this. + +.TP +.B httpauthavail +Returns a list with the authentication method(s) available. + +.TP +.B proxyauthavail +Returns a list with the authentication method(s) available for your +proxy athentication. + +.TP +.B oserrno +Returns the errno value from a connect failure. + +.TP +.B cookielist +Returns a list of all cookies TclCurl knows (expired ones, too). If there +are no cookies (cookies for the handle have not been enabled or simply +none have been received) the list will be empty. + +.TP +.B ftpentrypath +Returns a string holding the path of the entry path. That is the initial path +TclCurl ended up in when logging on to the remote FTP server. Returns an empty +string if something is wrong. + +.SH curlHandle cleanup +This procedure must be the last one to call for a curl session. It is the +opposite of the +.I curl::init +procedure and must be called with the same +.I curlhandle +as input as the curl::init call returned. +This will effectively close all connections TclCurl has used and possibly +has kept open until now. Don't call this procedure if you intend to transfer +more files. + +.SH curlHandle reset + +Re-initializes all options previously set on a specified handle to the +default values. + +This puts back the handle to the same state as it was in when it was just +created with curl::init. + +It does not change the following information kept in the handle: live +connections, the Session ID cache, the DNS cache, the cookies and shares. + +.SH curlHandle duphandle +This procedure will return a new curl handle, a duplicate, +using all the options previously set in the input curl handle. +Both handles can subsequently be used independently and +they must both be freed with +.B cleanup. +The new handle will not inherit any state information, +connections, SSL sessions or cookies. +.TP +.B RETURN VALUE +A new curl handle or an error message if the copy fails. + +.SH curlHandle pause +You can use this command from within a progress callback procedure +to pause the transfer. + +.SH curlHandle resume +Resumes a transfer paused with \fBcurlhandle pause\fP + +.SH curl::transfer +In case you do not want to use persistant connections you can use this +command, it takes the same arguments as the \fIcurlHandle\fP \fBconfigure\fP +and will init, configure, perform and cleanup a connection for you. + +You can also get the \fIgetinfo\fP information by using \fI-infooption variable\fP +pairs, after the transfer \fIvariable\fP will contain the value that would have +been returned by \fI$curlHandle getinfo option\fP. +.TP +.B RETURN VALUE +The same error code \fBperform\fP would return. + +.SH curl::version +Returns a string with the version number of tclcurl, libcurl and some of +its important components (like OpenSSL version). +.TP +.B RETURN VALUE +The string with the version info. + +.SH curl::escape url +This procedure will convert the given input string to an URL encoded string and +return that. All input characters that are not a-z, +A-Z or 0-9 will be converted to their "URL escaped" version (%NN where NN is a +two-digit hexadecimal number) +.TP +.B RETURN VALUE +The converted string. +.SH curl::unescape url +This procedure will convert the given URL encoded input string to a "plain +string" and return that. All input characters that +are URL encoded (%XX where XX is a two-digit hexadecimal number) will be +converted to their plain text versions. +.TP +.B RETURN VALUE +The string unencoded. + +.SH curl::curlConfig option +Returns some information about how you have +.B cURL +installed. + +.TP +.B -prefix +Returns the directory root where you installed +.B cURL +.TP +.B -feature +Returns a list containing particular main features the installed +.B libcurl +was built with. The list may include SSL, KRB4 or IPv6, do not +assume any particular order. +.TP +.B -vernum +Outputs version information about the installed libcurl, in +numerical mode. This outputs the version number, in hexadecimal, +with 8 bits for each part; major, minor, patch. So that libcurl +7.7.4 would appear as 070704 and libcurl 12.13.14 would appear as +0c0d0e... + +.SH curl::versioninfo option +Returns information about various run-time features in TclCurl. + +Applications should use this information to judge if things are possible to do +or not, instead of using compile-time checks, as dynamic/DLL libraries can be +changed independent of applications. + +.TP +.B -version +Returns the version of libcurl we are using. + +.TP +.B -versionnum +Retuns the version of libcurl we are using in hexadecimal with 8 bits for each +part; major, minor, patch. So that libcurl 7.7.4 would appear as 070704 and +libcurl 12.13.14 would appear as 0c0d0e... Note that the initial zero might be +omitted. + +.TP +.B -host +Returns a string with the host information as discovered by a configure +script or set by the build environment. + +.TP +.B -features +Returns a list with the features compiled into libcurl, the possible elements are: +.RS +.TP 5 +.B ASYNCHDNS +Libcurl was built with support for asynchronous name lookups, which allows +more exact timeouts (even on Windows) and less blocking when using the multi +interface. +.TP +.B CONV +Libcurl was built with support for character conversions. +.TP +.B DEBUG +Libcurl was built with extra debug capabilities built-in. This is mainly of +interest for libcurl hackers. +.TP +.B GSSNEGOTIATE +Supports HTTP GSS-Negotiate. +.TP +.B IDN +Supports IDNA, domain names with international letters. +.TP +.B IPV6 +Supports IPv6. +.TP +.B KERBEROS4 +Supports kerberos4 (when using FTP). +.TP +.B LARGEFILE +Libcurl was built with support for large files. +.TP +.B LIBZ +Supports HTTP deflate using libz. +.TP +.B NTML +Supports HTTP NTLM +.TP +.B SPNEGO +Libcurl was built with support for SPNEGO authentication (Simple and Protected +GSS-API Negotiation Mechanism, defined in RFC 2478) +.TP +.B SSL +Supports SSL (HTTPS/FTPS) +.TP +.B SSPI +Libcurl was built with support for SSPI. This is only available on Windows and +makes libcurl use Windows-provided functions for NTLM authentication. It also +allows libcurl to use the current user and the current user's password without +the app having to pass them on. +.RE +Do not assume any particular order. + +.TP +.B -sslversion +Returns a string with the OpenSSL version used, like OpenSSL/0.9.6b. + +.TP +.B -sslversionnum +Returns the numerical OpenSSL version value as defined by the OpenSSL project. +If libcurl has no SSL support, this is 0. + +.TP +.B -libzversion +Returns a string, there is no numerical version, for example: 1.1.3. + +.TP +.B -protocols +Lists what particular protocols the installed TclCurl was built to support. +At the time of writing, this list may include HTTP, HTTPS, FTP, FTPS, +FILE, TELNET, LDAP, DICT. Do not assume any particular order. The protocols +will be listed using uppercase. There may be none, one or several protocols +in the list. + +.SH curl::easystrerror errorCode +This procedure returns a string describing the error code passed in the argument. + +.SH "SEE ALSO" +.I curl, The art of HTTP scripting (at http://curl.haxx.se), RFC 2396,