← Back to branch summary

~ubuntu-branches/debian/sid/tclcurl/sid

« back to all changes in this revision

Viewing changes to doc/tclcurl.n

  • Committer: Bazaar Package Importer
  • Author(s): Sven Hoexter
  • Date: 2009-08-05 21:30:47 UTC
  • mfrom: (1.3.2 upstream)
  • Revision ID: james.westby@ubuntu.com-20090805213047-jfz9ljcp5fzrxa5o
Tags: 7.19.0-1
* New upstream release.
  + Refresh all patches.
  + Build-Depend at least on libcurl4 (>= 7.19.0).
* Update mail address of the upstream maintainer in debian/copyright.
* Bump Standards-Version to 3.8.2.
  + Add a debian/README.source file.
* Update debian/copyright with copyright information for Makefile.in
  and tclconfig/tcl.m4. Thanks to Ondrej Certik for the pointer in
  mysqltcl which has to applied here aswell.
* Add description header to all patches.
* Add patches/example-shebang. This patch adds a working shebang line
  to those example files that carry one (Thanks to Sergei).
* Set the permissions for the example files to 644, except for those
  with a working shebang line (Thanks to Sergei).

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/tclcurl.n
1
1
.\" You can view this file with:
2
2
.\" nroff -man [file]
3
3
.\" Adapted from libcurl docs by fandom@telefonica.net
4
 
.TH TclCurl n "1 November 2007" "TclCurl 7.17.1" "TclCurl Easy Interface"
 
4
.TH TclCurl n "8 September 2008" "TclCurl 7.19.0 "TclCurl Easy Interface"
5
5
.SH NAME
6
6
TclCurl: - get  a  URL with FTP, FTPS, HTTP, HTTPS, SCP, SFTP, TFTP, TELNET, DICT, FILE or LDAP syntax.
7
7
.SH SYNOPSIS
11
11
.sp
12
12
.IB curlHandle " perform"
13
13
.sp
14
 
.IB curlHandle " duhandle"
15
 
.sp
16
14
.IB curlHandle " getinfo " curlinfo_option
17
15
.sp
18
16
.IB curlhandle " cleanup"
19
17
.sp
20
18
.IB curlhandle " reset"
21
19
.sp
 
20
.IB curlHandle " duhandle"
 
21
.sp
 
22
.IB curlHandle " pause"
 
23
.sp
 
24
.IB curlHandle " resume"
 
25
.sp
22
26
.BI curl::transfer " ?options?"
23
27
.sp
24
28
.BI curl::version
83
87
 
84
88
.TP
85
89
.B -verbose
86
 
Set the parameter to non-zero to get the library to display a lot of verbose
 
90
Set the parameter to 1 to get the library to display a lot of verbose
87
91
information about its operations. Very useful for libcurl and/or protocol
88
92
debugging and understanding.
89
93
 
93
97
 
94
98
.TP
95
99
.B -header
96
 
A non-zero parameter tells the extension to include the headers in the body
97
 
output. This is only relevant for protocols that actually have headers preceding
98
 
the  data (like HTTP).
 
100
A 1 tells the extension to include the headers in the body output. This is
 
101
only relevant for protocols that actually have headers preceding the data (like HTTP).
99
102
 
100
103
.TP
101
104
.B -noprogress
102
 
A non-zero parameter tells the extension to turn on the built-in progress meter.
 
105
A 1 tells the extension to turn on the built-in progress meter.
103
106
Nowadays it is turn off by default.
104
107
 
105
108
.TP
106
109
.B -nosignal
107
 
A non zero parameter tells TclCurl not use any functions that install signal
 
110
A 1 tells TclCurl not use any functions that install signal
108
111
handlers or any functions that cause signals to be sent to the process. This
109
112
option is mainly here to allow multi-threaded unix applications to still
110
113
set/use all timeout options etc, without risking getting signals.
157
160
called during periods of idleness unless you call the appropriate procedure
158
161
that performs transfers.
159
162
 
 
163
You can pause and resume a transfer from within this procedure using the
 
164
\fBpause\fP and \fBresume\fP commands.
 
165
 
160
166
.TP
161
167
.B -writeheader
162
168
Pass a the file name to be used to write the header part of the received data to.
190
196
of stderr when reporting errors.
191
197
.TP
192
198
.B -failonerror
193
 
A non-zero parameter tells the extension to fail silently if the HTTP code
 
199
A 1 parameter tells the extension to fail silently if the HTTP code
194
200
returned is equal or larger than 400. The default action would be to return
195
201
the page normally, ignoring that code.
196
202
 
