src/tool_help.c

   1 /***************************************************************************
   2  *                                  _   _ ____  _
   3  *  Project                     ___| | | |  _ \| |
   4  *                             / __| | | | |_) | |
   5  *                            | (__| |_| |  _ <| |___
   6  *                             \___|\___/|_| \_\_____|
   7  *
   8  * Copyright (C) 1998 - 2018, 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   {"    --happy-eyeballs-timeout-ms",
 164    "How long to wait in milliseconds for IPv6 before trying IPv4"},
 165   {"-I, --head",
 166    "Show document info only"},
 167   {"-H, --header <header/@file>",
 168    "Pass custom header(s) to server"},
 169   {"-h, --help",
 170    "This help text"},
 171   {"    --hostpubmd5 <md5>",
 172    "Acceptable MD5 hash of the host public key"},
 173   {"-0, --http1.0",
 174    "Use HTTP 1.0"},
 175   {"    --http1.1",
 176    "Use HTTP 1.1"},
 177   {"    --http2",
 178    "Use HTTP 2"},
 179   {"    --http2-prior-knowledge",
 180    "Use HTTP 2 without HTTP/1.1 Upgrade"},
 181   {"    --ignore-content-length",
 182    "Ignore the size of the remote resource"},
 183   {"-i, --include",
 184    "Include protocol response headers in the output"},
 185   {"-k, --insecure",
 186    "Allow insecure server connections when using SSL"},
 187   {"    --interface <name>",
 188    "Use network INTERFACE (or address)"},
 189   {"-4, --ipv4",
 190    "Resolve names to IPv4 addresses"},
 191   {"-6, --ipv6",
 192    "Resolve names to IPv6 addresses"},
 193   {"-j, --junk-session-cookies",
 194    "Ignore session cookies read from file"},
 195   {"    --keepalive-time <seconds>",
 196    "Interval time for keepalive probes"},
 197   {"    --key <key>",
 198    "Private key file name"},
 199   {"    --key-type <type>",
 200    "Private key file type (DER/PEM/ENG)"},
 201   {"    --krb <level>",
 202    "Enable Kerberos with security <level>"},
 203   {"    --libcurl <file>",
 204    "Dump libcurl equivalent code of this command line"},
 205   {"    --limit-rate <speed>",
 206    "Limit transfer speed to RATE"},
 207   {"-l, --list-only",
 208    "List only mode"},
 209   {"    --local-port <num/range>",
 210    "Force use of RANGE for local port numbers"},
 211   {"-L, --location",
 212    "Follow redirects"},
 213   {"    --location-trusted",
 214    "Like --location, and send auth to other hosts"},
 215   {"    --login-options <options>",
 216    "Server login options"},
 217   {"    --mail-auth <address>",
 218    "Originator address of the original email"},
 219   {"    --mail-from <address>",
 220    "Mail from this address"},
 221   {"    --mail-rcpt <address>",
 222    "Mail to this address"},
 223   {"-M, --manual",
 224    "Display the full manual"},
 225   {"    --max-filesize <bytes>",
 226    "Maximum file size to download"},
 227   {"    --max-redirs <num>",
 228    "Maximum number of redirects allowed"},
 229   {"-m, --max-time <time>",
 230    "Maximum time allowed for the transfer"},
 231   {"    --metalink",
 232    "Process given URLs as metalink XML file"},
 233   {"    --negotiate",
 234    "Use HTTP Negotiate (SPNEGO) authentication"},
 235   {"-n, --netrc",
 236    "Must read .netrc for user name and password"},
 237   {"    --netrc-file <filename>",
 238    "Specify FILE for netrc"},
 239   {"    --netrc-optional",
 240    "Use either .netrc or URL"},
 241   {"-:, --next",
 242    "Make next URL use its separate set of options"},
 243   {"    --no-alpn",
 244    "Disable the ALPN TLS extension"},
 245   {"-N, --no-buffer",
 246    "Disable buffering of the output stream"},
 247   {"    --no-keepalive",
 248    "Disable TCP keepalive on the connection"},
 249   {"    --no-npn",
 250    "Disable the NPN TLS extension"},
 251   {"    --no-sessionid",
 252    "Disable SSL session-ID reusing"},
 253   {"    --noproxy <no-proxy-list>",
 254    "List of hosts which do not use proxy"},
 255   {"    --ntlm",
 256    "Use HTTP NTLM authentication"},
 257   {"    --ntlm-wb",
 258    "Use HTTP NTLM authentication with winbind"},
 259   {"    --oauth2-bearer <token>",
 260    "OAuth 2 Bearer Token"},
 261   {"-o, --output <file>",
 262    "Write to file instead of stdout"},
 263   {"    --pass <phrase>",
 264    "Pass phrase for the private key"},
 265   {"    --path-as-is",
 266    "Do not squash .. sequences in URL path"},
 267   {"    --pinnedpubkey <hashes>",
 268    "FILE/HASHES Public key to verify peer against"},
 269   {"    --post301",
 270    "Do not switch to GET after following a 301"},
 271   {"    --post302",
 272    "Do not switch to GET after following a 302"},
 273   {"    --post303",
 274    "Do not switch to GET after following a 303"},
 275   {"    --preproxy [protocol://]host[:port]",
 276    "Use this proxy first"},
 277   {"-#, --progress-bar",
 278    "Display transfer progress as a bar"},
 279   {"    --proto <protocols>",
 280    "Enable/disable PROTOCOLS"},
 281   {"    --proto-default <protocol>",
 282    "Use PROTOCOL for any URL missing a scheme"},
 283   {"    --proto-redir <protocols>",
 284    "Enable/disable PROTOCOLS on redirect"},
 285   {"-x, --proxy [protocol://]host[:port]",
 286    "Use this proxy"},
 287   {"    --proxy-anyauth",
 288    "Pick any proxy authentication method"},
 289   {"    --proxy-basic",
 290    "Use Basic authentication on the proxy"},
 291   {"    --proxy-cacert <file>",
 292    "CA certificate to verify peer against for proxy"},
 293   {"    --proxy-capath <dir>",
 294    "CA directory to verify peer against for proxy"},
 295   {"    --proxy-cert <cert[:passwd]>",
 296    "Set client certificate for proxy"},
 297   {"    --proxy-cert-type <type>",
 298    "Client certificate type for HTTS proxy"},
 299   {"    --proxy-ciphers <list>",
 300    "SSL ciphers to use for proxy"},
 301   {"    --proxy-crlfile <file>",
 302    "Set a CRL list for proxy"},
 303   {"    --proxy-digest",
 304    "Use Digest authentication on the proxy"},
 305   {"    --proxy-header <header/@file>",
 306    "Pass custom header(s) to proxy"},
 307   {"    --proxy-insecure",
 308    "Do HTTPS proxy connections without verifying the proxy"},
 309   {"    --proxy-key <key>",
 310    "Private key for HTTPS proxy"},
 311   {"    --proxy-key-type <type>",
 312    "Private key file type for proxy"},
 313   {"    --proxy-negotiate",
 314    "Use HTTP Negotiate (SPNEGO) authentication on the proxy"},
 315   {"    --proxy-ntlm",
 316    "Use NTLM authentication on the proxy"},
 317   {"    --proxy-pass <phrase>",
 318    "Pass phrase for the private key for HTTPS proxy"},
 319   {"    --proxy-pinnedpubkey <hashes>",
 320    "FILE/HASHES public key to verify proxy with"},
 321   {"    --proxy-service-name <name>",
 322    "SPNEGO proxy service name"},
 323   {"    --proxy-ssl-allow-beast",
 324    "Allow security flaw for interop for HTTPS proxy"},
 325   {"    --proxy-tlsauthtype <type>",
 326    "TLS authentication type for HTTPS proxy"},
 327   {"    --proxy-tlspassword <string>",
 328    "TLS password for HTTPS proxy"},
 329   {"    --proxy-tlsuser <name>",
 330    "TLS username for HTTPS proxy"},
 331   {"    --proxy-tlsv1",
 332    "Use TLSv1 for HTTPS proxy"},
 333   {"-U, --proxy-user <user:password>",
 334    "Proxy user and password"},
 335   {"    --proxy1.0 <host[:port]>",
 336    "Use HTTP/1.0 proxy on given port"},
 337   {"-p, --proxytunnel",
 338    "Operate through a HTTP proxy tunnel (using CONNECT)"},
 339   {"    --pubkey <key>",
 340    "SSH Public key file name"},
 341   {"-Q, --quote",
 342    "Send command(s) to server before transfer"},
 343   {"    --random-file <file>",
 344    "File for reading random data from"},
 345   {"-r, --range <range>",
 346    "Retrieve only the bytes within RANGE"},
 347   {"    --raw",
 348    "Do HTTP \"raw\"; no transfer decoding"},
 349   {"-e, --referer <URL>",
 350    "Referrer URL"},
 351   {"-J, --remote-header-name",
 352    "Use the header-provided filename"},
 353   {"-O, --remote-name",
 354    "Write output to a file named as the remote file"},
 355   {"    --remote-name-all",
 356    "Use the remote file name for all URLs"},
 357   {"-R, --remote-time",
 358    "Set the remote file's time on the local output"},
 359   {"-X, --request <command>",
 360    "Specify request command to use"},
 361   {"    --request-target",
 362    "Specify the target for this request"},
 363   {"    --resolve <host:port:address>",
 364    "Resolve the host+port to this address"},
 365   {"    --retry <num>",
 366    "Retry request if transient problems occur"},
 367   {"    --retry-connrefused",
 368    "Retry on connection refused (use with --retry)"},
 369   {"    --retry-delay <seconds>",
 370    "Wait time between retries"},
 371   {"    --retry-max-time <seconds>",
 372    "Retry only within this period"},
 373   {"    --sasl-ir",
 374    "Enable initial response in SASL authentication"},
 375   {"    --service-name <name>",
 376    "SPNEGO service name"},
 377   {"-S, --show-error",
 378    "Show error even when -s is used"},
 379   {"-s, --silent",
 380    "Silent mode"},
 381   {"    --socks4 <host[:port]>",
 382    "SOCKS4 proxy on given host + port"},
 383   {"    --socks4a <host[:port]>",
 384    "SOCKS4a proxy on given host + port"},
 385   {"    --socks5 <host[:port]>",
 386    "SOCKS5 proxy on given host + port"},
 387   {"    --socks5-basic",
 388    "Enable username/password auth for SOCKS5 proxies"},
 389   {"    --socks5-gssapi",
 390    "Enable GSS-API auth for SOCKS5 proxies"},
 391   {"    --socks5-gssapi-nec",
 392    "Compatibility with NEC SOCKS5 server"},
 393   {"    --socks5-gssapi-service <name>",
 394    "SOCKS5 proxy service name for GSS-API"},
 395   {"    --socks5-hostname <host[:port]>",
 396    "SOCKS5 proxy, pass host name to proxy"},
 397   {"-Y, --speed-limit <speed>",
 398    "Stop transfers slower than this"},
 399   {"-y, --speed-time <seconds>",
 400    "Trigger 'speed-limit' abort after this time"},
 401   {"    --ssl",
 402    "Try SSL/TLS"},
 403   {"    --ssl-allow-beast",
 404    "Allow security flaw to improve interop"},
 405   {"    --ssl-no-revoke",
 406    "Disable cert revocation checks (WinSSL)"},
 407   {"    --ssl-reqd",
 408    "Require SSL/TLS"},
 409   {"-2, --sslv2",
 410    "Use SSLv2"},
 411   {"-3, --sslv3",
 412    "Use SSLv3"},
 413   {"    --stderr",
 414    "Where to redirect stderr"},
 415   {"    --suppress-connect-headers",
 416    "Suppress proxy CONNECT response headers"},
 417   {"    --tcp-fastopen",
 418    "Use TCP Fast Open"},
 419   {"    --tcp-nodelay",
 420    "Use the TCP_NODELAY option"},
 421   {"-t, --telnet-option <opt=val>",
 422    "Set telnet option"},
 423   {"    --tftp-blksize <value>",
 424    "Set TFTP BLKSIZE option"},
 425   {"    --tftp-no-options",
 426    "Do not send any TFTP options"},
 427   {"-z, --time-cond <time>",
 428    "Transfer based on a time condition"},
 429   {"    --tls-max <VERSION>",
 430    "Use TLSv1.0 or greater"},
 431   {"    --tlsauthtype <type>",
 432    "TLS authentication type"},
 433   {"    --tlspassword",
 434    "TLS password"},
 435   {"    --tlsuser <name>",
 436    "TLS user name"},
 437   {"-1, --tlsv1",
 438    "Use TLSv1.0 or greater"},
 439   {"    --tlsv1.0",
 440    "Use TLSv1.0"},
 441   {"    --tlsv1.1",
 442    "Use TLSv1.1"},
 443   {"    --tlsv1.2",
 444    "Use TLSv1.2"},
 445   {"    --tlsv1.3",
 446    "Use TLSv1.3"},
 447   {"    --tr-encoding",
 448    "Request compressed transfer encoding"},
 449   {"    --trace <file>",
 450    "Write a debug trace to FILE"},
 451   {"    --trace-ascii <file>",
 452    "Like --trace, but without hex output"},
 453   {"    --trace-time",
 454    "Add time stamps to trace/verbose output"},
 455   {"    --unix-socket <path>",
 456    "Connect through this Unix domain socket"},
 457   {"-T, --upload-file <file>",
 458    "Transfer local FILE to destination"},
 459   {"    --url <url>",
 460    "URL to work with"},
 461   {"-B, --use-ascii",
 462    "Use ASCII/text transfer"},
 463   {"-u, --user <user:password>",
 464    "Server user and password"},
 465   {"-A, --user-agent <name>",
 466    "Send User-Agent <name> to server"},
 467   {"-v, --verbose",
 468    "Make the operation more talkative"},
 469   {"-V, --version",
 470    "Show version number and quit"},
 471   {"-w, --write-out <format>",
 472    "Use output FORMAT after completion"},
 473   {"    --xattr",
 474    "Store metadata in extended file attributes"},
 475   { NULL, NULL }
 476 };
 477
 478 #ifdef NETWARE
 479 #  define PRINT_LINES_PAUSE 23
 480 #endif
 481
 482 #ifdef __SYMBIAN32__
 483 #  define PRINT_LINES_PAUSE 16
 484 #endif
 485
 486 struct feat {
 487   const char *name;
 488   int bitmask;
 489 };
 490
 491 static const struct feat feats[] = {
 492   {"AsynchDNS",      CURL_VERSION_ASYNCHDNS},
 493   {"Debug",          CURL_VERSION_DEBUG},
 494   {"TrackMemory",    CURL_VERSION_CURLDEBUG},
 495   {"IDN",            CURL_VERSION_IDN},
 496   {"IPv6",           CURL_VERSION_IPV6},
 497   {"Largefile",      CURL_VERSION_LARGEFILE},
 498   {"SSPI",           CURL_VERSION_SSPI},
 499   {"GSS-API",        CURL_VERSION_GSSAPI},
 500   {"Kerberos",       CURL_VERSION_KERBEROS5},
 501   {"SPNEGO",         CURL_VERSION_SPNEGO},
 502   {"NTLM",           CURL_VERSION_NTLM},
 503   {"NTLM_WB",        CURL_VERSION_NTLM_WB},
 504   {"SSL",            CURL_VERSION_SSL},
 505   {"libz",           CURL_VERSION_LIBZ},
 506   {"brotli",         CURL_VERSION_BROTLI},
 507   {"CharConv",       CURL_VERSION_CONV},
 508   {"TLS-SRP",        CURL_VERSION_TLSAUTH_SRP},
 509   {"HTTP2",          CURL_VERSION_HTTP2},
 510   {"UnixSockets",    CURL_VERSION_UNIX_SOCKETS},
 511   {"HTTPS-proxy",    CURL_VERSION_HTTPS_PROXY},
 512   {"MultiSSL",       CURL_VERSION_MULTI_SSL},
 513   {"PSL",            CURL_VERSION_PSL},
 514 };
 515
 516 void tool_help(void)
 517 {
 518   int i;
 519   puts("Usage: curl [options...] <url>");
 520   for(i = 0; helptext[i].opt; i++) {
 521     printf(" %-19s %s\n", helptext[i].opt, helptext[i].desc);
 522 #ifdef PRINT_LINES_PAUSE
 523     if(i && ((i % PRINT_LINES_PAUSE) == 0))
 524       tool_pressanykey();
 525 #endif
 526   }
 527 }
 528
 529 void tool_version_info(void)
 530 {
 531   const char *const *proto;
 532
 533   printf(CURL_ID "%s\n", curl_version());
 534 #ifdef CURL_PATCHSTAMP
 535   printf("Release-Date: %s, security patched: %s\n",
 536          LIBCURL_TIMESTAMP, CURL_PATCHSTAMP);
 537 #else
 538   printf("Release-Date: %s\n", LIBCURL_TIMESTAMP);
 539 #endif
 540   if(curlinfo->protocols) {
 541     printf("Protocols: ");
 542     for(proto = curlinfo->protocols; *proto; ++proto) {
 543       printf("%s ", *proto);
 544     }
 545     puts(""); /* newline */
 546   }
 547   if(curlinfo->features) {
 548     unsigned int i;
 549     printf("Features: ");
 550     for(i = 0; i < sizeof(feats)/sizeof(feats[0]); i++) {
 551       if(curlinfo->features & feats[i].bitmask)
 552         printf("%s ", feats[i].name);
 553     }
 554 #ifdef USE_METALINK
 555     printf("Metalink ");
 556 #endif
 557     puts(""); /* newline */
 558   }
 559 }
 560
 561 void tool_list_engines(CURL *curl)
 562 {
 563   struct curl_slist *engines = NULL;
 564
 565   /* Get the list of engines */
 566   curl_easy_getinfo(curl, CURLINFO_SSL_ENGINES, &engines);
 567
 568   puts("Build-time engines:");
 569   if(engines) {
 570     for(; engines; engines = engines->next)
 571       printf("  %s\n", engines->data);
 572   }
 573   else {
 574     puts("  <none>");
 575   }
 576
 577   /* Cleanup the list of engines */
 578   curl_slist_free_all(engines);
 579 }