X-Git-Url: https://git.sven.stormbind.net/?a=blobdiff_plain;f=doc%2FSinComprimir%2Ftclcurl.n;fp=doc%2FSinComprimir%2Ftclcurl.n;h=0000000000000000000000000000000000000000;hb=b62db6a104a211b14dc512cbb9cbcea49613ff19;hp=cb51d822f2cc2a79b768e11196e60b9aa74ea4fb;hpb=b0e6fb6e4379fb87fa2854b84a56c5ad49c644da;p=sven%2Ftclcurl.git diff --git a/doc/SinComprimir/tclcurl.n b/doc/SinComprimir/tclcurl.n deleted file mode 100644 index cb51d82..0000000 --- a/doc/SinComprimir/tclcurl.n +++ /dev/null @@ -1,2078 +0,0 @@ -.\" 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,