253
259
 
254
260
.TP
255
261
.B -proxytype
256
 
Pass the type of  the  proxy. Available options are 'http', 'socks4'
 
262
Pass the type of  the  proxy. Available options are 'http', 'socks4', 'socks4a'
257
263
and 'socks5', with the HTTP one being default.
258
264
 
259
265
.TP
260
266
.B -httpproxytunnel
261
 
Set the parameter to non-zero to get the extension to tunnel all non-HTTP
 
267
Set the parameter to 1 to get the extension to tunnel all non-HTTP
262
268
operations through the given HTTP proxy. Do note that there is a big
263
269
difference between using a proxy and tunneling through it. If you don't know what
264
270
this means, you probably don't want this tunnel option.
293
299
 
294
300
.TP
295
301
.B -dnsuseglobalcache
296
 
If the value passed is non-zero, it tells TclCurl to use a global DNS cache that
 
302
If the value passed is 1, it tells TclCurl to use a global DNS cache that
297
303
will survive between curl handles creations and deletions. This is not thread-safe
298
304
as it uses a global varible.
299
305
 
328
334
delay. This is less efficient than sending larger amounts of data at a time, and can contribute to
329
335
congestion on the network if overdone.
330
336
 
 
337
.TP
 
338
.B -addressscope
 
339
Pass a number specifying the scope_id value to use when connecting to IPv6 link-local or site-local
 
340
addresses.
 
341
 
331
342
.SH Names and Passwords options
332
343
 
333
344
.TP
334
345
.B -netrc
335
 
A non-zero parameter tells the extension to scan your
 
346
A 1 parameter tells the extension to scan your
336
347
.B ~/.netrc
337
348
file to find user name and password for the remote site you are about to
338
349
access. Do note that TclCurl does not verify that the file has the correct
444
455
 
445
456
.TP
446
457
.B -autoreferer
447
 
Pass a non-zero parameter to enable this. When enabled, TclCurl will
 
458
Pass an 1 parameter to enable this. When enabled, TclCurl will
448
459
automatically set the Referer: field in requests where it follows a Location:
449
460
redirect.
450
461
 
465
476
 
466
477
.TP
467
478
.B -followlocation
468
 
A non-zero parameter tells the library to follow any
 
479
An 1 tells the library to follow any
469
480
.B Location: header
470
481
that the server sends as part of a HTTP header.
471
482
 
477
488
 
478
489
.TP
479
490
.B -unrestrictedauth
480
 
A non-zero parameter tells the extension it can continue
 
491
An 1 parameter tells the extension it can continue
481
492
to  send authentication (user+password) when following
482
493
locations, even when hostname changed. Note that  this
483
494
is  meaningful  only  when setting \fB-followlocation\fP.
492
503
 
493
504
.TP
494
505
.B -post301
495
 
A non-zero parameter tells TclCurl to respect RFC 2616/10.3.2 and not
 
506
An 1 tells TclCurl to respect RFC 2616/10.3.2 and not
496
507
convert POST requests into GET requests when following a 301 redirection. The
497
508
non-RFC behaviour is ubiquitous in web browsers, so the conversion is done
498
509
by default to maintain consistency. However, a server may require
501
512
 
502
513
.TP
503
514
.B -put
504
 
A non-zero parameter tells the extension to use HTTP PUT a file. The file to put
 
515
An 1 parameter tells the extension to use HTTP PUT a file. The file to put
505
516
must be set with \fB-infile\fP and \fB-infilesize\fP.
506
517
 
507
518
This option is deprecated starting with version 0.12.1, you should use \fB-upload\fP.
508
519
 
509
520
.TP
510
521
.B -post
511
 
A non-zero parameter tells the library to do a regular HTTP post. This is a
 
522
An 1 parameter tells the library to do a regular HTTP post. This is a
512
523
normal application/x-www-form-urlencoded kind, which is the most commonly used
513
524
one by HTML forms. See the \fB-postfields\fP option for how to specify the
514
525
data to post and \fB-postfieldsize\fP about how to set the data size.
529
540
With HTTP 1.0 or without chunked transfer, you must specify the size in the
530
541
request.
531
542
 
532
 
When setting \fBpost\fP to a non-zero value, it will automatically set
 
543
When setting \fBpost\fP to an 1 value, it will automatically set
533
544
\fBnobody\fP to 0.
534
545
 
535
546
NOTE: if you have issued a POST request and want to make a HEAD or GET instead, you must
686
697
Set multiple cookies in one string like this: "name1=content1; name2=content2;"
687
698
etc.
688
699
 
 
700
Note that this option sets the cookie header explictly in the outgoing request(s).
 
