src/tool_help.c

   1 /***************************************************************************
   2  *                                  _   _ ____  _
   3  *  Project                     ___| | | |  _ \| |
   4  *                             / __| | | | |_) | |
   5  *                            | (__| |_| |  _ <| |___
   6  *                             \___|\___/|_| \_\_____|
   7  *
   8  * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
   9  *
  10  * This software is licensed as described in the file COPYING, which
  11  * you should have received as part of this distribution. The terms
  12  * are also available at https://curl.haxx.se/docs/copyright.html.
  13  *
  14  * You may opt to use, copy, modify, merge, publish, distribute and/or sell
  15  * copies of the Software, and permit persons to whom the Software is
  16  * furnished to do so, under the terms of the COPYING file.
  17  *
  18  * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
  19  * KIND, either express or implied.
  20  *
  21  ***************************************************************************/
  22 #include "tool_setup.h"
  23
  24 #include "tool_panykey.h"
  25 #include "tool_help.h"
  26 #include "tool_libinfo.h"
  27 #include "tool_version.h"
  28
  29 #include "memdebug.h" /* keep this as LAST include */
  30
  31 #ifdef MSDOS
  32 #  define USE_WATT32
  33 #endif
  34
  35 /*
  36  * The help output is generated with the following command
  37  ---------------------------------------------------------
  38
  39   cd $srcroot/docs/cmdline-opts
  40   ./gen.pl listhelp
  41  */
  42
  43 struct helptxt {
  44   const char *opt;
  45   const char *desc;
  46 };
  47
  48 static const struct helptxt helptext[] = {
  49   {"    --abstract-unix-socket <path>",
  50    "Connect via abstract Unix domain socket"},
  51   {"    --anyauth",
  52    "Pick any authentication method"},
  53   {"-a, --append",
  54    "Append to target file when uploading"},
  55   {"    --basic",
  56    "Use HTTP Basic Authentication"},
  57   {"    --cacert <file>",
  58    "CA certificate to verify peer against"},
  59   {"    --capath <dir>",
  60    "CA directory to verify peer against"},
  61   {"-E, --cert <certificate[:password]>",
  62    "Client certificate file and password"},
  63   {"    --cert-status",
  64    "Verify the status of the server certificate"},
  65   {"    --cert-type <type>",
  66    "Certificate file type (DER/PEM/ENG)"},
  67   {"    --ciphers <list of ciphers>",
  68    "SSL ciphers to use"},
  69   {"    --compressed",
  70    "Request compressed response"},
  71   {"    --compressed-ssh",
  72    "Enable SSH compression"},
  73   {"-K, --config <file>",
  74    "Read config from a file"},
  75   {"    --connect-timeout <seconds>",
  76    "Maximum time allowed for connection"},
  77   {"    --connect-to <HOST1:PORT1:HOST2:PORT2>",
  78    "Connect to host"},
  79   {"-C, --continue-at <offset>",
  80    "Resumed transfer offset"},
  81   {"-b, --cookie <data>",
  82    "Send cookies from string/file"},
  83   {"-c, --cookie-jar <filename>",
  84    "Write cookies to <filename> after operation"},
  85   {"    --create-dirs",
  86    "Create necessary local directory hierarchy"},
  87   {"    --crlf",
  88    "Convert LF to CRLF in upload"},
  89   {"    --crlfile <file>",
  90    "Get a CRL list in PEM format from the given file"},
  91   {"-d, --data <data>",
  92    "HTTP POST data"},
  93   {"    --data-ascii <data>",
  94    "HTTP POST ASCII data"},
  95   {"    --data-binary <data>",
  96    "HTTP POST binary data"},
  97   {"    --data-raw <data>",
  98    "HTTP POST data, '@' allowed"},
  99   {"    --data-urlencode <data>",
 100    "HTTP POST data url encoded"},
 101   {"    --delegation <LEVEL>",
 102    "GSS-API delegation permission"},
 103   {"    --digest",
 104    "Use HTTP Digest Authentication"},
 105   {"-q, --disable",
 106    "Disable .curlrc"},
 107   {"    --disable-eprt",
 108    "Inhibit using EPRT or LPRT"},
 109   {"    --disable-epsv",
 110    "Inhibit using EPSV"},
 111   {"    --dns-interface <interface>",
 112    "Interface to use for DNS requests"},
 113   {"    --dns-ipv4-addr <address>",
 114    "IPv4 address to use for DNS requests"},
 115   {"    --dns-ipv6-addr <address>",
 116    "IPv6 address to use for DNS requests"},
 117   {"    --dns-servers <addresses>",
 118    "DNS server addrs to use"},
 119   {"-D, --dump-header <filename>",
 120    "Write the received headers to <filename>"},
 121   {"    --egd-file <file>",
 122    "EGD socket path for random data"},
 123   {"    --engine <name>",
 124    "Crypto engine to use"},
 125   {"    --expect100-timeout <seconds>",
 126    "How long to wait for 100-continue"},
 127   {"-f, --fail",
 128    "Fail silently (no output at all) on HTTP errors"},
 129   {"    --fail-early",
 130    "Fail on first transfer error, do not continue"},
 131   {"    --false-start",
 132    "Enable TLS False Start"},
 133   {"-F, --form <name=content>",
 134    "Specify multipart MIME data"},
 135   {"    --form-string <name=string>",
 136    "Specify multipart MIME data"},
 137   {"    --ftp-account <data>",
 138    "Account data string"},
 139   {"    --ftp-alternative-to-user <command>",
 140    "String to replace USER [name]"},
 141   {"    --ftp-create-dirs",
 142    "Create the remote dirs if not present"},
 143   {"    --ftp-method <method>",
 144    "Control CWD usage"},
 145   {"    --ftp-pasv",
 146    "Use PASV/EPSV instead of PORT"},
 147   {"-P, --ftp-port <address>",
 148    "Use PORT instead of PASV"},
 149   {"    --ftp-pret",
 150    "Send PRET before PASV"},
 151   {"    --ftp-skip-pasv-ip",
 152    "Skip the IP address for PASV"},
 153   {"    --ftp-ssl-ccc",
 154    "Send CCC after authenticating"},
 155   {"    --ftp-ssl-ccc-mode <active/passive>",
 156    "Set CCC mode"},
 157   {"    --ftp-ssl-control",
 158    "Require SSL/TLS for FTP login, clear for transfer"},
 159   {"-G, --get",
 160    "Put the post data in the URL and use GET"},
 161   {"-g, --globoff",
 162    "Disable URL sequences and ranges using {} and []"},
 163   {"-I, --head",
 164    "Show document info only"},
 165   {"-H, --header <header/@file>",
 166    "Pass custom header(s) to server"},
 167   {"-h, --help",
 168    "This help text"},
 169   {"    --hostpubmd5 <md5>",
 170    "Acceptable MD5 hash of the host public key"},
 171   {"-0, --http1.0",
 172    "Use HTTP 1.0"},
 173   {"    --http1.1",
 174    "Use HTTP 1.1"},
 175   {"    --http2",
 176    "Use HTTP 2"},
 177   {"    --http2-prior-knowledge",
 178    "Use HTTP 2 without HTTP/1.1 Upgrade"},
 179   {"    --ignore-content-length",
 180    "Ignore the size of the remote resource"},
 181   {"-i, --include",
 182    "Include protocol response headers in the output"},
 183   {"-k, --insecure",
 184    "Allow insecure server connections when using SSL"},
 185   {"    --interface <name>",
 186    "Use network INTERFACE (or address)"},
 187   {"-4, --ipv4",
 188    "Resolve names to IPv4 addresses"},
 189   {"-6, --ipv6",
 190    "Resolve names to IPv6 addresses"},
 191   {"-j, --junk-session-cookies",
 192    "Ignore session cookies read from file"},
 193   {"    --keepalive-time <seconds>",
 194    "Interval time for keepalive probes"},
 195   {"    --key <key>",
 196    "Private key file name"},
 197   {"    --key-type <type>",
 198    "Private key file type (DER/PEM/ENG)"},
 199   {"    --krb <level>",
 200    "Enable Kerberos with security <level>"},
 201   {"    --libcurl <file>",
 202    "Dump libcurl equivalent code of this command line"},
 203   {"    --limit-rate <speed>",
 204    "Limit transfer speed to RATE"},
 205   {"-l, --list-only",
 206    "List only mode"},
 207   {"    --local-port <num/range>",
 208    "Force use of RANGE for local port numbers"},
 209   {"-L, --location",
 210    "Follow redirects"},
 211   {"    --location-trusted",
 212    "Like --location, and send auth to other hosts"},
 213   {"    --login-options <options>",
 214    "Server login options"},
 215   {"    --mail-auth <address>",
 216    "Originator address of the original email"},
 217   {"    --mail-from <address>",
 218    "Mail from this address"},
 219   {"    --mail-rcpt <address>",
 220    "Mail from this address"},
 221   {"-M, --manual",
 222    "Display the full manual"},
 223   {"    --max-filesize <bytes>",
 224    "Maximum file size to download"},
 225   {"    --max-redirs <num>",
 226    "Maximum number of redirects allowed"},
 227   {"-m, --max-time <time>",
 228    "Maximum time allowed for the transfer"},
 229   {"    --metalink",
 230    "Process given URLs as metalink XML file"},
 231   {"    --negotiate",
 232    "Use HTTP Negotiate (SPNEGO) authentication"},
 233   {"-n, --netrc",
 234    "Must read .netrc for user name and password"},
 235   {"    --netrc-file <filename>",
 236    "Specify FILE for netrc"},
 237   {"    --netrc-optional",
 238    "Use either .netrc or URL"},
 239   {"-:, --next",
 240    "Make next URL use its separate set of options"},
 241   {"    --no-alpn",
 242    "Disable the ALPN TLS extension"},
 243   {"-N, --no-buffer",
 244    "Disable buffering of the output stream"},
 245   {"    --no-keepalive",
 246    "Disable TCP keepalive on the connection"},
 247   {"    --no-npn",
 248    "Disable the NPN TLS extension"},
 249   {"    --no-sessionid",
 250    "Disable SSL session-ID reusing"},
 251   {"    --noproxy <no-proxy-list>",
 252    "List of hosts which do not use proxy"},
 253   {"    --ntlm",
 254    "Use HTTP NTLM authentication"},
 255   {"    --ntlm-wb",
 256    "Use HTTP NTLM authentication with winbind"},
 257   {"    --oauth2-bearer <token>",
 258    "OAuth 2 Bearer Token"},
 259   {"-o, --output <file>",
 260    "Write to file instead of stdout"},
 261   {"    --pass <phrase>",
 262    "Pass phrase for the private key"},
 263   {"    --path-as-is",
 264    "Do not squash .. sequences in URL path"},
 265   {"    --pinnedpubkey <hashes>",
 266    "FILE/HASHES Public key to verify peer against"},
 267   {"    --post301",
 268    "Do not switch to GET after following a 301"},
 269   {"    --post302",
 270    "Do not switch to GET after following a 302"},
 271   {"    --post303",
 272    "Do not switch to GET after following a 303"},
 273   {"    --preproxy [protocol://]host[:port]",
 274    "Use this proxy first"},
 275   {"-#, --progress-bar",
 276    "Display transfer progress as a bar"},
 277   {"    --proto <protocols>",
 278    "Enable/disable PROTOCOLS"},
 279   {"    --proto-default <protocol>",
 280    "Use PROTOCOL for any URL missing a scheme"},
 281   {"    --proto-redir <protocols>",
 282    "Enable/disable PROTOCOLS on redirect"},
 283   {"-x, --proxy [protocol://]host[:port]",
 284    "Use this proxy"},
 285   {"    --proxy-anyauth",
 286    "Pick any proxy authentication method"},
 287   {"    --proxy-basic",
 288    "Use Basic authentication on the proxy"},
 289   {"    --proxy-cacert <file>",
 290    "CA certificate to verify peer against for proxy"},
 291   {"    --proxy-capath <dir>",
 292    "CA directory to verify peer against for proxy"},
 293   {"    --proxy-cert <cert[:passwd]>",
 294    "Set client certificate for proxy"},
 295   {"    --proxy-cert-type <type>",
 296    "Client certificate type for HTTS proxy"},
 297   {"    --proxy-ciphers <list>",
 298    "SSL ciphers to use for proxy"},
 299   {"    --proxy-crlfile <file>",
 300    "Set a CRL list for proxy"},
 301   {"    --proxy-digest",
 302    "Use Digest authentication on the proxy"},
 303   {"    --proxy-header <header/@file>",
 304    "Pass custom header(s) to proxy"},
 305   {"    --proxy-insecure",
 306    "Do HTTPS proxy connections without verifying the proxy"},
 307   {"    --proxy-key <key>",
 308    "Private key for HTTPS proxy"},
 309   {"    --proxy-key-type <type>",
 310    "Private key file type for proxy"},
 311   {"    --proxy-negotiate",
 312    "Use HTTP Negotiate (SPNEGO) authentication on the proxy"},
 313   {"    --proxy-ntlm",
 314    "Use NTLM authentication on the proxy"},
 315   {"    --proxy-pass <phrase>",
 316    "Pass phrase for the private key for HTTPS proxy"},
 317   {"    --proxy-service-name <name>",
 318    "SPNEGO proxy service name"},
 319   {"    --proxy-ssl-allow-beast",
 320    "Allow security flaw for interop for HTTPS proxy"},
 321   {"    --proxy-tlsauthtype <type>",
 322    "TLS authentication type for HTTPS proxy"},
 323   {"    --proxy-tlspassword <string>",
 324    "TLS password for HTTPS proxy"},
 325   {"    --proxy-tlsuser <name>",
 326    "TLS username for HTTPS proxy"},
 327   {"    --proxy-tlsv1",
 328    "Use TLSv1 for HTTPS proxy"},
 329   {"-U, --proxy-user <user:password>",
 330    "Proxy user and password"},
 331   {"    --proxy1.0 <host[:port]>",
 332    "Use HTTP/1.0 proxy on given port"},
 333   {"-p, --proxytunnel",
 334    "Operate through a HTTP proxy tunnel (using CONNECT)"},
 335   {"    --pubkey <key>",
 336    "SSH Public key file name"},
 337   {"-Q, --quote",
 338    "Send command(s) to server before transfer"},
 339   {"    --random-file <file>",
 340    "File for reading random data from"},
 341   {"-r, --range <range>",
 342    "Retrieve only the bytes within RANGE"},
 343   {"    --raw",
 344    "Do HTTP \"raw\"; no transfer decoding"},
 345   {"-e, --referer <URL>",
 346    "Referrer URL"},
 347   {"-J, --remote-header-name",
 348    "Use the header-provided filename"},
 349   {"-O, --remote-name",
 350    "Write output to a file named as the remote file"},
 351   {"    --remote-name-all",
 352    "Use the remote file name for all URLs"},
 353   {"-R, --remote-time",
 354    "Set the remote file's time on the local output"},
 355   {"-X, --request <command>",
 356    "Specify request command to use"},
 357   {"    --request-target",
 358    "Specify the target for this request"},
 359   {"    --resolve <host:port:address>",
 360    "Resolve the host+port to this address"},
 361   {"    --retry <num>",
 362    "Retry request if transient problems occur"},
 363   {"    --retry-connrefused",
 364    "Retry on connection refused (use with --retry)"},
 365   {"    --retry-delay <seconds>",
 366    "Wait time between retries"},
 367   {"    --retry-max-time <seconds>",
 368    "Retry only within this period"},
 369   {"    --sasl-ir",
 370    "Enable initial response in SASL authentication"},
 371   {"    --service-name <name>",
 372    "SPNEGO service name"},
 373   {"-S, --show-error",
 374    "Show error even when -s is used"},
 375   {"-s, --silent",
 376    "Silent mode"},
 377   {"    --socks4 <host[:port]>",
 378    "SOCKS4 proxy on given host + port"},
 379   {"    --socks4a <host[:port]>",
 380    "SOCKS4a proxy on given host + port"},
 381   {"    --socks5 <host[:port]>",
 382    "SOCKS5 proxy on given host + port"},
 383   {"    --socks5-basic",
 384    "Enable username/password auth for SOCKS5 proxies"},
 385   {"    --socks5-gssapi",
 386    "Enable GSS-API auth for SOCKS5 proxies"},
 387   {"    --socks5-gssapi-nec",
 388    "Compatibility with NEC SOCKS5 server"},
 389   {"    --socks5-gssapi-service <name>",
 390    "SOCKS5 proxy service name for GSS-API"},
 391   {"    --socks5-hostname <host[:port]>",
 392    "SOCKS5 proxy, pass host name to proxy"},
 393   {"-Y, --speed-limit <speed>",
 394    "Stop transfers slower than this"},
 395   {"-y, --speed-time <seconds>",
 396    "Trigger 'speed-limit' abort after this time"},
 397   {"    --ssl",
 398    "Try SSL/TLS"},
 399   {"    --ssl-allow-beast",
 400    "Allow security flaw to improve interop"},
 401   {"    --ssl-no-revoke",
 402    "Disable cert revocation checks (WinSSL)"},
 403   {"    --ssl-reqd",
 404    "Require SSL/TLS"},
 405   {"-2, --sslv2",
 406    "Use SSLv2"},
 407   {"-3, --sslv3",
 408    "Use SSLv3"},
 409   {"    --stderr",
 410    "Where to redirect stderr"},
 411   {"    --suppress-connect-headers",
 412    "Suppress proxy CONNECT response headers"},
 413   {"    --tcp-fastopen",
 414    "Use TCP Fast Open"},
 415   {"    --tcp-nodelay",
 416    "Use the TCP_NODELAY option"},
 417   {"-t, --telnet-option <opt=val>",
 418    "Set telnet option"},
 419   {"    --tftp-blksize <value>",
 420    "Set TFTP BLKSIZE option"},
 421   {"    --tftp-no-options",
 422    "Do not send any TFTP options"},
 423   {"-z, --time-cond <time>",
 424    "Transfer based on a time condition"},
 425   {"    --tls-max <VERSION>",
 426    "Use TLSv1.0 or greater"},
 427   {"    --tlsauthtype <type>",
 428    "TLS authentication type"},
 429   {"    --tlspassword",
 430    "TLS password"},
 431   {"    --tlsuser <name>",
 432    "TLS user name"},
 433   {"-1, --tlsv1",
 434    "Use TLSv1.0 or greater"},
 435   {"    --tlsv1.0",
 436    "Use TLSv1.0"},
 437   {"    --tlsv1.1",
 438    "Use TLSv1.1"},
 439   {"    --tlsv1.2",
 440    "Use TLSv1.2"},
 441   {"    --tlsv1.3",
 442    "Use TLSv1.3"},
 443   {"    --tr-encoding",
 444    "Request compressed transfer encoding"},
 445   {"    --trace <file>",
 446    "Write a debug trace to FILE"},
 447   {"    --trace-ascii <file>",
 448    "Like --trace, but without hex output"},
 449   {"    --trace-time",
 450    "Add time stamps to trace/verbose output"},
 451   {"    --unix-socket <path>",
 452    "Connect through this Unix domain socket"},
 453   {"-T, --upload-file <file>",
 454    "Transfer local FILE to destination"},
 455   {"    --url <url>",
 456    "URL to work with"},
 457   {"-B, --use-ascii",
 458    "Use ASCII/text transfer"},
 459   {"-u, --user <user:password>",
 460    "Server user and password"},
 461   {"-A, --user-agent <name>",
 462    "Send User-Agent <name> to server"},
 463   {"-v, --verbose",
 464    "Make the operation more talkative"},
 465   {"-V, --version",
 466    "Show version number and quit"},
 467   {"-w, --write-out <format>",
 468    "Use output FORMAT after completion"},
 469   {"    --xattr",
 470    "Store metadata in extended file attributes"},
 471   { NULL, NULL }
 472 };
 473
 474 #ifdef NETWARE
 475 #  define PRINT_LINES_PAUSE 23
 476 #endif
 477
 478 #ifdef __SYMBIAN32__
 479 #  define PRINT_LINES_PAUSE 16
 480 #endif
 481
 482 struct feat {
 483   const char *name;
 484   int bitmask;
 485 };
 486
 487 static const struct feat feats[] = {
 488   {"AsynchDNS",      CURL_VERSION_ASYNCHDNS},
 489   {"Debug",          CURL_VERSION_DEBUG},
 490   {"TrackMemory",    CURL_VERSION_CURLDEBUG},
 491   {"IDN",            CURL_VERSION_IDN},
 492   {"IPv6",           CURL_VERSION_IPV6},
 493   {"Largefile",      CURL_VERSION_LARGEFILE},
 494   {"SSPI",           CURL_VERSION_SSPI},
 495   {"GSS-API",        CURL_VERSION_GSSAPI},
 496   {"Kerberos",       CURL_VERSION_KERBEROS5},
 497   {"SPNEGO",         CURL_VERSION_SPNEGO},
 498   {"NTLM",           CURL_VERSION_NTLM},
 499   {"NTLM_WB",        CURL_VERSION_NTLM_WB},
 500   {"SSL",            CURL_VERSION_SSL},
 501   {"libz",           CURL_VERSION_LIBZ},
 502   {"CharConv",       CURL_VERSION_CONV},
 503   {"TLS-SRP",        CURL_VERSION_TLSAUTH_SRP},
 504   {"HTTP2",          CURL_VERSION_HTTP2},
 505   {"UnixSockets",    CURL_VERSION_UNIX_SOCKETS},
 506   {"HTTPS-proxy",    CURL_VERSION_HTTPS_PROXY},
 507   {"MultiSSL",       CURL_VERSION_MULTI_SSL}
 508 };
 509
 510 void tool_help(void)
 511 {
 512   int i;
 513   puts("Usage: curl [options...] <url>");
 514   for(i = 0; helptext[i].opt; i++) {
 515     printf(" %-19s %s\n", helptext[i].opt, helptext[i].desc);
 516 #ifdef PRINT_LINES_PAUSE
 517     if(i && ((i % PRINT_LINES_PAUSE) == 0))
 518       tool_pressanykey();
 519 #endif
 520   }
 521 }
 522
 523 void tool_version_info(void)
 524 {
 525   const char *const *proto;
 526
 527   printf(CURL_ID "%s\n", curl_version());
 528 #ifdef CURL_PATCHSTAMP
 529   printf("Release-Date: %s, security patched: %s\n",
 530          LIBCURL_TIMESTAMP, CURL_PATCHSTAMP);
 531 #else
 532   printf("Release-Date: %s\n", LIBCURL_TIMESTAMP);
 533 #endif
 534   if(curlinfo->protocols) {
 535     printf("Protocols: ");
 536     for(proto = curlinfo->protocols; *proto; ++proto) {
 537       printf("%s ", *proto);
 538     }
 539     puts(""); /* newline */
 540   }
 541   if(curlinfo->features) {
 542     unsigned int i;
 543     printf("Features: ");
 544     for(i = 0; i < sizeof(feats)/sizeof(feats[0]); i++) {
 545       if(curlinfo->features & feats[i].bitmask)
 546         printf("%s ", feats[i].name);
 547     }
 548 #ifdef USE_METALINK
 549     printf("Metalink ");
 550 #endif
 551 #ifdef USE_LIBPSL
 552     printf("PSL ");
 553 #endif
 554     puts(""); /* newline */
 555   }
 556 }
 557
 558 void tool_list_engines(CURL *curl)
 559 {
 560   struct curl_slist *engines = NULL;
 561
 562   /* Get the list of engines */
 563   curl_easy_getinfo(curl, CURLINFO_SSL_ENGINES, &engines);
 564
 565   puts("Build-time engines:");
 566   if(engines) {
 567     for(; engines; engines = engines->next)
 568       printf("  %s\n", engines->data);
 569   }
 570   else {
 571     puts("  <none>");
 572   }
 573
 574   /* Cleanup the list of engines */
 575   curl_slist_free_all(engines);
 576 }