701
If multiple requests are done due to authentication, followed redirections or similar,
 
702
they will all get this cookie passed on.
 
703
 
689
704
Using this option multiple times will only make the latest string override
690
705
the previous ones.
691
706
 
718
733
 
719
734
.TP
720
735
.B -cookiesession
721
 
Pass a non-zero number  to mark this as a new cookie "session". It will
 
736
Pass an 1 to mark this as a new cookie "session". It will
722
737
force TclCurl to ignore all cookies it is about to load that are "session
723
738
cookies" from the previous session. By default, TclCurl always stores and
724
739
loads all cookies, independent of whether they are session cookies are not.
735
750
 
736
751
.TP
737
752
.B -httpget
738
 
If set to non-zero forces the HTTP request to get back to GET, usable if
 
753
If set to 1 forces the HTTP request to get back to GET, usable if
739
754
POST, PUT or a custom request have been used previously with the
740
755
same handle.
741
756
 
742
 
When setting \fBhttpget\fP to a non-zero value, \fBnobody\fP will
743
 
automatically be set to 0.
 
757
When setting \fBhttpget\fP to 1, \fBnobody\fP will automatically be set to 0.
744
758
 
745
759
.TP
746
760
.B -httpversion
815
829
 
816
830
.TP
817
831
.B -dirlistonly
818
 
A non-zero parameter tells the library to just list the names of files in a
 
832
A 1 tells the library to just list the names of files in a
819
833
directory, instead of doing a full directory listing that would include file
820
834
sizes, dates etc. It works with both FTP and SFTP urls.
821
835
 
825
839
 
826
840
.TP
827
841
.B -append
828
 
A non-zero parameter tells the extension to append to the remote file instead of
 
842
A 1 parameter tells the extension to append to the remote file instead of
829
843
overwriting it. This is only useful when uploading to a ftp site.
830
844
 
831
845
.TP
832
846
.B -ftpuseeprt
833
 
Set to non-zero, to tell TclCurl to use the EPRT (and LPRT) command when doing
 
847
Set to 1 to tell TclCurl to use the EPRT (and LPRT) command when doing
834
848
active FTP downloads (which is enabled by '\fBftpport\fP'). Using EPRT means
835
849
that it will first attempt to use EPRT and then LPRT before using PORT, if
836
850
you pass zero to this option, it will not try using EPRT or LPRT, only plain PORT.
844
858
 
845
859
.TP
846
860
.B -ftpcreatemissingdirs
847
 
If set to non-zero, TclCurl will attempt to create any remote directory that it
 
861
If set to 1, TclCurl will attempt to create any remote directory that it
848
862
fails to CWD into. CWD is the command that changes working directory.
849
863
 
850
864
This setting also applies to SFTP-connections. TclCurl will attempt to create
869
883
 
870
884
.TP
871
885
.B -ftpskippasvip
872
 
If set to a non-zero value, it instructs TclCurl not to use the IP address the
 
886
If set to 1, it instructs TclCurl not to use the IP address the
873
887
server suggests in its 227-response to TclCurl's PASV command when TclCurl
874
888
connects the data connection. Instead TclCurl will re-use the same IP address
875
889
it already uses for the control connection. But it will use the port number
971
985
 
972
986
.TP
973
987
.B -transfertext
974
 
A non-zero parameter tells the extension to use ASCII mode for ftp transfers,
 
988
A 1 tells the extension to use ASCII mode for ftp transfers,
975
989
instead of the default binary transfer. For win32 systems it does not set the
976
990
stdout to binary mode. This option can be usable when transferring text data
977
991
between systems with different views on certain characters, such as newlines
983
997
transfer.
984
998
 
985
999
.TP
 
1000
.B -proxytransfermode
 
1001
If set to 1, TclCurl sets the transfer mode (binary or ASCII) for FTP transfers
 
1002
done via an HTTP proxy, by appending ;type=a or ;type=i to the URL.
 
1003
Without this setting, or it being set to 0, the default, \fB-transfertext\fP has
 
1004
no effect when doing FTP via a proxy. Beware that not all proxies support this feature.
 
1005
 
 
1006
.TP
986
1007
.B -crlf
987
1008
Convert unix newlines to CRLF newlines on FTP transfers.
988
1009
 
995
1016
transfers also support several intervals, separated with commas as in
996
1017
.I "X-Y,N-M"
997
1018
Using this kind of multiple intervals will cause the HTTP server to send the
998
 
response document in pieces.
 
1019
response document in pieces (using standard MIME separation techniques).
 
1020
 
 
1021
Ranges only work on HTTP, FTP and FILE transfers.
999
1022
 
1000
1023
.TP
1001
1024
.B -resumefrom
1020
1043
 
1021
1044
.TP
1022
1045
.B -filetime
1023
 
If you pass a non-zero value, TclCurl will attempt to get the
 
1046
If you pass a 1, TclCurl will attempt to get the
1024
1047
modification date of the remote document in this operation. This requires that
1025
1048
the remote server sends the time or replies to a time querying command. The
1026
1049
getinfo procedure with the
1029
1052
 
1030
1053
.TP
1031
1054
.B -nobody
1032
 
A non-zero parameter tells the library not to include the body-part in the
 
1055
A 1 tells the library not to include the body-part in the
1033
1056
output. This is only relevant for protocols that have a separate header and
1034
1057
body part. On HTTP(S) servers, this will make TclCurl do a HEAD request.
1035
1058
 
1045
1068
 
1046
1069
.TP
1047
1070
.B -upload
1048
 
A non-zero parameter tells the library to prepare for an upload. The
 
1071
A 1 tells the library to prepare for an upload. The
1049
1072
\fB-infile\fP and \fB-infilesize\fP options are also interesting for uploads.
1050
1073
If the protocol is HTTP, uploading means using the PUT request unless you tell
1051
1074
TclCurl otherwise.
1226
1249
 
1227
1250
.TP
1228
1251
.B -sslenginedefault
1229
 
Sets the actual crypto engine as the default for (asymmetric) crypto operations.
 
1252
Pass a 1 to set the actual crypto engine as the default for (asymmetric) crypto operations.
1230
1253
 
1231
1254
\fBNOTE:\fPIf the crypto device cannot be set, an error will be returned.
1232
1255
 
1236
1259
.RS
1237
1260
.TP 5
1238
1261
.B default
1239
 
The default action. When libcurl built with OpenSSL or NSS, this will attempt
1240
 
to figure out the remote SSL protocol version. Unfortunately there are a lot
1241
 
of ancient and broken servers in use which cannot handle this technique and
1242
 
will fail to connect. When libcurl is built with GnuTLS, this will mean SSLv3. 
 
1262
The default action. This will attempt to figure out the remote SSL protocol version,
 
1263
i.e. either SSLv3 or TLSv1 (but not SSLv2, which became disabled by default with 7.18.1). 
1243
1264
.TP
1244
1265
.B tlsv1
1245
1266
Force TLSv1
1254
1275
.TP
1255
1276
.B -sslverifypeer
1256
1277
This option determines whether TclCurl verifies the authenticity of the peer's certificate.
1257
 
A nonzero value means it verifies; zero means it doesn't. The default is nonzero. 
 
1278
A 1 means it verifies; zero means it doesn't. The default is 1. 
1258
1279
 
1259
1280
When negotiating an SSL connection, the server sends a certificate indicating its identity.
1260
1281
TclCurl verifies whether the certificate is authentic, i.e. that you can trust that the
1281
1302
resides in.
1282
1303
 
1283
1304
.TP
 
1305
.B -issuercert
 
1306
Pass a string naming a file holding a CA certificate in PEM format. If the option
 
1307
is set, an additional check against the peer certificate is performed to verify
 
1308
the issuer is indeed the one associated with the certificate provided by the option.
 
1309
This additional check is useful in multi-level PKI where one need to enforce the peer
 
1310
certificate is from a specific branch of the tree.
 
1311
 
 
1312
This option makes sense only when used in combination with the \fB-sslverifypeer\fP
 
1313
option. Otherwise, the result of the check is not considered as failure.
 
1314
 
 
1315
.TP
1284
1316
.B -capath
1285
1317
Pass the directory holding multiple CA certificates to verify the peer with.
1286
1318
The certificate directory must be prepared using the openssl c_rehash utility.
1293
1325
This option is OpenSSL-specific and does nothing if libcurl is built to use GnuTLS.
1294
1326
 
1295
1327
.TP
 
1328
.B -crlfile
 
1329
Pass a string naming a file with the concatenation of CRL (in PEM format) to use in
 
1330
the certificate validation that occurs during the SSL exchange.
 
1331
 
 
1332
When libcurl is built to use NSS or GnuTLS, there is no way to influence the use of
 
1333
CRL passed to help in the verification process. When built with OpenSSL support,
 
1334
X509_V_FLAG_CRL_CHECK and X509_V_FLAG_CRL_CHECK_ALL are both set, requiring CRL
 
1335
check against all the elements of the certificate chain if a CRL file is passed.
 
1336
 
 
1337
This option makes sense only when used in combination with the \fB-sslverifypeer\fP
 
1338
option. 
 
1339
 
 
1340
.TP
1296
1341
.B -randomfile
1297
1342
Pass a file name. The file will be used to read from to seed the random engine
1298
1343
for SSL. The more random the specified file is, the more secure will the SSL
1644
1689
Error from the SSH layer
1645
1690
.IP 80
1646
1691
Failed to shut down the SSL connection
 
1692
.IP 82
 
1693
Failed to load CRL file
 
1694
.IP 83
 
1695
Issuer check failed
1647
1696
 
1648
1697
.SH curlHandle getinfo option
1649
1698
Request internal information from the curl session with this procedure.
1690
1739
remote host (or proxy) was completed.
1691
1740
 
1692
1741
.TP
 
1742
.B appconnecttime
 
1743
Returns the time, in seconds, it took from the start until the SSL/SSH
 
1744
connect/handshake to the remote host was completed. This time is most often very
 
1745
near to the PRETRANSFER time, except for cases such as HTTP pippelining where the
 
1746
pretransfer time can be delayed due to waits in line for the pipeline and more.
 
1747
 
 
1748
.TP
1693
1749
.B pretransfertime
1694
1750
Returns the time, in seconds, it took from the start until the file transfer
1695
1751
is just about to begin. This includes all pre-transfer commands and
1707
1763
including name resolving, TCP connect etc.
1708
1764
 
1709
1765
.TP
 
1766
.B redirecturl
 
1767
Returns the URL a redirect would take you to if you enable \fBfollowlocation\fP.
 
1768
This can come very handy if you think using the built-in libcurl redirect logic
 
1769
isn't good enough for you but you would still prefer to avoid implementing all
 
1770
the magic of figuring out the new URL.
 
1771
 
 
1772
.TP
1710
1773
.B redirecttime
1711
1774
Returns the total time, in seconds, it took for all redirection steps
1712
1775
including name lookup, connect, pretransfer and transfer before
1728
1791
connections to save time.
1729
1792
 
1730
1793
.TP
 
1794
.B primaryip
 
1795
Returns the IP address of the most recent connection done with this handle.
 
1796
This string may be IPv6 if that's enabled.
 
1797
 
 
1798
.TP
1731
1799
.B sizeupload
1732
1800
Returns the total amount of bytes that were uploaded.
1733
1801
 
1806
1874
TclCurl ended up in when logging on to the remote FTP server. Returns an empty
1807
1875
string if something is wrong.
1808
1876
 
1809
 
.SH curlHandle duphandle
1810
 
This procedure will return a new curl handle, a duplicate,
1811
 
using all the options previously set in the input curl handle.
1812
 
Both handles can subsequently be used independently and
1813
 
they must both be freed with
1814
 
.B cleanup.
1815
 
The new handle will not inherit any state information,
1816
 
connections, SSL sessions or cookies.
1817
 
.TP
1818
 
.B RETURN VALUE
1819
 
A new curl handle or an error message if the copy fails.
1820
 
 
1821
1877
.SH curlHandle cleanup
1822
1878
This procedure must be the last one to call for a curl session. It is the
1823
1879
opposite of the
1840
1896
It does not change the following information kept in the handle: live
1841
1897
connections, the Session ID cache, the DNS cache, the cookies and shares.
1842
1898
 
 
1899
.SH curlHandle duphandle
 
1900
This procedure will return a new curl handle, a duplicate,
 
1901
using all the options previously set in the input curl handle.
 
1902
Both handles can subsequently be used independently and
 
1903
they must both be freed with
 
1904
.B cleanup.
 
1905
The new handle will not inherit any state information,
 
1906
connections, SSL sessions or cookies.
 
1907
.TP
 
1908
.B RETURN VALUE
 
1909
A new curl handle or an error message if the copy fails.
 
1910
 
 
1911
.SH curlHandle pause
 
1912
You can use this command from within a progress callback procedure
 
1913
to pause the transfer.
 
1914
 
 
1915
.SH curlHandle resume
 
1916
Resumes a transfer paused with \fBcurlhandle pause\fP
 
1917
 
1843
1918
.SH curl::transfer
1844
1919
In case you do not want to use persistant connections you can use this
1845
1920
command, it takes the same arguments as the \fIcurlHandle\fP \fBconfigure\fP