Annotation of embedaddon/curl/docs/curl.1, revision 1.1
1.1 ! misho 1: .\" **************************************************************************
! 2: .\" * _ _ ____ _
! 3: .\" * Project ___| | | | _ \| |
! 4: .\" * / __| | | | |_) | |
! 5: .\" * | (__| |_| | _ <| |___
! 6: .\" * \___|\___/|_| \_\_____|
! 7: .\" *
! 8: .\" * Copyright (C) 1998 - 2020, 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: .\"
! 23: .\" DO NOT EDIT. Generated by the curl project gen.pl man page generator.
! 24: .\"
! 25: .TH curl 1 "November 16, 2016" "Curl 7.70.0" "Curl Manual"
! 26:
! 27: .SH NAME
! 28: curl \- transfer a URL
! 29: .SH SYNOPSIS
! 30: .B curl [options / URLs]
! 31: .SH DESCRIPTION
! 32: .B curl
! 33: is a tool to transfer data from or to a server, using one of the supported
! 34: protocols (DICT, FILE, FTP, FTPS, GOPHER, HTTP, HTTPS, IMAP, IMAPS, LDAP,
! 35: LDAPS, MQTT, POP3, POP3S, RTMP, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS,
! 36: TELNET and TFTP). The command is designed to work without user interaction.
! 37:
! 38: curl offers a busload of useful tricks like proxy support, user
! 39: authentication, FTP upload, HTTP post, SSL connections, cookies, file transfer
! 40: resume, Metalink, and more. As you will see below, the number of features will
! 41: make your head spin!
! 42:
! 43: curl is powered by libcurl for all transfer-related features. See
! 44: \fIlibcurl(3)\fP for details.
! 45: .SH URL
! 46: The URL syntax is protocol-dependent. You'll find a detailed description in
! 47: RFC 3986.
! 48:
! 49: You can specify multiple URLs or parts of URLs by writing part sets within
! 50: braces and quoting the URL as in:
! 51:
! 52: "http://site.{one,two,three}.com"
! 53:
! 54: or you can get sequences of alphanumeric series by using [] as in:
! 55:
! 56: ftp://ftp.example.com/file[1-100].txt
! 57:
! 58: ftp://ftp.example.com/file[001-100].txt (with leading zeros)
! 59:
! 60: ftp://ftp.example.com/file[a-z].txt
! 61:
! 62: Nested sequences are not supported, but you can use several ones next to each
! 63: other:
! 64:
! 65: http://example.com/archive[1996-1999]/vol[1-4]/part{a,b,c}.html
! 66:
! 67: You can specify any amount of URLs on the command line. They will be fetched
! 68: in a sequential manner in the specified order. You can specify command line
! 69: options and URLs mixed and in any order on the command line.
! 70:
! 71: You can specify a step counter for the ranges to get every Nth number or
! 72: letter:
! 73:
! 74: http://example.com/file[1-100:10].txt
! 75:
! 76: http://example.com/file[a-z:2].txt
! 77:
! 78: When using [] or {} sequences when invoked from a command line prompt, you
! 79: probably have to put the full URL within double quotes to avoid the shell from
! 80: interfering with it. This also goes for other characters treated special, like
! 81: for example '&', '?' and '*'.
! 82:
! 83: Provide the IPv6 zone index in the URL with an escaped percentage sign and the
! 84: interface name. Like in
! 85:
! 86: http://[fe80::3%25eth0]/
! 87:
! 88: If you specify URL without protocol:// prefix, curl will attempt to guess what
! 89: protocol you might want. It will then default to HTTP but try other protocols
! 90: based on often-used host name prefixes. For example, for host names starting
! 91: with "ftp." curl will assume you want to speak FTP.
! 92:
! 93: curl will do its best to use what you pass to it as a URL. It is not trying to
! 94: validate it as a syntactically correct URL by any means but is instead
! 95: \fBvery\fP liberal with what it accepts.
! 96:
! 97: curl will attempt to re-use connections for multiple file transfers, so that
! 98: getting many files from the same server will not do multiple connects /
! 99: handshakes. This improves speed. Of course this is only done on files
! 100: specified on a single command line and cannot be used between separate curl
! 101: invokes.
! 102: .SH "PROGRESS METER"
! 103: curl normally displays a progress meter during operations, indicating the
! 104: amount of transferred data, transfer speeds and estimated time left, etc. The
! 105: progress meter displays number of bytes and the speeds are in bytes per
! 106: second. The suffixes (k, M, G, T, P) are 1024 based. For example 1k is 1024
! 107: bytes. 1M is 1048576 bytes.
! 108:
! 109: curl displays this data to the terminal by default, so if you invoke curl to
! 110: do an operation and it is about to write data to the terminal, it
! 111: \fIdisables\fP the progress meter as otherwise it would mess up the output
! 112: mixing progress meter and response data.
! 113:
! 114: If you want a progress meter for HTTP POST or PUT requests, you need to
! 115: redirect the response output to a file, using shell redirect (>), \fI-o, --output\fP or
! 116: similar.
! 117:
! 118: It is not the same case for FTP upload as that operation does not spit out
! 119: any response data to the terminal.
! 120:
! 121: If you prefer a progress "bar" instead of the regular meter, \fI-#, --progress-bar\fP is
! 122: your friend. You can also disable the progress meter completely with the
! 123: \fI-s, --silent\fP option.
! 124: .SH OPTIONS
! 125: Options start with one or two dashes. Many of the options require an
! 126: additional value next to them.
! 127:
! 128: The short "single-dash" form of the options, -d for example, may be used with
! 129: or without a space between it and its value, although a space is a recommended
! 130: separator. The long "double-dash" form, \fI-d, --data\fP for example, requires a space
! 131: between it and its value.
! 132:
! 133: Short version options that don't need any additional values can be used
! 134: immediately next to each other, like for example you can specify all the
! 135: options -O, -L and -v at once as -OLv.
! 136:
! 137: In general, all boolean options are enabled with --\fBoption\fP and yet again
! 138: disabled with --\fBno-\fPoption. That is, you use the exact same option name
! 139: but prefix it with "no-". However, in this list we mostly only list and show
! 140: the --option version of them. (This concept with --no options was added in
! 141: 7.19.0. Previously most options were toggled on/off on repeated use of the
! 142: same command line option.)
! 143: .IP "--abstract-unix-socket <path>"
! 144: (HTTP) Connect through an abstract Unix domain socket, instead of using the network.
! 145: Note: netstat shows the path of an abstract socket prefixed with '@', however
! 146: the <path> argument should not have this leading character.
! 147:
! 148: Added in 7.53.0.
! 149: .IP "--alt-svc <file name>"
! 150: (HTTPS) WARNING: this option is experimental. Do not use in production.
! 151:
! 152: This option enables the alt-svc parser in curl. If the file name points to an
! 153: existing alt-svc cache file, that will be used. After a completed transfer,
! 154: the cache will be saved to the file name again if it has been modified.
! 155:
! 156: Specify a "" file name (zero length) to avoid loading/saving and make curl
! 157: just handle the cache in memory.
! 158:
! 159: If this option is used several times, curl will load contents from all the
! 160: files but the last one will be used for saving.
! 161:
! 162: Added in 7.64.1.
! 163: .IP "--anyauth"
! 164: (HTTP) Tells curl to figure out authentication method by itself, and use the most
! 165: secure one the remote site claims to support. This is done by first doing a
! 166: request and checking the response-headers, thus possibly inducing an extra
! 167: network round-trip. This is used instead of setting a specific authentication
! 168: method, which you can do with \fI--basic\fP, \fI--digest\fP, \fI--ntlm\fP, and \fI--negotiate\fP.
! 169:
! 170: Using \fI--anyauth\fP is not recommended if you do uploads from stdin, since it may
! 171: require data to be sent twice and then the client must be able to rewind. If
! 172: the need should arise when uploading from stdin, the upload operation will
! 173: fail.
! 174:
! 175: Used together with \fI-u, --user\fP.
! 176:
! 177: See also \fI--proxy-anyauth\fP and \fI--basic\fP and \fI--digest\fP.
! 178: .IP "-a, --append"
! 179: (FTP SFTP) When used in an upload, this makes curl append to the target file instead of
! 180: overwriting it. If the remote file doesn't exist, it will be created. Note
! 181: that this flag is ignored by some SFTP servers (including OpenSSH).
! 182: .IP "--basic"
! 183: (HTTP) Tells curl to use HTTP Basic authentication with the remote host. This is the
! 184: default and this option is usually pointless, unless you use it to override a
! 185: previously set option that sets a different authentication method (such as
! 186: \fI--ntlm\fP, \fI--digest\fP, or \fI--negotiate\fP).
! 187:
! 188: Used together with \fI-u, --user\fP.
! 189:
! 190: See also \fI--proxy-basic\fP.
! 191: .IP "--cacert <file>"
! 192: (TLS) Tells curl to use the specified certificate file to verify the peer. The file
! 193: may contain multiple CA certificates. The certificate(s) must be in PEM
! 194: format. Normally curl is built to use a default file for this, so this option
! 195: is typically used to alter that default file.
! 196:
! 197: curl recognizes the environment variable named 'CURL_CA_BUNDLE' if it is
! 198: set, and uses the given path as a path to a CA cert bundle. This option
! 199: overrides that variable.
! 200:
! 201: The windows version of curl will automatically look for a CA certs file named
! 202: \'curl-ca-bundle.crt\', either in the same directory as curl.exe, or in the
! 203: Current Working Directory, or in any folder along your PATH.
! 204:
! 205: If curl is built against the NSS SSL library, the NSS PEM PKCS#11 module
! 206: (libnsspem.so) needs to be available for this option to work properly.
! 207:
! 208: (iOS and macOS only) If curl is built against Secure Transport, then this
! 209: option is supported for backward compatibility with other SSL engines, but it
! 210: should not be set. If the option is not set, then curl will use the
! 211: certificates in the system and user Keychain to verify the peer, which is the
! 212: preferred method of verifying the peer's certificate chain.
! 213:
! 214: (Schannel only) This option is supported for Schannel in Windows 7 or later with
! 215: libcurl 7.60 or later. This option is supported for backward compatibility
! 216: with other SSL engines; instead it is recommended to use Windows' store of
! 217: root certificates (the default for Schannel).
! 218:
! 219: If this option is used several times, the last one will be used.
! 220: .IP "--capath <dir>"
! 221: (TLS) Tells curl to use the specified certificate directory to verify the
! 222: peer. Multiple paths can be provided by separating them with ":" (e.g.
! 223: \&"path1:path2:path3"). The certificates must be in PEM format, and if curl is
! 224: built against OpenSSL, the directory must have been processed using the
! 225: c_rehash utility supplied with OpenSSL. Using \fI--capath\fP can allow
! 226: OpenSSL-powered curl to make SSL-connections much more efficiently than using
! 227: \fI--cacert\fP if the --cacert file contains many CA certificates.
! 228:
! 229: If this option is set, the default capath value will be ignored, and if it is
! 230: used several times, the last one will be used.
! 231: .IP "--cert-status"
! 232: (TLS) Tells curl to verify the status of the server certificate by using the
! 233: Certificate Status Request (aka. OCSP stapling) TLS extension.
! 234:
! 235: If this option is enabled and the server sends an invalid (e.g. expired)
! 236: response, if the response suggests that the server certificate has been revoked,
! 237: or no response at all is received, the verification fails.
! 238:
! 239: This is currently only implemented in the OpenSSL, GnuTLS and NSS backends.
! 240:
! 241: Added in 7.41.0.
! 242: .IP "--cert-type <type>"
! 243: (TLS) Tells curl what type the provided client certificate is using. PEM, DER, ENG
! 244: and P12 are recognized types. If not specified, PEM is assumed.
! 245:
! 246: If this option is used several times, the last one will be used.
! 247:
! 248: See also \fI-E, --cert\fP and \fI--key\fP and \fI--key-type\fP.
! 249: .IP "-E, --cert <certificate[:password]>"
! 250: (TLS) Tells curl to use the specified client certificate file when getting a file
! 251: with HTTPS, FTPS or another SSL-based protocol. The certificate must be in
! 252: PKCS#12 format if using Secure Transport, or PEM format if using any other
! 253: engine. If the optional password isn't specified, it will be queried for on
! 254: the terminal. Note that this option assumes a \&"certificate" file that is the
! 255: private key and the client certificate concatenated! See \fI-E, --cert\fP and \fI--key\fP to
! 256: specify them independently.
! 257:
! 258: If curl is built against the NSS SSL library then this option can tell
! 259: curl the nickname of the certificate to use within the NSS database defined
! 260: by the environment variable SSL_DIR (or by default /etc/pki/nssdb). If the
! 261: NSS PEM PKCS#11 module (libnsspem.so) is available then PEM files may be
! 262: loaded. If you want to use a file from the current directory, please precede
! 263: it with "./" prefix, in order to avoid confusion with a nickname. If the
! 264: nickname contains ":", it needs to be preceded by "\\" so that it is not
! 265: recognized as password delimiter. If the nickname contains "\\", it needs to
! 266: be escaped as "\\\\" so that it is not recognized as an escape character.
! 267:
! 268: If curl is built against OpenSSL library, and the engine pkcs11 is available,
! 269: then a PKCS#11 URI (RFC 7512) can be used to specify a certificate located in
! 270: a PKCS#11 device. A string beginning with "pkcs11:" will be interpreted as a
! 271: PKCS#11 URI. If a PKCS#11 URI is provided, then the \fI--engine\fP option will be set
! 272: as "pkcs11" if none was provided and the \fI--cert-type\fP option will be set as
! 273: "ENG" if none was provided.
! 274:
! 275: (iOS and macOS only) If curl is built against Secure Transport, then the
! 276: certificate string can either be the name of a certificate/private key in the
! 277: system or user keychain, or the path to a PKCS#12-encoded certificate and
! 278: private key. If you want to use a file from the current directory, please
! 279: precede it with "./" prefix, in order to avoid confusion with a nickname.
! 280:
! 281: (Schannel only) Client certificates must be specified by a path
! 282: expression to a certificate store. (Loading PFX is not supported; you can
! 283: import it to a store first). You can use
! 284: "<store location>\\<store name>\\<thumbprint>" to refer to a certificate
! 285: in the system certificates store, for example,
! 286: "CurrentUser\\MY\\934a7ac6f8a5d579285a74fa61e19f23ddfe8d7a". Thumbprint is
! 287: usually a SHA-1 hex string which you can see in certificate details. Following
! 288: store locations are supported: CurrentUser, LocalMachine, CurrentService,
! 289: Services, CurrentUserGroupPolicy, LocalMachineGroupPolicy,
! 290: LocalMachineEnterprise.
! 291:
! 292: If this option is used several times, the last one will be used.
! 293:
! 294: See also \fI--cert-type\fP and \fI--key\fP and \fI--key-type\fP.
! 295: .IP "--ciphers <list of ciphers>"
! 296: (TLS) Specifies which ciphers to use in the connection. The list of ciphers must
! 297: specify valid ciphers. Read up on SSL cipher list details on this URL:
! 298:
! 299: https://curl.haxx.se/docs/ssl-ciphers.html
! 300:
! 301: If this option is used several times, the last one will be used.
! 302: .IP "--compressed-ssh"
! 303: (SCP SFTP) Enables built-in SSH compression.
! 304: This is a request, not an order; the server may or may not do it.
! 305:
! 306: Added in 7.56.0.
! 307: .IP "--compressed"
! 308: (HTTP) Request a compressed response using one of the algorithms curl supports, and
! 309: automatically decompress the content. Headers are not modified.
! 310:
! 311: If this option is used and the server sends an unsupported encoding, curl will
! 312: report an error.
! 313: .IP "-K, --config <file>"
! 314:
! 315: Specify a text file to read curl arguments from. The command line arguments
! 316: found in the text file will be used as if they were provided on the command
! 317: line.
! 318:
! 319: Options and their parameters must be specified on the same line in the file,
! 320: separated by whitespace, colon, or the equals sign. Long option names can
! 321: optionally be given in the config file without the initial double dashes and
! 322: if so, the colon or equals characters can be used as separators. If the option
! 323: is specified with one or two dashes, there can be no colon or equals character
! 324: between the option and its parameter.
! 325:
! 326: If the parameter contains whitespace (or starts with : or =), the parameter
! 327: must be enclosed within quotes. Within double quotes, the following escape
! 328: sequences are available: \\\\, \\", \\t, \\n, \\r and \\v. A backslash
! 329: preceding any other letter is ignored. If the first column of a config line is
! 330: a '#' character, the rest of the line will be treated as a comment. Only write
! 331: one option per physical line in the config file.
! 332:
! 333: Specify the filename to \fI-K, --config\fP as '-' to make curl read the file from stdin.
! 334:
! 335: Note that to be able to specify a URL in the config file, you need to specify
! 336: it using the \fI--url\fP option, and not by simply writing the URL on its own
! 337: line. So, it could look similar to this:
! 338:
! 339: url = "https://curl.haxx.se/docs/"
! 340:
! 341: When curl is invoked, it (unless \fI-q, --disable\fP is used) checks for a default
! 342: config file and uses it if found. The default config file is checked for in
! 343: the following places in this order:
! 344:
! 345: 1) curl tries to find the "home dir": It first checks for the CURL_HOME and
! 346: then the HOME environment variables. Failing that, it uses getpwuid() on
! 347: Unix-like systems (which returns the home dir given the current user in your
! 348: system). On Windows, it then checks for the APPDATA variable, or as a last
! 349: resort the '%USERPROFILE%\\Application Data'.
! 350:
! 351: 2) On windows, if there is no .curlrc file in the home dir, it checks for one
! 352: in the same dir the curl executable is placed. On Unix-like systems, it will
! 353: simply try to load .curlrc from the determined home dir.
! 354:
! 355: .nf
! 356: # --- Example file ---
! 357: # this is a comment
! 358: url = "example.com"
! 359: output = "curlhere.html"
! 360: user-agent = "superagent/1.0"
! 361:
! 362: # and fetch another URL too
! 363: url = "example.com/docs/manpage.html"
! 364: -O
! 365: referer = "http://nowhereatall.example.com/"
! 366: # --- End of example file ---
! 367: .fi
! 368:
! 369: This option can be used multiple times to load multiple config files.
! 370: .IP "--connect-timeout <seconds>"
! 371: Maximum time in seconds that you allow curl's connection to take. This only
! 372: limits the connection phase, so if curl connects within the given period it
! 373: will continue - if not it will exit. Since version 7.32.0, this option
! 374: accepts decimal values.
! 375:
! 376: If this option is used several times, the last one will be used.
! 377:
! 378: See also \fI-m, --max-time\fP.
! 379: .IP "--connect-to <HOST1:PORT1:HOST2:PORT2>"
! 380:
! 381: For a request to the given HOST1:PORT1 pair, connect to HOST2:PORT2 instead.
! 382: This option is suitable to direct requests at a specific server, e.g. at a
! 383: specific cluster node in a cluster of servers. This option is only used to
! 384: establish the network connection. It does NOT affect the hostname/port that is
! 385: used for TLS/SSL (e.g. SNI, certificate verification) or for the application
! 386: protocols. "HOST1" and "PORT1" may be the empty string, meaning "any
! 387: host/port". "HOST2" and "PORT2" may also be the empty string, meaning "use the
! 388: request's original host/port".
! 389:
! 390: A "host" specified to this option is compared as a string, so it needs to
! 391: match the name used in request URL. It can be either numerical such as
! 392: "127.0.0.1" or the full host name such as "example.org".
! 393:
! 394: This option can be used many times to add many connect rules.
! 395:
! 396: See also \fI--resolve\fP and \fI-H, --header\fP. Added in 7.49.0.
! 397: .IP "-C, --continue-at <offset>"
! 398: Continue/Resume a previous file transfer at the given offset. The given offset
! 399: is the exact number of bytes that will be skipped, counting from the beginning
! 400: of the source file before it is transferred to the destination. If used with
! 401: uploads, the FTP server command SIZE will not be used by curl.
! 402:
! 403: Use "-C -" to tell curl to automatically find out where/how to resume the
! 404: transfer. It then uses the given output/input files to figure that out.
! 405:
! 406: If this option is used several times, the last one will be used.
! 407:
! 408: See also \fI-r, --range\fP.
! 409: .IP "-c, --cookie-jar <filename>"
! 410: (HTTP) Specify to which file you want curl to write all cookies after a completed
! 411: operation. Curl writes all cookies from its in-memory cookie storage to the
! 412: given file at the end of operations. If no cookies are known, no data will be
! 413: written. The file will be written using the Netscape cookie file format. If
! 414: you set the file name to a single dash, "-", the cookies will be written to
! 415: stdout.
! 416:
! 417: This command line option will activate the cookie engine that makes curl
! 418: record and use cookies. Another way to activate it is to use the \fI-b, --cookie\fP
! 419: option.
! 420:
! 421: If the cookie jar can't be created or written to, the whole curl operation
! 422: won't fail or even report an error clearly. Using \fI-v, --verbose\fP will get a warning
! 423: displayed, but that is the only visible feedback you get about this possibly
! 424: lethal situation.
! 425:
! 426: If this option is used several times, the last specified file name will be
! 427: used.
! 428: .IP "-b, --cookie <data|filename>"
! 429: (HTTP) Pass the data to the HTTP server in the Cookie header. It is supposedly
! 430: the data previously received from the server in a "Set-Cookie:" line. The
! 431: data should be in the format "NAME1=VALUE1; NAME2=VALUE2".
! 432:
! 433: If no '=' symbol is used in the argument, it is instead treated as a filename
! 434: to read previously stored cookie from. This option also activates the cookie
! 435: engine which will make curl record incoming cookies, which may be handy if
! 436: you're using this in combination with the \fI-L, --location\fP option or do multiple URL
! 437: transfers on the same invoke. If the file name is exactly a minus ("-"), curl
! 438: will instead read the contents from stdin.
! 439:
! 440: The file format of the file to read cookies from should be plain HTTP headers
! 441: (Set-Cookie style) or the Netscape/Mozilla cookie file format.
! 442:
! 443: The file specified with \fI-b, --cookie\fP is only used as input. No cookies will be
! 444: written to the file. To store cookies, use the \fI-c, --cookie-jar\fP option.
! 445:
! 446: Exercise caution if you are using this option and multiple transfers may
! 447: occur. If you use the NAME1=VALUE1; format, or in a file use the Set-Cookie
! 448: format and don't specify a domain, then the cookie is sent for any domain
! 449: (even after redirects are followed) and cannot be modified by a server-set
! 450: cookie. If the cookie engine is enabled and a server sets a cookie of the same
! 451: name then both will be sent on a future transfer to that server, likely not
! 452: what you intended. To address these issues set a domain in Set-Cookie (doing
! 453: that will include sub domains) or use the Netscape format.
! 454:
! 455: If this option is used several times, the last one will be used.
! 456:
! 457: Users very often want to both read cookies from a file and write updated
! 458: cookies back to a file, so using both \fI-b, --cookie\fP and \fI-c, --cookie-jar\fP in the same
! 459: command line is common.
! 460: .IP "--create-dirs"
! 461: When used in conjunction with the \fI-o, --output\fP option, curl will create the
! 462: necessary local directory hierarchy as needed. This option creates the dirs
! 463: mentioned with the \fI-o, --output\fP option, nothing else. If the --output file name
! 464: uses no dir or if the dirs it mentions already exist, no dir will be created.
! 465:
! 466: Created dirs are made with mode 0750 on unix style file systems.
! 467:
! 468: To create remote directories when using FTP or SFTP, try \fI--ftp-create-dirs\fP.
! 469: .IP "--crlf"
! 470: (FTP SMTP) Convert LF to CRLF in upload. Useful for MVS (OS/390).
! 471:
! 472: (SMTP added in 7.40.0)
! 473: .IP "--crlfile <file>"
! 474: (TLS) Provide a file using PEM format with a Certificate Revocation List that may
! 475: specify peer certificates that are to be considered revoked.
! 476:
! 477: If this option is used several times, the last one will be used.
! 478:
! 479: Added in 7.19.7.
! 480: .IP "--data-ascii <data>"
! 481: (HTTP) This is just an alias for \fI-d, --data\fP.
! 482: .IP "--data-binary <data>"
! 483: (HTTP) This posts data exactly as specified with no extra processing whatsoever.
! 484:
! 485: If you start the data with the letter @, the rest should be a filename. Data
! 486: is posted in a similar manner as \fI-d, --data\fP does, except that newlines and
! 487: carriage returns are preserved and conversions are never done.
! 488:
! 489: Like \fI-d, --data\fP the default content-type sent to the server is
! 490: application/x-www-form-urlencoded. If you want the data to be treated as
! 491: arbitrary binary data by the server then set the content-type to octet-stream:
! 492: -H "Content-Type: application/octet-stream".
! 493:
! 494: If this option is used several times, the ones following the first will append
! 495: data as described in \fI-d, --data\fP.
! 496: .IP "--data-raw <data>"
! 497: (HTTP) This posts data similarly to \fI-d, --data\fP but without the special
! 498: interpretation of the @ character.
! 499:
! 500: See also \fI-d, --data\fP. Added in 7.43.0.
! 501: .IP "--data-urlencode <data>"
! 502: (HTTP) This posts data, similar to the other \fI-d, --data\fP options with the exception
! 503: that this performs URL-encoding.
! 504:
! 505: To be CGI-compliant, the <data> part should begin with a \fIname\fP followed
! 506: by a separator and a content specification. The <data> part can be passed to
! 507: curl using one of the following syntaxes:
! 508: .RS
! 509: .IP "content"
! 510: This will make curl URL-encode the content and pass that on. Just be careful
! 511: so that the content doesn't contain any = or @ symbols, as that will then make
! 512: the syntax match one of the other cases below!
! 513: .IP "=content"
! 514: This will make curl URL-encode the content and pass that on. The preceding =
! 515: symbol is not included in the data.
! 516: .IP "name=content"
! 517: This will make curl URL-encode the content part and pass that on. Note that
! 518: the name part is expected to be URL-encoded already.
! 519: .IP "@filename"
! 520: This will make curl load data from the given file (including any newlines),
! 521: URL-encode that data and pass it on in the POST.
! 522: .IP "name@filename"
! 523: This will make curl load data from the given file (including any newlines),
! 524: URL-encode that data and pass it on in the POST. The name part gets an equal
! 525: sign appended, resulting in \fIname=urlencoded-file-content\fP. Note that the
! 526: name is expected to be URL-encoded already.
! 527: .RE
! 528:
! 529: See also \fI-d, --data\fP and \fI--data-raw\fP. Added in 7.18.0.
! 530: .IP "-d, --data <data>"
! 531: (HTTP MQTT) Sends the specified data in a POST request to the HTTP server, in the same way
! 532: that a browser does when a user has filled in an HTML form and presses the
! 533: submit button. This will cause curl to pass the data to the server using the
! 534: content-type application/x-www-form-urlencoded. Compare to \fI-F, --form\fP.
! 535:
! 536: \fI--data-raw\fP is almost the same but does not have a special interpretation of
! 537: the @ character. To post data purely binary, you should instead use the
! 538: \fI--data-binary\fP option. To URL-encode the value of a form field you may use
! 539: \fI--data-urlencode\fP.
! 540:
! 541: If any of these options is used more than once on the same command line, the
! 542: data pieces specified will be merged together with a separating
! 543: &-symbol. Thus, using '-d name=daniel -d skill=lousy' would generate a post
! 544: chunk that looks like \&'name=daniel&skill=lousy'.
! 545:
! 546: If you start the data with the letter @, the rest should be a file name to
! 547: read the data from, or - if you want curl to read the data from stdin. Posting
! 548: data from a file named \&'foobar' would thus be done with \fI-d, --data\fP @foobar. When
! 549: \fI-d, --data\fP is told to read from a file like that, carriage returns and newlines
! 550: will be stripped out. If you don't want the @ character to have a special
! 551: interpretation use \fI--data-raw\fP instead.
! 552:
! 553: See also \fI--data-binary\fP and \fI--data-urlencode\fP and \fI--data-raw\fP. This option overrides \fI-F, --form\fP and \fI-I, --head\fP and \fI-T, --upload-file\fP.
! 554: .IP "--delegation <LEVEL>"
! 555: (GSS/kerberos) Set LEVEL to tell the server what it is allowed to delegate when it
! 556: comes to user credentials.
! 557: .RS
! 558: .IP "none"
! 559: Don't allow any delegation.
! 560: .IP "policy"
! 561: Delegates if and only if the OK-AS-DELEGATE flag is set in the Kerberos
! 562: service ticket, which is a matter of realm policy.
! 563: .IP "always"
! 564: Unconditionally allow the server to delegate.
! 565: .RE
! 566: .IP "--digest"
! 567: (HTTP) Enables HTTP Digest authentication. This is an authentication scheme that
! 568: prevents the password from being sent over the wire in clear text. Use this in
! 569: combination with the normal \fI-u, --user\fP option to set user name and password.
! 570:
! 571: If this option is used several times, only the first one is used.
! 572:
! 573: See also \fI-u, --user\fP and \fI--proxy-digest\fP and \fI--anyauth\fP. This option overrides \fI--basic\fP and \fI--ntlm\fP and \fI--negotiate\fP.
! 574: .IP "--disable-eprt"
! 575: (FTP) Tell curl to disable the use of the EPRT and LPRT commands when doing active
! 576: FTP transfers. Curl will normally always first attempt to use EPRT, then LPRT
! 577: before using PORT, but with this option, it will use PORT right away. EPRT and
! 578: LPRT are extensions to the original FTP protocol, and may not work on all
! 579: servers, but they enable more functionality in a better way than the
! 580: traditional PORT command.
! 581:
! 582: --eprt can be used to explicitly enable EPRT again and --no-eprt is an alias
! 583: for \fI--disable-eprt\fP.
! 584:
! 585: If the server is accessed using IPv6, this option will have no effect as EPRT
! 586: is necessary then.
! 587:
! 588: Disabling EPRT only changes the active behavior. If you want to switch to
! 589: passive mode you need to not use \fI-P, --ftp-port\fP or force it with \fI--ftp-pasv\fP.
! 590: .IP "--disable-epsv"
! 591: (FTP) (FTP) Tell curl to disable the use of the EPSV command when doing passive FTP
! 592: transfers. Curl will normally always first attempt to use EPSV before PASV,
! 593: but with this option, it will not try using EPSV.
! 594:
! 595: --epsv can be used to explicitly enable EPSV again and --no-epsv is an alias
! 596: for \fI--disable-epsv\fP.
! 597:
! 598: If the server is an IPv6 host, this option will have no effect as EPSV is
! 599: necessary then.
! 600:
! 601: Disabling EPSV only changes the passive behavior. If you want to switch to
! 602: active mode you need to use \fI-P, --ftp-port\fP.
! 603: .IP "-q, --disable"
! 604: If used as the first parameter on the command line, the \fIcurlrc\fP config
! 605: file will not be read and used. See the \fI-K, --config\fP for details on the default
! 606: config file search path.
! 607: .IP "--disallow-username-in-url"
! 608: (HTTP) This tells curl to exit if passed a url containing a username.
! 609:
! 610: See also \fI--proto\fP. Added in 7.61.0.
! 611: .IP "--dns-interface <interface>"
! 612: (DNS) Tell curl to send outgoing DNS requests through <interface>. This option is a
! 613: counterpart to \fI--interface\fP (which does not affect DNS). The supplied string
! 614: must be an interface name (not an address).
! 615:
! 616: See also \fI--dns-ipv4-addr\fP and \fI--dns-ipv6-addr\fP. \fI--dns-interface\fP requires that the underlying libcurl was built to support c-ares. Added in 7.33.0.
! 617: .IP "--dns-ipv4-addr <address>"
! 618: (DNS) Tell curl to bind to <ip-address> when making IPv4 DNS requests, so that
! 619: the DNS requests originate from this address. The argument should be a
! 620: single IPv4 address.
! 621:
! 622: See also \fI--dns-interface\fP and \fI--dns-ipv6-addr\fP. \fI--dns-ipv4-addr\fP requires that the underlying libcurl was built to support c-ares. Added in 7.33.0.
! 623: .IP "--dns-ipv6-addr <address>"
! 624: (DNS) Tell curl to bind to <ip-address> when making IPv6 DNS requests, so that
! 625: the DNS requests originate from this address. The argument should be a
! 626: single IPv6 address.
! 627:
! 628: See also \fI--dns-interface\fP and \fI--dns-ipv4-addr\fP. \fI--dns-ipv6-addr\fP requires that the underlying libcurl was built to support c-ares. Added in 7.33.0.
! 629: .IP "--dns-servers <addresses>"
! 630: Set the list of DNS servers to be used instead of the system default.
! 631: The list of IP addresses should be separated with commas. Port numbers
! 632: may also optionally be given as \fI:<port-number>\fP after each IP
! 633: address.
! 634:
! 635: \fI--dns-servers\fP requires that the underlying libcurl was built to support c-ares. Added in 7.33.0.
! 636: .IP "--doh-url <URL>"
! 637: (all) Specifies which DNS-over-HTTPS (DOH) server to use to resolve hostnames,
! 638: instead of using the default name resolver mechanism. The URL must be HTTPS.
! 639:
! 640: If this option is used several times, the last one will be used.
! 641:
! 642: Added in 7.62.0.
! 643: .IP "-D, --dump-header <filename>"
! 644: (HTTP FTP) Write the received protocol headers to the specified file.
! 645:
! 646: This option is handy to use when you want to store the headers that an HTTP
! 647: site sends to you. Cookies from the headers could then be read in a second
! 648: curl invocation by using the \fI-b, --cookie\fP option! The \fI-c, --cookie-jar\fP option is a
! 649: better way to store cookies.
! 650:
! 651: If no headers are received, the use of this option will create an empty file.
! 652:
! 653: When used in FTP, the FTP server response lines are considered being "headers"
! 654: and thus are saved there.
! 655:
! 656: If this option is used several times, the last one will be used.
! 657:
! 658: See also \fI-o, --output\fP.
! 659: .IP "--egd-file <file>"
! 660: (TLS) Specify the path name to the Entropy Gathering Daemon socket. The socket is
! 661: used to seed the random engine for SSL connections.
! 662:
! 663: See also \fI--random-file\fP.
! 664: .IP "--engine <name>"
! 665: (TLS) Select the OpenSSL crypto engine to use for cipher operations. Use \fI--engine\fP
! 666: list to print a list of build-time supported engines. Note that not all (or
! 667: none) of the engines may be available at run-time.
! 668: .IP "--etag-compare <file>"
! 669: (HTTP) This option makes a conditional HTTP request for the specific
! 670: ETag read from the given file by sending a custom If-None-Match
! 671: header using the extracted ETag.
! 672:
! 673: For correct results, make sure that specified file contains only a single
! 674: line with a desired ETag. An empty file is parsed as an empty ETag.
! 675:
! 676: Use the option \fI--etag-save\fP to first save the ETag from a response, and
! 677: then use this option to compare using the saved ETag in a subsequent request.
! 678:
! 679: \fCOMPARISON\fP: There are 2 types of comparison or ETags, Weak and Strong.
! 680: This option expects, and uses a strong comparison.
! 681:
! 682: Added in 7.68.0.
! 683: .IP "--etag-save <file>"
! 684: (HTTP) This option saves an HTTP ETag to the specified file. Etag is
! 685: usually part of headers returned by a request. When server sends an
! 686: ETag, it must be enveloped by a double quote. This option extracts the
! 687: ETag without the double quotes and saves it into the <file>.
! 688:
! 689: A server can send a week ETag which is prefixed by "W/". This identifier
! 690: is not considered, and only relevant ETag between quotation marks is parsed.
! 691:
! 692: It an ETag wasn't send by the server or it cannot be parsed, and empty
! 693: file is created.
! 694:
! 695: Added in 7.68.0.
! 696: .IP "--expect100-timeout <seconds>"
! 697: (HTTP) Maximum time in seconds that you allow curl to wait for a 100-continue
! 698: response when curl emits an Expects: 100-continue header in its request. By
! 699: default curl will wait one second. This option accepts decimal values! When
! 700: curl stops waiting, it will continue as if the response has been received.
! 701:
! 702: See also \fI--connect-timeout\fP. Added in 7.47.0.
! 703: .IP "--fail-early"
! 704: Fail and exit on the first detected transfer error.
! 705:
! 706: When curl is used to do multiple transfers on the command line, it will
! 707: attempt to operate on each given URL, one by one. By default, it will ignore
! 708: errors if there are more URLs given and the last URL's success will determine
! 709: the error code curl returns. So early failures will be "hidden" by subsequent
! 710: successful transfers.
! 711:
! 712: Using this option, curl will instead return an error on the first transfer
! 713: that fails, independent of the amount of URLs that are given on the command
! 714: line. This way, no transfer failures go undetected by scripts and similar.
! 715:
! 716: This option is global and does not need to be specified for each use of \fI-:, --next\fP.
! 717:
! 718: This option does not imply \fI-f, --fail\fP, which causes transfers to fail due to the
! 719: server's HTTP status code. You can combine the two options, however note \fI-f, --fail\fP
! 720: is not global and is therefore contained by \fI-:, --next\fP.
! 721:
! 722: Added in 7.52.0.
! 723: .IP "-f, --fail"
! 724: (HTTP) Fail silently (no output at all) on server errors. This is mostly done to
! 725: better enable scripts etc to better deal with failed attempts. In normal cases
! 726: when an HTTP server fails to deliver a document, it returns an HTML document
! 727: stating so (which often also describes why and more). This flag will prevent
! 728: curl from outputting that and return error 22.
! 729:
! 730: This method is not fail-safe and there are occasions where non-successful
! 731: response codes will slip through, especially when authentication is involved
! 732: (response codes 401 and 407).
! 733: .IP "--false-start"
! 734: (TLS) Tells curl to use false start during the TLS handshake. False start is a mode
! 735: where a TLS client will start sending application data before verifying the
! 736: server's Finished message, thus saving a round trip when performing a full
! 737: handshake.
! 738:
! 739: This is currently only implemented in the NSS and Secure Transport (on iOS 7.0
! 740: or later, or OS X 10.9 or later) backends.
! 741:
! 742: Added in 7.42.0.
! 743: .IP "--form-string <name=string>"
! 744: (HTTP SMTP IMAP) Similar to \fI-F, --form\fP except that the value string for the named parameter is used
! 745: literally. Leading \&'@' and \&'<' characters, and the \&';type=' string in
! 746: the value have no special meaning. Use this in preference to \fI-F, --form\fP if
! 747: there's any possibility that the string value may accidentally trigger the
! 748: \&'@' or \&'<' features of \fI-F, --form\fP.
! 749:
! 750: See also \fI-F, --form\fP.
! 751: .IP "-F, --form <name=content>"
! 752: (HTTP SMTP IMAP) For HTTP protocol family, this lets curl emulate a filled-in form in which a
! 753: user has pressed the submit button. This causes curl to POST data using the
! 754: Content-Type multipart/form-data according to RFC 2388.
! 755:
! 756: For SMTP and IMAP protocols, this is the mean to compose a multipart mail
! 757: message to transmit.
! 758:
! 759: This enables uploading of binary files etc. To force the 'content' part to be
! 760: a file, prefix the file name with an @ sign. To just get the content part from
! 761: a file, prefix the file name with the symbol <. The difference between @ and <
! 762: is then that @ makes a file get attached in the post as a file upload, while
! 763: the < makes a text field and just get the contents for that text field from a
! 764: file.
! 765:
! 766: Tell curl to read content from stdin instead of a file by using - as
! 767: filename. This goes for both @ and < constructs. When stdin is used, the
! 768: contents is buffered in memory first by curl to determine its size and allow a
! 769: possible resend. Defining a part's data from a named non-regular file (such
! 770: as a named pipe or similar) is unfortunately not subject to buffering and will
! 771: be effectively read at transmission time; since the full size is unknown
! 772: before the transfer starts, such data is sent as chunks by HTTP and rejected
! 773: by IMAP.
! 774:
! 775: Example: send an image to an HTTP server, where \&'profile' is the name of the
! 776: form-field to which the file portrait.jpg will be the input:
! 777:
! 778: curl -F profile=@portrait.jpg https://example.com/upload.cgi
! 779:
! 780: Example: send your name and shoe size in two text fields to the server:
! 781:
! 782: curl -F name=John -F shoesize=11 https://example.com/
! 783:
! 784: Example: send your essay in a text field to the server. Send it as a plain
! 785: text field, but get the contents for it from a local file:
! 786:
! 787: curl -F "story=<hugefile.txt" https://example.com/
! 788:
! 789: You can also tell curl what Content-Type to use by using 'type=', in a manner
! 790: similar to:
! 791:
! 792: curl -F "web=@index.html;type=text/html" example.com
! 793:
! 794: or
! 795:
! 796: curl -F "name=daniel;type=text/foo" example.com
! 797:
! 798: You can also explicitly change the name field of a file upload part by setting
! 799: filename=, like this:
! 800:
! 801: curl -F "file=@localfile;filename=nameinpost" example.com
! 802:
! 803: If filename/path contains ',' or ';', it must be quoted by double-quotes like:
! 804:
! 805: curl -F "file=@\\"localfile\\";filename=\\"nameinpost\\"" example.com
! 806:
! 807: or
! 808:
! 809: curl -F 'file=@"localfile";filename="nameinpost"' example.com
! 810:
! 811: Note that if a filename/path is quoted by double-quotes, any double-quote
! 812: or backslash within the filename must be escaped by backslash.
! 813:
! 814: Quoting must also be applied to non-file data if it contains semicolons,
! 815: leading/trailing spaces or leading double quotes:
! 816:
! 817: curl -F 'colors="red; green; blue";type=text/x-myapp' example.com
! 818:
! 819: You can add custom headers to the field by setting headers=, like
! 820:
! 821: curl -F "submit=OK;headers=\\"X-submit-type: OK\\"" example.com
! 822:
! 823: or
! 824:
! 825: curl -F "submit=OK;headers=@headerfile" example.com
! 826:
! 827: The headers= keyword may appear more that once and above notes about quoting
! 828: apply. When headers are read from a file, Empty lines and lines starting
! 829: with '#' are comments and ignored; each header can be folded by splitting
! 830: between two words and starting the continuation line with a space; embedded
! 831: carriage-returns and trailing spaces are stripped.
! 832: Here is an example of a header file contents:
! 833:
! 834: # This file contain two headers.
! 835: .br
! 836: X-header-1: this is a header
! 837:
! 838: # The following header is folded.
! 839: .br
! 840: X-header-2: this is
! 841: .br
! 842: another header
! 843:
! 844:
! 845: To support sending multipart mail messages, the syntax is extended as follows:
! 846: .br
! 847: - name can be omitted: the equal sign is the first character of the argument,
! 848: .br
! 849: - if data starts with '(', this signals to start a new multipart: it can be
! 850: followed by a content type specification.
! 851: .br
! 852: - a multipart can be terminated with a '=)' argument.
! 853:
! 854: Example: the following command sends an SMTP mime e-mail consisting in an
! 855: inline part in two alternative formats: plain text and HTML. It attaches a
! 856: text file:
! 857:
! 858: curl -F '=(;type=multipart/alternative' \\
! 859: .br
! 860: -F '=plain text message' \\
! 861: .br
! 862: -F '= <body>HTML message</body>;type=text/html' \\
! 863: .br
! 864: -F '=)' -F '=@textfile.txt' ... smtp://example.com
! 865:
! 866: Data can be encoded for transfer using encoder=. Available encodings are
! 867: \fIbinary\fP and \fI8bit\fP that do nothing else than adding the corresponding
! 868: Content-Transfer-Encoding header, \fI7bit\fP that only rejects 8-bit characters
! 869: with a transfer error, \fIquoted-printable\fP and \fIbase64\fP that encodes
! 870: data according to the corresponding schemes, limiting lines length to
! 871: 76 characters.
! 872:
! 873: Example: send multipart mail with a quoted-printable text message and a
! 874: base64 attached file:
! 875:
! 876: curl -F '=text message;encoder=quoted-printable' \\
! 877: .br
! 878: -F '=@localfile;encoder=base64' ... smtp://example.com
! 879:
! 880: See further examples and details in the MANUAL.
! 881:
! 882: This option can be used multiple times.
! 883:
! 884: This option overrides \fI-d, --data\fP and \fI-I, --head\fP and \fI-T, --upload-file\fP.
! 885: .IP "--ftp-account <data>"
! 886: (FTP) When an FTP server asks for "account data" after user name and password has
! 887: been provided, this data is sent off using the ACCT command.
! 888:
! 889: If this option is used several times, the last one will be used.
! 890:
! 891: Added in 7.13.0.
! 892: .IP "--ftp-alternative-to-user <command>"
! 893: (FTP) If authenticating with the USER and PASS commands fails, send this command.
! 894: When connecting to Tumbleweed's Secure Transport server over FTPS using a
! 895: client certificate, using "SITE AUTH" will tell the server to retrieve the
! 896: username from the certificate.
! 897:
! 898: Added in 7.15.5.
! 899: .IP "--ftp-create-dirs"
! 900: (FTP SFTP) When an FTP or SFTP URL/operation uses a path that doesn't currently exist on
! 901: the server, the standard behavior of curl is to fail. Using this option, curl
! 902: will instead attempt to create missing directories.
! 903:
! 904: See also \fI--create-dirs\fP.
! 905: .IP "--ftp-method <method>"
! 906: (FTP) Control what method curl should use to reach a file on an FTP(S)
! 907: server. The method argument should be one of the following alternatives:
! 908: .RS
! 909: .IP multicwd
! 910: curl does a single CWD operation for each path part in the given URL. For deep
! 911: hierarchies this means very many commands. This is how RFC 1738 says it should
! 912: be done. This is the default but the slowest behavior.
! 913: .IP nocwd
! 914: curl does no CWD at all. curl will do SIZE, RETR, STOR etc and give a full
! 915: path to the server for all these commands. This is the fastest behavior.
! 916: .IP singlecwd
! 917: curl does one CWD with the full target directory and then operates on the file
! 918: \&"normally" (like in the multicwd case). This is somewhat more standards
! 919: compliant than 'nocwd' but without the full penalty of 'multicwd'.
! 920: .RE
! 921:
! 922: Added in 7.15.1.
! 923: .IP "--ftp-pasv"
! 924: (FTP) Use passive mode for the data connection. Passive is the internal default
! 925: behavior, but using this option can be used to override a previous \fI-P, --ftp-port\fP
! 926: option.
! 927:
! 928: If this option is used several times, only the first one is used. Undoing an
! 929: enforced passive really isn't doable but you must then instead enforce the
! 930: correct \fI-P, --ftp-port\fP again.
! 931:
! 932: Passive mode means that curl will try the EPSV command first and then PASV,
! 933: unless \fI--disable-epsv\fP is used.
! 934:
! 935: See also \fI--disable-epsv\fP. Added in 7.11.0.
! 936: .IP "-P, --ftp-port <address>"
! 937: (FTP) Reverses the default initiator/listener roles when connecting with FTP. This
! 938: option makes curl use active mode. curl then tells the server to connect back
! 939: to the client's specified address and port, while passive mode asks the server
! 940: to setup an IP address and port for it to connect to. <address> should be one
! 941: of:
! 942: .RS
! 943: .IP interface
! 944: e.g. "eth0" to specify which interface's IP address you want to use (Unix only)
! 945: .IP "IP address"
! 946: e.g. "192.168.10.1" to specify the exact IP address
! 947: .IP "host name"
! 948: e.g. "my.host.domain" to specify the machine
! 949: .IP "-"
! 950: make curl pick the same IP address that is already used for the control
! 951: connection
! 952: .RE
! 953:
! 954: If this option is used several times, the last one will be used. Disable the
! 955: use of PORT with \fI--ftp-pasv\fP. Disable the attempt to use the EPRT command
! 956: instead of PORT by using \fI--disable-eprt\fP. EPRT is really PORT++.
! 957:
! 958: Since 7.19.5, you can append \&":[start]-[end]\&" to the right of the address,
! 959: to tell curl what TCP port range to use. That means you specify a port range,
! 960: from a lower to a higher number. A single number works as well, but do note
! 961: that it increases the risk of failure since the port may not be available.
! 962:
! 963: See also \fI--ftp-pasv\fP and \fI--disable-eprt\fP.
! 964: .IP "--ftp-pret"
! 965: (FTP) Tell curl to send a PRET command before PASV (and EPSV). Certain FTP servers,
! 966: mainly drftpd, require this non-standard command for directory listings as
! 967: well as up and downloads in PASV mode.
! 968:
! 969: Added in 7.20.0.
! 970: .IP "--ftp-skip-pasv-ip"
! 971: (FTP) Tell curl to not use the IP address the server suggests in its response
! 972: to curl's PASV command when curl connects the data connection. Instead curl
! 973: will re-use the same IP address it already uses for the control
! 974: connection.
! 975:
! 976: This option has no effect if PORT, EPRT or EPSV is used instead of PASV.
! 977:
! 978: See also \fI--ftp-pasv\fP. Added in 7.14.2.
! 979: .IP "--ftp-ssl-ccc-mode <active/passive>"
! 980: (FTP) Sets the CCC mode. The passive mode will not initiate the shutdown, but
! 981: instead wait for the server to do it, and will not reply to the shutdown from
! 982: the server. The active mode initiates the shutdown and waits for a reply from
! 983: the server.
! 984:
! 985: See also \fI--ftp-ssl-ccc\fP. Added in 7.16.2.
! 986: .IP "--ftp-ssl-ccc"
! 987: (FTP) Use CCC (Clear Command Channel) Shuts down the SSL/TLS layer after
! 988: authenticating. The rest of the control channel communication will be
! 989: unencrypted. This allows NAT routers to follow the FTP transaction. The
! 990: default mode is passive.
! 991:
! 992: See also \fI--ssl\fP and \fI--ftp-ssl-ccc-mode\fP. Added in 7.16.1.
! 993: .IP "--ftp-ssl-control"
! 994: (FTP) Require SSL/TLS for the FTP login, clear for transfer. Allows secure
! 995: authentication, but non-encrypted data transfers for efficiency. Fails the
! 996: transfer if the server doesn't support SSL/TLS.
! 997:
! 998: Added in 7.16.0.
! 999: .IP "-G, --get"
! 1000: When used, this option will make all data specified with \fI-d, --data\fP, \fI--data-binary\fP
! 1001: or \fI--data-urlencode\fP to be used in an HTTP GET request instead of the POST
! 1002: request that otherwise would be used. The data will be appended to the URL
! 1003: with a '?' separator.
! 1004:
! 1005: If used in combination with \fI-I, --head\fP, the POST data will instead be appended to
! 1006: the URL with a HEAD request.
! 1007:
! 1008: If this option is used several times, only the first one is used. This is
! 1009: because undoing a GET doesn't make sense, but you should then instead enforce
! 1010: the alternative method you prefer.
! 1011: .IP "-g, --globoff"
! 1012: This option switches off the "URL globbing parser". When you set this option,
! 1013: you can specify URLs that contain the letters {}[] without having them being
! 1014: interpreted by curl itself. Note that these letters are not normal legal URL
! 1015: contents but they should be encoded according to the URI standard.
! 1016: .IP "--happy-eyeballs-timeout-ms <milliseconds>"
! 1017: Happy eyeballs is an algorithm that attempts to connect to both IPv4 and IPv6
! 1018: addresses for dual-stack hosts, preferring IPv6 first for the number of
! 1019: milliseconds. If the IPv6 address cannot be connected to within that time then
! 1020: a connection attempt is made to the IPv4 address in parallel. The first
! 1021: connection to be established is the one that is used.
! 1022:
! 1023: The range of suggested useful values is limited. Happy Eyeballs RFC 6555 says
! 1024: "It is RECOMMENDED that connection attempts be paced 150-250 ms apart to
! 1025: balance human factors against network load." libcurl currently defaults to
! 1026: 200 ms. Firefox and Chrome currently default to 300 ms.
! 1027:
! 1028: If this option is used several times, the last one will be used.
! 1029:
! 1030: Added in 7.59.0.
! 1031: .IP "--haproxy-protocol"
! 1032: (HTTP) Send a HAProxy PROXY protocol v1 header at the beginning of the connection. This
! 1033: is used by some load balancers and reverse proxies to indicate the client's
! 1034: true IP address and port.
! 1035:
! 1036: This option is primarily useful when sending test requests to a service that
! 1037: expects this header.
! 1038:
! 1039: Added in 7.60.0.
! 1040: .IP "-I, --head"
! 1041: (HTTP FTP FILE) Fetch the headers only! HTTP-servers feature the command HEAD which this uses
! 1042: to get nothing but the header of a document. When used on an FTP or FILE file,
! 1043: curl displays the file size and last modification time only.
! 1044: .IP "-H, --header <header/@file>"
! 1045: (HTTP) Extra header to include in the request when sending HTTP to a server. You may
! 1046: specify any number of extra headers. Note that if you should add a custom
! 1047: header that has the same name as one of the internal ones curl would use, your
! 1048: externally set header will be used instead of the internal one. This allows
! 1049: you to make even trickier stuff than curl would normally do. You should not
! 1050: replace internally set headers without knowing perfectly well what you're
! 1051: doing. Remove an internal header by giving a replacement without content on
! 1052: the right side of the colon, as in: -H \&"Host:". If you send the custom
! 1053: header with no-value then its header must be terminated with a semicolon, such
! 1054: as \-H \&"X-Custom-Header;" to send "X-Custom-Header:".
! 1055:
! 1056: curl will make sure that each header you add/replace is sent with the proper
! 1057: end-of-line marker, you should thus \fBnot\fP add that as a part of the header
! 1058: content: do not add newlines or carriage returns, they will only mess things up
! 1059: for you.
! 1060:
! 1061: Starting in 7.55.0, this option can take an argument in @filename style, which
! 1062: then adds a header for each line in the input file. Using @- will make curl
! 1063: read the header file from stdin.
! 1064:
! 1065: See also the \fI-A, --user-agent\fP and \fI-e, --referer\fP options.
! 1066:
! 1067: Starting in 7.37.0, you need \fI--proxy-header\fP to send custom headers intended
! 1068: for a proxy.
! 1069:
! 1070: Example:
! 1071:
! 1072: curl -H "X-First-Name: Joe" http://example.com/
! 1073:
! 1074: \fBWARNING\fP: headers set with this option will be set in all requests - even
! 1075: after redirects are followed, like when told with \fI-L, --location\fP. This can lead to
! 1076: the header being sent to other hosts than the original host, so sensitive
! 1077: headers should be used with caution combined with following redirects.
! 1078:
! 1079: This option can be used multiple times to add/replace/remove multiple headers.
! 1080: .IP "-h, --help"
! 1081: Usage help. This lists all current command line options with a short
! 1082: description.
! 1083: .IP "--hostpubmd5 <md5>"
! 1084: (SFTP SCP) Pass a string containing 32 hexadecimal digits. The string should
! 1085: be the 128 bit MD5 checksum of the remote host's public key, curl will refuse
! 1086: the connection with the host unless the md5sums match.
! 1087:
! 1088: Added in 7.17.1.
! 1089: .IP "--http0.9"
! 1090: (HTTP) Tells curl to be fine with HTTP version 0.9 response.
! 1091:
! 1092: HTTP/0.9 is a completely headerless response and therefore you can also
! 1093: connect with this to non-HTTP servers and still get a response since curl will
! 1094: simply transparently downgrade - if allowed.
! 1095:
! 1096: Since curl 7.66.0, HTTP/0.9 is disabled by default.
! 1097: .IP "-0, --http1.0"
! 1098: (HTTP) Tells curl to use HTTP version 1.0 instead of using its internally preferred
! 1099: HTTP version.
! 1100:
! 1101: This option overrides \fI--http1.1\fP and \fI--http2\fP.
! 1102: .IP "--http1.1"
! 1103: (HTTP) Tells curl to use HTTP version 1.1.
! 1104:
! 1105: This option overrides \fI-0, --http1.0\fP and \fI--http2\fP. Added in 7.33.0.
! 1106: .IP "--http2-prior-knowledge"
! 1107: (HTTP) Tells curl to issue its non-TLS HTTP requests using HTTP/2 without HTTP/1.1
! 1108: Upgrade. It requires prior knowledge that the server supports HTTP/2 straight
! 1109: away. HTTPS requests will still do HTTP/2 the standard way with negotiated
! 1110: protocol version in the TLS handshake.
! 1111:
! 1112: \fI--http2-prior-knowledge\fP requires that the underlying libcurl was built to support HTTP/2. This option overrides \fI--http1.1\fP and \fI-0, --http1.0\fP and \fI--http2\fP. Added in 7.49.0.
! 1113: .IP "--http2"
! 1114: (HTTP) Tells curl to use HTTP version 2.
! 1115:
! 1116: See also \fI--http1.1\fP and \fI--http3\fP. \fI--http2\fP requires that the underlying libcurl was built to support HTTP/2. This option overrides \fI--http1.1\fP and \fI-0, --http1.0\fP and \fI--http2-prior-knowledge\fP. Added in 7.33.0.
! 1117: .IP "--http3"
! 1118: (HTTP)
! 1119: WARNING: this option is experimental. Do not use in production.
! 1120:
! 1121: Tells curl to use HTTP version 3 directly to the host and port number used in
! 1122: the URL. A normal HTTP/3 transaction will be done to a host and then get
! 1123: redirected via Alt-SVc, but this option allows a user to circumvent that when
! 1124: you know that the target speaks HTTP/3 on the given host and port.
! 1125:
! 1126: This option will make curl fail if a QUIC connection cannot be established, it
! 1127: cannot fall back to a lower HTTP version on its own.
! 1128:
! 1129: See also \fI--http1.1\fP and \fI--http2\fP. \fI--http3\fP requires that the underlying libcurl was built to support HTTP/3. This option overrides \fI--http1.1\fP and \fI-0, --http1.0\fP and \fI--http2\fP and \fI--http2-prior-knowledge\fP. Added in 7.66.0.
! 1130: .IP "--ignore-content-length"
! 1131: (FTP HTTP) For HTTP, Ignore the Content-Length header. This is particularly useful for
! 1132: servers running Apache 1.x, which will report incorrect Content-Length for
! 1133: files larger than 2 gigabytes.
! 1134:
! 1135: For FTP (since 7.46.0), skip the RETR command to figure out the size before
! 1136: downloading a file.
! 1137: .IP "-i, --include"
! 1138: Include the HTTP response headers in the output. The HTTP response headers can
! 1139: include things like server name, cookies, date of the document, HTTP version
! 1140: and more...
! 1141:
! 1142: To view the request headers, consider the \fI-v, --verbose\fP option.
! 1143:
! 1144: See also \fI-v, --verbose\fP.
! 1145: .IP "-k, --insecure"
! 1146: (TLS)
! 1147: By default, every SSL connection curl makes is verified to be secure. This
! 1148: option allows curl to proceed and operate even for server connections
! 1149: otherwise considered insecure.
! 1150:
! 1151: The server connection is verified by making sure the server's certificate
! 1152: contains the right name and verifies successfully using the cert store.
! 1153:
! 1154: See this online resource for further details:
! 1155: https://curl.haxx.se/docs/sslcerts.html
! 1156:
! 1157: See also \fI--proxy-insecure\fP and \fI--cacert\fP.
! 1158: .IP "--interface <name>"
! 1159:
! 1160: Perform an operation using a specified interface. You can enter interface
! 1161: name, IP address or host name. An example could look like:
! 1162:
! 1163: curl --interface eth0:1 https://www.example.com/
! 1164:
! 1165: If this option is used several times, the last one will be used.
! 1166:
! 1167: On Linux it can be used to specify a VRF, but the binary needs to either
! 1168: have CAP_NET_RAW or to be run as root. More information about Linux VRF:
! 1169: https://www.kernel.org/doc/Documentation/networking/vrf.txt
! 1170:
! 1171: See also \fI--dns-interface\fP.
! 1172: .IP "-4, --ipv4"
! 1173: This option tells curl to resolve names to IPv4 addresses only, and not for
! 1174: example try IPv6.
! 1175:
! 1176: See also \fI--http1.1\fP and \fI--http2\fP. This option overrides \fI-6, --ipv6\fP.
! 1177: .IP "-6, --ipv6"
! 1178: This option tells curl to resolve names to IPv6 addresses only, and not for
! 1179: example try IPv4.
! 1180:
! 1181: See also \fI--http1.1\fP and \fI--http2\fP. This option overrides \fI-4, --ipv4\fP.
! 1182: .IP "-j, --junk-session-cookies"
! 1183: (HTTP) When curl is told to read cookies from a given file, this option will make it
! 1184: discard all "session cookies". This will basically have the same effect as if
! 1185: a new session is started. Typical browsers always discard session cookies when
! 1186: they're closed down.
! 1187:
! 1188: See also \fI-b, --cookie\fP and \fI-c, --cookie-jar\fP.
! 1189: .IP "--keepalive-time <seconds>"
! 1190: This option sets the time a connection needs to remain idle before sending
! 1191: keepalive probes and the time between individual keepalive probes. It is
! 1192: currently effective on operating systems offering the TCP_KEEPIDLE and
! 1193: TCP_KEEPINTVL socket options (meaning Linux, recent AIX, HP-UX and more). This
! 1194: option has no effect if \fI--no-keepalive\fP is used.
! 1195:
! 1196: If this option is used several times, the last one will be used. If
! 1197: unspecified, the option defaults to 60 seconds.
! 1198:
! 1199: Added in 7.18.0.
! 1200: .IP "--key-type <type>"
! 1201: (TLS) Private key file type. Specify which type your \fI--key\fP provided private key
! 1202: is. DER, PEM, and ENG are supported. If not specified, PEM is assumed.
! 1203:
! 1204: If this option is used several times, the last one will be used.
! 1205: .IP "--key <key>"
! 1206: (TLS SSH) Private key file name. Allows you to provide your private key in this separate
! 1207: file. For SSH, if not specified, curl tries the following candidates in order:
! 1208: \&'~/.ssh/id_rsa', '~/.ssh/id_dsa', './id_rsa', './id_dsa'.
! 1209:
! 1210: If curl is built against OpenSSL library, and the engine pkcs11 is available,
! 1211: then a PKCS#11 URI (RFC 7512) can be used to specify a private key located in a
! 1212: PKCS#11 device. A string beginning with "pkcs11:" will be interpreted as a
! 1213: PKCS#11 URI. If a PKCS#11 URI is provided, then the \fI--engine\fP option will be set
! 1214: as "pkcs11" if none was provided and the \fI--key-type\fP option will be set as
! 1215: "ENG" if none was provided.
! 1216:
! 1217: If this option is used several times, the last one will be used.
! 1218: .IP "--krb <level>"
! 1219: (FTP) Enable Kerberos authentication and use. The level must be entered and should
! 1220: be one of 'clear', 'safe', 'confidential', or 'private'. Should you use a
! 1221: level that is not one of these, 'private' will instead be used.
! 1222:
! 1223: If this option is used several times, the last one will be used.
! 1224:
! 1225: \fI--krb\fP requires that the underlying libcurl was built to support Kerberos.
! 1226: .IP "--libcurl <file>"
! 1227: Append this option to any ordinary curl command line, and you will get a
! 1228: libcurl-using C source code written to the file that does the equivalent
! 1229: of what your command-line operation does!
! 1230:
! 1231: If this option is used several times, the last given file name will be
! 1232: used.
! 1233:
! 1234: Added in 7.16.1.
! 1235: .IP "--limit-rate <speed>"
! 1236: Specify the maximum transfer rate you want curl to use - for both downloads
! 1237: and uploads. This feature is useful if you have a limited pipe and you'd like
! 1238: your transfer not to use your entire bandwidth. To make it slower than it
! 1239: otherwise would be.
! 1240:
! 1241: The given speed is measured in bytes/second, unless a suffix is appended.
! 1242: Appending 'k' or 'K' will count the number as kilobytes, 'm' or 'M' makes it
! 1243: megabytes, while 'g' or 'G' makes it gigabytes. Examples: 200K, 3m and 1G.
! 1244:
! 1245: If you also use the \fI-Y, --speed-limit\fP option, that option will take precedence and
! 1246: might cripple the rate-limiting slightly, to help keeping the speed-limit
! 1247: logic working.
! 1248:
! 1249: If this option is used several times, the last one will be used.
! 1250: .IP "-l, --list-only"
! 1251: (FTP POP3) (FTP)
! 1252: When listing an FTP directory, this switch forces a name-only view. This is
! 1253: especially useful if the user wants to machine-parse the contents of an FTP
! 1254: directory since the normal directory view doesn't use a standard look or
! 1255: format. When used like this, the option causes a NLST command to be sent to
! 1256: the server instead of LIST.
! 1257:
! 1258: Note: Some FTP servers list only files in their response to NLST; they do not
! 1259: include sub-directories and symbolic links.
! 1260:
! 1261: (POP3)
! 1262: When retrieving a specific email from POP3, this switch forces a LIST command
! 1263: to be performed instead of RETR. This is particularly useful if the user wants
! 1264: to see if a specific message id exists on the server and what size it is.
! 1265:
! 1266: Note: When combined with \fI-X, --request\fP, this option can be used to send an UIDL
! 1267: command instead, so the user may use the email's unique identifier rather than
! 1268: it's message id to make the request.
! 1269:
! 1270: Added in 7.21.5.
! 1271: .IP "--local-port <num/range>"
! 1272: Set a preferred single number or range (FROM-TO) of local port numbers to use
! 1273: for the connection(s). Note that port numbers by nature are a scarce resource
! 1274: that will be busy at times so setting this range to something too narrow might
! 1275: cause unnecessary connection setup failures.
! 1276:
! 1277: Added in 7.15.2.
! 1278: .IP "--location-trusted"
! 1279: (HTTP) Like \fI-L, --location\fP, but will allow sending the name + password to all hosts that
! 1280: the site may redirect to. This may or may not introduce a security breach if
! 1281: the site redirects you to a site to which you'll send your authentication info
! 1282: (which is plaintext in the case of HTTP Basic authentication).
! 1283:
! 1284: See also \fI-u, --user\fP.
! 1285: .IP "-L, --location"
! 1286: (HTTP) If the server reports that the requested page has moved to a different
! 1287: location (indicated with a Location: header and a 3XX response code), this
! 1288: option will make curl redo the request on the new place. If used together with
! 1289: \fI-i, --include\fP or \fI-I, --head\fP, headers from all requested pages will be shown. When
! 1290: authentication is used, curl only sends its credentials to the initial
! 1291: host. If a redirect takes curl to a different host, it won't be able to
! 1292: intercept the user+password. See also \fI--location-trusted\fP on how to change
! 1293: this. You can limit the amount of redirects to follow by using the
! 1294: \fI--max-redirs\fP option.
! 1295:
! 1296: When curl follows a redirect and if the request is a POST, it will do the
! 1297: following request with a GET if the HTTP response was 301, 302, or 303. If the
! 1298: response code was any other 3xx code, curl will re-send the following request
! 1299: using the same unmodified method.
! 1300:
! 1301: You can tell curl to not change POST requests to GET after a 30x response by
! 1302: using the dedicated options for that: \fI--post301\fP, \fI--post302\fP and \fI--post303\fP.
! 1303:
! 1304: The method set with \fI-X, --request\fP overrides the method curl would otherwise select
! 1305: to use.
! 1306: .IP "--login-options <options>"
! 1307: (IMAP POP3 SMTP) Specify the login options to use during server authentication.
! 1308:
! 1309: You can use the login options to specify protocol specific options that may
! 1310: be used during authentication. At present only IMAP, POP3 and SMTP support
! 1311: login options. For more information about the login options please see
! 1312: RFC 2384, RFC 5092 and IETF draft draft-earhart-url-smtp-00.txt
! 1313:
! 1314: If this option is used several times, the last one will be used.
! 1315:
! 1316: Added in 7.34.0.
! 1317: .IP "--mail-auth <address>"
! 1318: (SMTP) Specify a single address. This will be used to specify the authentication
! 1319: address (identity) of a submitted message that is being relayed to another
! 1320: server.
! 1321:
! 1322: See also \fI--mail-rcpt\fP and \fI--mail-from\fP. Added in 7.25.0.
! 1323: .IP "--mail-from <address>"
! 1324: (SMTP) Specify a single address that the given mail should get sent from.
! 1325:
! 1326: See also \fI--mail-rcpt\fP and \fI--mail-auth\fP. Added in 7.20.0.
! 1327: .IP "--mail-rcpt-allowfails"
! 1328: (SMTP) When sending data to multiple recipients, by default curl will abort SMTP
! 1329: conversation if at least one of the recipients causes RCPT TO command to
! 1330: return an error.
! 1331:
! 1332: The default behavior can be changed by passing \fI--mail-rcpt-allowfails\fP
! 1333: command-line option which will make curl ignore errors and proceed with the
! 1334: remaining valid recipients.
! 1335:
! 1336: In case when all recipients cause RCPT TO command to fail, curl will abort SMTP
! 1337: conversation and return the error received from to the last RCPT TO command.
! 1338: Added in 7.69.0.
! 1339: .IP "--mail-rcpt <address>"
! 1340: (SMTP) Specify a single address, user name or mailing list name. Repeat this
! 1341: option several times to send to multiple recipients.
! 1342:
! 1343: When performing a mail transfer, the recipient should specify a valid email
! 1344: address to send the mail to.
! 1345:
! 1346: When performing an address verification (VRFY command), the recipient should be
! 1347: specified as the user name or user name and domain (as per Section 3.5 of
! 1348: RFC5321). (Added in 7.34.0)
! 1349:
! 1350: When performing a mailing list expand (EXPN command), the recipient should be
! 1351: specified using the mailing list name, such as "Friends" or "London-Office".
! 1352: (Added in 7.34.0)
! 1353:
! 1354: Added in 7.20.0.
! 1355: .IP "-M, --manual"
! 1356: Manual. Display the huge help text.
! 1357: .IP "--max-filesize <bytes>"
! 1358: Specify the maximum size (in bytes) of a file to download. If the file
! 1359: requested is larger than this value, the transfer will not start and curl will
! 1360: return with exit code 63.
! 1361:
! 1362: A size modifier may be used. For example, Appending 'k' or 'K' will count the
! 1363: number as kilobytes, 'm' or 'M' makes it megabytes, while 'g' or 'G' makes it
! 1364: gigabytes. Examples: 200K, 3m and 1G. (Added in 7.58.0)
! 1365:
! 1366: \fBNOTE:\fP The file size is not always known prior to download, and for such
! 1367: files this option has no effect even if the file transfer ends up being larger
! 1368: than this given limit. This concerns both FTP and HTTP transfers.
! 1369:
! 1370: See also \fI--limit-rate\fP.
! 1371: .IP "--max-redirs <num>"
! 1372: (HTTP) Set maximum number of redirection-followings allowed. When \fI-L, --location\fP is used,
! 1373: is used to prevent curl from following redirections too much. By default, the
! 1374: limit is set to 50 redirections. Set this option to -1 to make it unlimited.
! 1375:
! 1376: If this option is used several times, the last one will be used.
! 1377: .IP "-m, --max-time <seconds>"
! 1378: Maximum time in seconds that you allow the whole operation to take. This is
! 1379: useful for preventing your batch jobs from hanging for hours due to slow
! 1380: networks or links going down. Since 7.32.0, this option accepts decimal
! 1381: values, but the actual timeout will decrease in accuracy as the specified
! 1382: timeout increases in decimal precision.
! 1383:
! 1384: If this option is used several times, the last one will be used.
! 1385:
! 1386: See also \fI--connect-timeout\fP.
! 1387: .IP "--metalink"
! 1388: This option can tell curl to parse and process a given URI as Metalink file
! 1389: (both version 3 and 4 (RFC 5854) are supported) and make use of the mirrors
! 1390: listed within for failover if there are errors (such as the file or server not
! 1391: being available). It will also verify the hash of the file after the download
! 1392: completes. The Metalink file itself is downloaded and processed in memory and
! 1393: not stored in the local file system.
! 1394:
! 1395: Example to use a remote Metalink file:
! 1396:
! 1397: curl --metalink http://www.example.com/example.metalink
! 1398:
! 1399: To use a Metalink file in the local file system, use FILE protocol (file://):
! 1400:
! 1401: curl --metalink file://example.metalink
! 1402:
! 1403: Please note that if FILE protocol is disabled, there is no way to use a local
! 1404: Metalink file at the time of this writing. Also note that if \fI--metalink\fP and
! 1405: \fI-i, --include\fP are used together, --include will be ignored. This is because
! 1406: including headers in the response will break Metalink parser and if the
! 1407: headers are included in the file described in Metalink file, hash check will
! 1408: fail.
! 1409:
! 1410: \fI--metalink\fP requires that the underlying libcurl was built to support metalink. Added in 7.27.0.
! 1411: .IP "--negotiate"
! 1412: (HTTP) Enables Negotiate (SPNEGO) authentication.
! 1413:
! 1414: This option requires a library built with GSS-API or SSPI support. Use
! 1415: \fI-V, --version\fP to see if your curl supports GSS-API/SSPI or SPNEGO.
! 1416:
! 1417: When using this option, you must also provide a fake \fI-u, --user\fP option to activate
! 1418: the authentication code properly. Sending a '-u :' is enough as the user name
! 1419: and password from the \fI-u, --user\fP option aren't actually used.
! 1420:
! 1421: If this option is used several times, only the first one is used.
! 1422:
! 1423: See also \fI--basic\fP and \fI--ntlm\fP and \fI--anyauth\fP and \fI--proxy-negotiate\fP.
! 1424: .IP "--netrc-file <filename>"
! 1425: This option is similar to \fI-n, --netrc\fP, except that you provide the path (absolute
! 1426: or relative) to the netrc file that curl should use. You can only specify one
! 1427: netrc file per invocation. If several \fI--netrc-file\fP options are provided,
! 1428: the last one will be used.
! 1429:
! 1430: It will abide by \fI--netrc-optional\fP if specified.
! 1431:
! 1432: This option overrides \fI-n, --netrc\fP. Added in 7.21.5.
! 1433: .IP "--netrc-optional"
! 1434: Very similar to \fI-n, --netrc\fP, but this option makes the .netrc usage \fBoptional\fP
! 1435: and not mandatory as the \fI-n, --netrc\fP option does.
! 1436:
! 1437: See also \fI--netrc-file\fP. This option overrides \fI-n, --netrc\fP.
! 1438: .IP "-n, --netrc"
! 1439: Makes curl scan the \fI.netrc\fP (\fI_netrc\fP on Windows) file in the user's
! 1440: home directory for login name and password. This is typically used for FTP on
! 1441: Unix. If used with HTTP, curl will enable user authentication. See
! 1442: \fInetrc(5)\fP \fIftp(1)\fP for details on the file format. Curl will not
! 1443: complain if that file doesn't have the right permissions (it should not be
! 1444: either world- or group-readable). The environment variable "HOME" is used to
! 1445: find the home directory.
! 1446:
! 1447: A quick and very simple example of how to setup a \fI.netrc\fP to allow curl
! 1448: to FTP to the machine host.domain.com with user name \&'myself' and password
! 1449: \&'secret' should look similar to:
! 1450:
! 1451: .B "machine host.domain.com login myself password secret"
! 1452: .IP "-:, --next"
! 1453: Tells curl to use a separate operation for the following URL and associated
! 1454: options. This allows you to send several URL requests, each with their own
! 1455: specific options, for example, such as different user names or custom requests
! 1456: for each.
! 1457:
! 1458: \fI-:, --next\fP will reset all local options and only global ones will have their
! 1459: values survive over to the operation following the \fI-:, --next\fP instruction. Global
! 1460: options include \fI-v, --verbose\fP, \fI--trace\fP, \fI--trace-ascii\fP and \fI--fail-early\fP.
! 1461:
! 1462: For example, you can do both a GET and a POST in a single command line:
! 1463:
! 1464: curl www1.example.com --next -d postthis www2.example.com
! 1465:
! 1466: Added in 7.36.0.
! 1467: .IP "--no-alpn"
! 1468: (HTTPS) Disable the ALPN TLS extension. ALPN is enabled by default if libcurl was built
! 1469: with an SSL library that supports ALPN. ALPN is used by a libcurl that supports
! 1470: HTTP/2 to negotiate HTTP/2 support with the server during https sessions.
! 1471:
! 1472: See also \fI--no-npn\fP and \fI--http2\fP. \fI--no-alpn\fP requires that the underlying libcurl was built to support TLS. Added in 7.36.0.
! 1473: .IP "-N, --no-buffer"
! 1474: Disables the buffering of the output stream. In normal work situations, curl
! 1475: will use a standard buffered output stream that will have the effect that it
! 1476: will output the data in chunks, not necessarily exactly when the data arrives.
! 1477: Using this option will disable that buffering.
! 1478:
! 1479: Note that this is the negated option name documented. You can thus use
! 1480: --buffer to enforce the buffering.
! 1481: .IP "--no-keepalive"
! 1482: Disables the use of keepalive messages on the TCP connection. curl otherwise
! 1483: enables them by default.
! 1484:
! 1485: Note that this is the negated option name documented. You can thus use
! 1486: --keepalive to enforce keepalive.
! 1487: .IP "--no-npn"
! 1488: (HTTPS) Disable the NPN TLS extension. NPN is enabled by default if libcurl was built
! 1489: with an SSL library that supports NPN. NPN is used by a libcurl that supports
! 1490: HTTP/2 to negotiate HTTP/2 support with the server during https sessions.
! 1491:
! 1492: See also \fI--no-alpn\fP and \fI--http2\fP. \fI--no-npn\fP requires that the underlying libcurl was built to support TLS. Added in 7.36.0.
! 1493: .IP "--no-progress-meter"
! 1494: Option to switch off the progress meter output without muting or otherwise
! 1495: affecting warning and informational messages like \fI-s, --silent\fP does.
! 1496:
! 1497: Note that this is the negated option name documented. You can thus use
! 1498: --progress-meter to enable the progress meter again.
! 1499:
! 1500: See also \fI-v, --verbose\fP and \fI-s, --silent\fP. Added in 7.67.0.
! 1501: .IP "--no-sessionid"
! 1502: (TLS) Disable curl's use of SSL session-ID caching. By default all transfers are
! 1503: done using the cache. Note that while nothing should ever get hurt by
! 1504: attempting to reuse SSL session-IDs, there seem to be broken SSL
! 1505: implementations in the wild that may require you to disable this in order for
! 1506: you to succeed.
! 1507:
! 1508: Note that this is the negated option name documented. You can thus use
! 1509: --sessionid to enforce session-ID caching.
! 1510:
! 1511: Added in 7.16.0.
! 1512: .IP "--noproxy <no-proxy-list>"
! 1513: Comma-separated list of hosts which do not use a proxy, if one is specified.
! 1514: The only wildcard is a single * character, which matches all hosts, and
! 1515: effectively disables the proxy. Each name in this list is matched as either
! 1516: a domain which contains the hostname, or the hostname itself. For example,
! 1517: local.com would match local.com, local.com:80, and www.local.com, but not
! 1518: www.notlocal.com.
! 1519:
! 1520: Since 7.53.0, This option overrides the environment variables that disable the
! 1521: proxy. If there's an environment variable disabling a proxy, you can set
! 1522: noproxy list to \&"" to override it.
! 1523:
! 1524: Added in 7.19.4.
! 1525: .IP "--ntlm-wb"
! 1526: (HTTP) Enables NTLM much in the style \fI--ntlm\fP does, but hand over the authentication
! 1527: to the separate binary ntlmauth application that is executed when needed.
! 1528:
! 1529: See also \fI--ntlm\fP and \fI--proxy-ntlm\fP.
! 1530: .IP "--ntlm"
! 1531: (HTTP) Enables NTLM authentication. The NTLM authentication method was designed by
! 1532: Microsoft and is used by IIS web servers. It is a proprietary protocol,
! 1533: reverse-engineered by clever people and implemented in curl based on their
! 1534: efforts. This kind of behavior should not be endorsed, you should encourage
! 1535: everyone who uses NTLM to switch to a public and documented authentication
! 1536: method instead, such as Digest.
! 1537:
! 1538: If you want to enable NTLM for your proxy authentication, then use
! 1539: \fI--proxy-ntlm\fP.
! 1540:
! 1541: If this option is used several times, only the first one is used.
! 1542:
! 1543: See also \fI--proxy-ntlm\fP. \fI--ntlm\fP requires that the underlying libcurl was built to support TLS. This option overrides \fI--basic\fP and \fI--negotiate\fP and \fI--digest\fP and \fI--anyauth\fP.
! 1544: .IP "--oauth2-bearer <token>"
! 1545: (IMAP POP3 SMTP HTTP) Specify the Bearer Token for OAUTH 2.0 server authentication. The Bearer Token
! 1546: is used in conjunction with the user name which can be specified as part of
! 1547: the \fI--url\fP or \fI-u, --user\fP options.
! 1548:
! 1549: The Bearer Token and user name are formatted according to RFC 6750.
! 1550:
! 1551: If this option is used several times, the last one will be used.
! 1552: .IP "-o, --output <file>"
! 1553: Write output to <file> instead of stdout. If you are using {} or [] to fetch
! 1554: multiple documents, you should quote the URL and you can use '#' followed by a
! 1555: number in the <file> specifier. That variable will be replaced with the current
! 1556: string for the URL being fetched. Like in:
! 1557:
! 1558: curl "http://{one,two}.example.com" -o "file_#1.txt"
! 1559:
! 1560: or use several variables like:
! 1561:
! 1562: curl "http://{site,host}.host[1-5].com" -o "#1_#2"
! 1563:
! 1564: You may use this option as many times as the number of URLs you have. For
! 1565: example, if you specify two URLs on the same command line, you can use it like
! 1566: this:
! 1567:
! 1568: curl -o aa example.com -o bb example.net
! 1569:
! 1570: and the order of the -o options and the URLs doesn't matter, just that the
! 1571: first -o is for the first URL and so on, so the above command line can also be
! 1572: written as
! 1573:
! 1574: curl example.com example.net -o aa -o bb
! 1575:
! 1576: See also the \fI--create-dirs\fP option to create the local directories
! 1577: dynamically. Specifying the output as '-' (a single dash) will force the
! 1578: output to be done to stdout.
! 1579:
! 1580: See also \fI-O, --remote-name\fP and \fI--remote-name-all\fP and \fI-J, --remote-header-name\fP.
! 1581: .IP "--parallel-immediate"
! 1582: When doing parallel transfers, this option will instruct curl that it should
! 1583: rather prefer opening up more connections in parallel at once rather than
! 1584: waiting to see if new transfers can be added as multiplexed streams on another
! 1585: connection.
! 1586:
! 1587: See also \fI-Z, --parallel\fP and \fI--parallel-max\fP. Added in 7.68.0.
! 1588: .IP "--parallel-max"
! 1589: When asked to do parallel transfers, using \fI-Z, --parallel\fP, this option controls
! 1590: the maximum amount of transfers to do simultaneously.
! 1591:
! 1592: The default is 50.
! 1593:
! 1594: See also \fI-Z, --parallel\fP. Added in 7.66.0.
! 1595: .IP "-Z, --parallel"
! 1596: Makes curl perform its transfers in parallel as compared to the regular serial
! 1597: manner.
! 1598:
! 1599: Added in 7.66.0.
! 1600: .IP "--pass <phrase>"
! 1601: (SSH TLS) Passphrase for the private key
! 1602:
! 1603: If this option is used several times, the last one will be used.
! 1604: .IP "--path-as-is"
! 1605: Tell curl to not handle sequences of /../ or /./ in the given URL
! 1606: path. Normally curl will squash or merge them according to standards but with
! 1607: this option set you tell it not to do that.
! 1608:
! 1609: Added in 7.42.0.
! 1610: .IP "--pinnedpubkey <hashes>"
! 1611: (TLS) Tells curl to use the specified public key file (or hashes) to verify the
! 1612: peer. This can be a path to a file which contains a single public key in PEM
! 1613: or DER format, or any number of base64 encoded sha256 hashes preceded by
! 1614: \'sha256//\' and separated by \';\'
! 1615:
! 1616: When negotiating a TLS or SSL connection, the server sends a certificate
! 1617: indicating its identity. A public key is extracted from this certificate and
! 1618: if it does not exactly match the public key provided to this option, curl will
! 1619: abort the connection before sending or receiving any data.
! 1620:
! 1621: PEM/DER support:
! 1622: 7.39.0: OpenSSL, GnuTLS and GSKit
! 1623: 7.43.0: NSS and wolfSSL
! 1624: 7.47.0: mbedtls
! 1625: sha256 support:
! 1626: 7.44.0: OpenSSL, GnuTLS, NSS and wolfSSL
! 1627: 7.47.0: mbedtls
! 1628: Other SSL backends not supported.
! 1629:
! 1630: If this option is used several times, the last one will be used.
! 1631: .IP "--post301"
! 1632: (HTTP) Tells curl to respect RFC 7231/6.4.2 and not convert POST requests into GET
! 1633: requests when following a 301 redirection. The non-RFC behaviour is ubiquitous
! 1634: in web browsers, so curl does the conversion by default to maintain
! 1635: consistency. However, a server may require a POST to remain a POST after such
! 1636: a redirection. This option is meaningful only when using \fI-L, --location\fP.
! 1637:
! 1638: See also \fI--post302\fP and \fI--post303\fP and \fI-L, --location\fP. Added in 7.17.1.
! 1639: .IP "--post302"
! 1640: (HTTP) Tells curl to respect RFC 7231/6.4.3 and not convert POST requests into GET
! 1641: requests when following a 302 redirection. The non-RFC behaviour is ubiquitous
! 1642: in web browsers, so curl does the conversion by default to maintain
! 1643: consistency. However, a server may require a POST to remain a POST after such
! 1644: a redirection. This option is meaningful only when using \fI-L, --location\fP.
! 1645:
! 1646: See also \fI--post301\fP and \fI--post303\fP and \fI-L, --location\fP. Added in 7.19.1.
! 1647: .IP "--post303"
! 1648: (HTTP) Tells curl to violate RFC 7231/6.4.4 and not convert POST requests into GET
! 1649: requests when following 303 redirections. A server may require a POST to
! 1650: remain a POST after a 303 redirection. This option is meaningful only when
! 1651: using \fI-L, --location\fP.
! 1652:
! 1653: See also \fI--post302\fP and \fI--post301\fP and \fI-L, --location\fP. Added in 7.26.0.
! 1654: .IP "--preproxy [protocol://]host[:port]"
! 1655: Use the specified SOCKS proxy before connecting to an HTTP or HTTPS \fI-x, --proxy\fP. In
! 1656: such a case curl first connects to the SOCKS proxy and then connects (through
! 1657: SOCKS) to the HTTP or HTTPS proxy. Hence pre proxy.
! 1658:
! 1659: The pre proxy string should be specified with a protocol:// prefix to specify
! 1660: alternative proxy protocols. Use socks4://, socks4a://, socks5:// or
! 1661: socks5h:// to request the specific SOCKS version to be used. No protocol
! 1662: specified will make curl default to SOCKS4.
! 1663:
! 1664: If the port number is not specified in the proxy string, it is assumed to be
! 1665: 1080.
! 1666:
! 1667: User and password that might be provided in the proxy string are URL decoded
! 1668: by curl. This allows you to pass in special characters such as @ by using %40
! 1669: or pass in a colon with %3a.
! 1670:
! 1671: If this option is used several times, the last one will be used.
! 1672:
! 1673: Added in 7.52.0.
! 1674: .IP "-#, --progress-bar"
! 1675: Make curl display transfer progress as a simple progress bar instead of the
! 1676: standard, more informational, meter.
! 1677:
! 1678: This progress bar draws a single line of '#' characters across the screen and
! 1679: shows a percentage if the transfer size is known. For transfers without a
! 1680: known size, there will be space ship (-=o=-) that moves back and forth but
! 1681: only while data is being transferred, with a set of flying hash sign symbols on
! 1682: top.
! 1683: .IP "--proto-default <protocol>"
! 1684: Tells curl to use \fIprotocol\fP for any URL missing a scheme name.
! 1685:
! 1686: Example:
! 1687:
! 1688: curl --proto-default https ftp.mozilla.org
! 1689:
! 1690: An unknown or unsupported protocol causes error
! 1691: \fICURLE_UNSUPPORTED_PROTOCOL\fP (1).
! 1692:
! 1693: This option does not change the default proxy protocol (http).
! 1694:
! 1695: Without this option curl would make a guess based on the host, see \fI--url\fP for
! 1696: details.
! 1697:
! 1698: Added in 7.45.0.
! 1699: .IP "--proto-redir <protocols>"
! 1700: Tells curl to limit what protocols it may use on redirect. Protocols denied by
! 1701: \fI--proto\fP are not overridden by this option. See --proto for how protocols are
! 1702: represented.
! 1703:
! 1704: Example, allow only HTTP and HTTPS on redirect:
! 1705:
! 1706: curl --proto-redir -all,http,https http://example.com
! 1707:
! 1708: By default curl will allow HTTP, HTTPS, FTP and FTPS on redirect (7.65.2).
! 1709: Older versions of curl allowed all protocols on redirect except several
! 1710: disabled for security reasons: Since 7.19.4 FILE and SCP are disabled, and
! 1711: since 7.40.0 SMB and SMBS are also disabled. Specifying \fIall\fP or \fI+all\fP
! 1712: enables all protocols on redirect, including those disabled for security.
! 1713:
! 1714: Added in 7.20.2.
! 1715: .IP "--proto <protocols>"
! 1716: Tells curl to limit what protocols it may use in the transfer. Protocols are
! 1717: evaluated left to right, are comma separated, and are each a protocol name or
! 1718: \&'all', optionally prefixed by zero or more modifiers. Available modifiers are:
! 1719: .RS
! 1720: .TP 3
! 1721: .B +
! 1722: Permit this protocol in addition to protocols already permitted (this is
! 1723: the default if no modifier is used).
! 1724: .TP
! 1725: .B -
! 1726: Deny this protocol, removing it from the list of protocols already permitted.
! 1727: .TP
! 1728: .B =
! 1729: Permit only this protocol (ignoring the list already permitted), though
! 1730: subject to later modification by subsequent entries in the comma separated
! 1731: list.
! 1732: .RE
! 1733: .IP
! 1734: For example:
! 1735: .RS
! 1736: .TP 15
! 1737: .B \fI--proto\fP -ftps
! 1738: uses the default protocols, but disables ftps
! 1739: .TP
! 1740: .B \fI--proto\fP -all,https,+http
! 1741: only enables http and https
! 1742: .TP
! 1743: .B \fI--proto\fP =http,https
! 1744: also only enables http and https
! 1745: .RE
! 1746:
! 1747: Unknown protocols produce a warning. This allows scripts to safely rely on
! 1748: being able to disable potentially dangerous protocols, without relying upon
! 1749: support for that protocol being built into curl to avoid an error.
! 1750:
! 1751: This option can be used multiple times, in which case the effect is the same
! 1752: as concatenating the protocols into one instance of the option.
! 1753:
! 1754: See also \fI--proto-redir\fP and \fI--proto-default\fP. Added in 7.20.2.
! 1755: .IP "--proxy-anyauth"
! 1756: Tells curl to pick a suitable authentication method when communicating with
! 1757: the given HTTP proxy. This might cause an extra request/response round-trip.
! 1758:
! 1759: See also \fI-x, --proxy\fP and \fI--proxy-basic\fP and \fI--proxy-digest\fP. Added in 7.13.2.
! 1760: .IP "--proxy-basic"
! 1761: Tells curl to use HTTP Basic authentication when communicating with the given
! 1762: proxy. Use \fI--basic\fP for enabling HTTP Basic with a remote host. Basic is the
! 1763: default authentication method curl uses with proxies.
! 1764:
! 1765: See also \fI-x, --proxy\fP and \fI--proxy-anyauth\fP and \fI--proxy-digest\fP.
! 1766: .IP "--proxy-cacert <file>"
! 1767: Same as \fI--cacert\fP but used in HTTPS proxy context.
! 1768:
! 1769: See also \fI--proxy-capath\fP and \fI--cacert\fP and \fI--capath\fP and \fI-x, --proxy\fP. Added in 7.52.0.
! 1770: .IP "--proxy-capath <dir>"
! 1771: Same as \fI--capath\fP but used in HTTPS proxy context.
! 1772:
! 1773: See also \fI--proxy-cacert\fP and \fI-x, --proxy\fP and \fI--capath\fP. Added in 7.52.0.
! 1774: .IP "--proxy-cert-type <type>"
! 1775: Same as \fI--cert-type\fP but used in HTTPS proxy context.
! 1776:
! 1777: Added in 7.52.0.
! 1778: .IP "--proxy-cert <cert[:passwd]>"
! 1779: Same as \fI-E, --cert\fP but used in HTTPS proxy context.
! 1780:
! 1781: Added in 7.52.0.
! 1782: .IP "--proxy-ciphers <list>"
! 1783: Same as \fI--ciphers\fP but used in HTTPS proxy context.
! 1784:
! 1785: Added in 7.52.0.
! 1786: .IP "--proxy-crlfile <file>"
! 1787: Same as \fI--crlfile\fP but used in HTTPS proxy context.
! 1788:
! 1789: Added in 7.52.0.
! 1790: .IP "--proxy-digest"
! 1791: Tells curl to use HTTP Digest authentication when communicating with the given
! 1792: proxy. Use \fI--digest\fP for enabling HTTP Digest with a remote host.
! 1793:
! 1794: See also \fI-x, --proxy\fP and \fI--proxy-anyauth\fP and \fI--proxy-basic\fP.
! 1795: .IP "--proxy-header <header/@file>"
! 1796: (HTTP) Extra header to include in the request when sending HTTP to a proxy. You may
! 1797: specify any number of extra headers. This is the equivalent option to \fI-H, --header\fP
! 1798: but is for proxy communication only like in CONNECT requests when you want a
! 1799: separate header sent to the proxy to what is sent to the actual remote host.
! 1800:
! 1801: curl will make sure that each header you add/replace is sent with the proper
! 1802: end-of-line marker, you should thus \fBnot\fP add that as a part of the header
! 1803: content: do not add newlines or carriage returns, they will only mess things
! 1804: up for you.
! 1805:
! 1806: Headers specified with this option will not be included in requests that curl
! 1807: knows will not be sent to a proxy.
! 1808:
! 1809: Starting in 7.55.0, this option can take an argument in @filename style, which
! 1810: then adds a header for each line in the input file. Using @- will make curl
! 1811: read the header file from stdin.
! 1812:
! 1813: This option can be used multiple times to add/replace/remove multiple headers.
! 1814:
! 1815: Added in 7.37.0.
! 1816: .IP "--proxy-insecure"
! 1817: Same as \fI-k, --insecure\fP but used in HTTPS proxy context.
! 1818:
! 1819: Added in 7.52.0.
! 1820: .IP "--proxy-key-type <type>"
! 1821: Same as \fI--key-type\fP but used in HTTPS proxy context.
! 1822:
! 1823: Added in 7.52.0.
! 1824: .IP "--proxy-key <key>"
! 1825: Same as \fI--key\fP but used in HTTPS proxy context.
! 1826: .IP "--proxy-negotiate"
! 1827: Tells curl to use HTTP Negotiate (SPNEGO) authentication when communicating
! 1828: with the given proxy. Use \fI--negotiate\fP for enabling HTTP Negotiate (SPNEGO)
! 1829: with a remote host.
! 1830:
! 1831: See also \fI--proxy-anyauth\fP and \fI--proxy-basic\fP. Added in 7.17.1.
! 1832: .IP "--proxy-ntlm"
! 1833: Tells curl to use HTTP NTLM authentication when communicating with the given
! 1834: proxy. Use \fI--ntlm\fP for enabling NTLM with a remote host.
! 1835:
! 1836: See also \fI--proxy-negotiate\fP and \fI--proxy-anyauth\fP.
! 1837: .IP "--proxy-pass <phrase>"
! 1838: Same as \fI--pass\fP but used in HTTPS proxy context.
! 1839:
! 1840: Added in 7.52.0.
! 1841: .IP "--proxy-pinnedpubkey <hashes>"
! 1842: (TLS) Tells curl to use the specified public key file (or hashes) to verify the
! 1843: proxy. This can be a path to a file which contains a single public key in PEM
! 1844: or DER format, or any number of base64 encoded sha256 hashes preceded by
! 1845: \'sha256//\' and separated by \';\'
! 1846:
! 1847: When negotiating a TLS or SSL connection, the server sends a certificate
! 1848: indicating its identity. A public key is extracted from this certificate and
! 1849: if it does not exactly match the public key provided to this option, curl will
! 1850: abort the connection before sending or receiving any data.
! 1851:
! 1852: If this option is used several times, the last one will be used.
! 1853: .IP "--proxy-service-name <name>"
! 1854: This option allows you to change the service name for proxy negotiation.
! 1855:
! 1856: Added in 7.43.0.
! 1857: .IP "--proxy-ssl-allow-beast"
! 1858: Same as \fI--ssl-allow-beast\fP but used in HTTPS proxy context.
! 1859:
! 1860: Added in 7.52.0.
! 1861: .IP "--proxy-tls13-ciphers <ciphersuite list>"
! 1862: (TLS) Specifies which cipher suites to use in the connection to your HTTPS proxy
! 1863: when it negotiates TLS 1.3. The list of ciphers suites must specify valid
! 1864: ciphers. Read up on TLS 1.3 cipher suite details on this URL:
! 1865:
! 1866: https://curl.haxx.se/docs/ssl-ciphers.html
! 1867:
! 1868: This option is currently used only when curl is built to use OpenSSL 1.1.1 or
! 1869: later. If you are using a different SSL backend you can try setting TLS 1.3
! 1870: cipher suites by using the \fI--proxy-ciphers\fP option.
! 1871:
! 1872: If this option is used several times, the last one will be used.
! 1873: .IP "--proxy-tlsauthtype <type>"
! 1874: Same as \fI--tlsauthtype\fP but used in HTTPS proxy context.
! 1875:
! 1876: Added in 7.52.0.
! 1877: .IP "--proxy-tlspassword <string>"
! 1878: Same as \fI--tlspassword\fP but used in HTTPS proxy context.
! 1879:
! 1880: Added in 7.52.0.
! 1881: .IP "--proxy-tlsuser <name>"
! 1882: Same as \fI--tlsuser\fP but used in HTTPS proxy context.
! 1883:
! 1884: Added in 7.52.0.
! 1885: .IP "--proxy-tlsv1"
! 1886: Same as \fI-1, --tlsv1\fP but used in HTTPS proxy context.
! 1887:
! 1888: Added in 7.52.0.
! 1889: .IP "-U, --proxy-user <user:password>"
! 1890: Specify the user name and password to use for proxy authentication.
! 1891:
! 1892: If you use a Windows SSPI-enabled curl binary and do either Negotiate or NTLM
! 1893: authentication then you can tell curl to select the user name and password
! 1894: from your environment by specifying a single colon with this option: "-U :".
! 1895:
! 1896: On systems where it works, curl will hide the given option argument from
! 1897: process listings. This is not enough to protect credentials from possibly
! 1898: getting seen by other users on the same system as they will still be visible
! 1899: for a brief moment before cleared. Such sensitive data should be retrieved
! 1900: from a file instead or similar and never used in clear text in a command line.
! 1901:
! 1902: If this option is used several times, the last one will be used.
! 1903: .IP "-x, --proxy [protocol://]host[:port]"
! 1904: Use the specified proxy.
! 1905:
! 1906: The proxy string can be specified with a protocol:// prefix. No protocol
! 1907: specified or http:// will be treated as HTTP proxy. Use socks4://, socks4a://,
! 1908: socks5:// or socks5h:// to request a specific SOCKS version to be used.
! 1909: (The protocol support was added in curl 7.21.7)
! 1910:
! 1911: HTTPS proxy support via https:// protocol prefix was added in 7.52.0 for
! 1912: OpenSSL, GnuTLS and NSS.
! 1913:
! 1914: Unrecognized and unsupported proxy protocols cause an error since 7.52.0.
! 1915: Prior versions may ignore the protocol and use http:// instead.
! 1916:
! 1917: If the port number is not specified in the proxy string, it is assumed to be
! 1918: 1080.
! 1919:
! 1920: This option overrides existing environment variables that set the proxy to
! 1921: use. If there's an environment variable setting a proxy, you can set proxy to
! 1922: \&"" to override it.
! 1923:
! 1924: All operations that are performed over an HTTP proxy will transparently be
! 1925: converted to HTTP. It means that certain protocol specific operations might
! 1926: not be available. This is not the case if you can tunnel through the proxy, as
! 1927: one with the \fI-p, --proxytunnel\fP option.
! 1928:
! 1929: User and password that might be provided in the proxy string are URL decoded
! 1930: by curl. This allows you to pass in special characters such as @ by using %40
! 1931: or pass in a colon with %3a.
! 1932:
! 1933: The proxy host can be specified the exact same way as the proxy environment
! 1934: variables, including the protocol prefix (http://) and the embedded user +
! 1935: password.
! 1936:
! 1937: If this option is used several times, the last one will be used.
! 1938: .IP "--proxy1.0 <host[:port]>"
! 1939: Use the specified HTTP 1.0 proxy. If the port number is not specified, it is
! 1940: assumed at port 1080.
! 1941:
! 1942: The only difference between this and the HTTP proxy option \fI-x, --proxy\fP, is that
! 1943: attempts to use CONNECT through the proxy will specify an HTTP 1.0 protocol
! 1944: instead of the default HTTP 1.1.
! 1945: .IP "-p, --proxytunnel"
! 1946: When an HTTP proxy is used \fI-x, --proxy\fP, this option will make curl tunnel through
! 1947: the proxy. The tunnel approach is made with the HTTP proxy CONNECT request and
! 1948: requires that the proxy allows direct connect to the remote port number curl
! 1949: wants to tunnel through to.
! 1950:
! 1951: To suppress proxy CONNECT response headers when curl is set to output headers
! 1952: use \fI--suppress-connect-headers\fP.
! 1953:
! 1954: See also \fI-x, --proxy\fP.
! 1955: .IP "--pubkey <key>"
! 1956: (SFTP SCP) Public key file name. Allows you to provide your public key in this separate
! 1957: file.
! 1958:
! 1959: If this option is used several times, the last one will be used.
! 1960:
! 1961: (As of 7.39.0, curl attempts to automatically extract the public key from the
! 1962: private key file, so passing this option is generally not required. Note that
! 1963: this public key extraction requires libcurl to be linked against a copy of
! 1964: libssh2 1.2.8 or higher that is itself linked against OpenSSL.)
! 1965: .IP "-Q, --quote"
! 1966: (FTP SFTP)
! 1967: Send an arbitrary command to the remote FTP or SFTP server. Quote commands are
! 1968: sent BEFORE the transfer takes place (just after the initial PWD command in an
! 1969: FTP transfer, to be exact). To make commands take place after a successful
! 1970: transfer, prefix them with a dash '-'. To make commands be sent after curl
! 1971: has changed the working directory, just before the transfer command(s), prefix
! 1972: the command with a '+' (this is only supported for FTP). You may specify any
! 1973: number of commands.
! 1974:
! 1975: If the server returns failure for one of the commands, the entire operation
! 1976: will be aborted. You must send syntactically correct FTP commands as RFC 959
! 1977: defines to FTP servers, or one of the commands listed below to SFTP servers.
! 1978:
! 1979: Prefix the command with an asterisk (*) to make curl continue even if the
! 1980: command fails as by default curl will stop at first failure.
! 1981:
! 1982: This option can be used multiple times.
! 1983:
! 1984: SFTP is a binary protocol. Unlike for FTP, curl interprets SFTP quote commands
! 1985: itself before sending them to the server. File names may be quoted
! 1986: shell-style to embed spaces or special characters. Following is the list of
! 1987: all supported SFTP quote commands:
! 1988: .RS
! 1989: .IP "chgrp group file"
! 1990: The chgrp command sets the group ID of the file named by the file operand to
! 1991: the group ID specified by the group operand. The group operand is a decimal
! 1992: integer group ID.
! 1993: .IP "chmod mode file"
! 1994: The chmod command modifies the file mode bits of the specified file. The
! 1995: mode operand is an octal integer mode number.
! 1996: .IP "chown user file"
! 1997: The chown command sets the owner of the file named by the file operand to the
! 1998: user ID specified by the user operand. The user operand is a decimal
! 1999: integer user ID.
! 2000: .IP "ln source_file target_file"
! 2001: The ln and symlink commands create a symbolic link at the target_file location
! 2002: pointing to the source_file location.
! 2003: .IP "mkdir directory_name"
! 2004: The mkdir command creates the directory named by the directory_name operand.
! 2005: .IP "pwd"
! 2006: The pwd command returns the absolute pathname of the current working directory.
! 2007: .IP "rename source target"
! 2008: The rename command renames the file or directory named by the source
! 2009: operand to the destination path named by the target operand.
! 2010: .IP "rm file"
! 2011: The rm command removes the file specified by the file operand.
! 2012: .IP "rmdir directory"
! 2013: The rmdir command removes the directory entry specified by the directory
! 2014: operand, provided it is empty.
! 2015: .IP "symlink source_file target_file"
! 2016: See ln.
! 2017: .RE
! 2018: .IP "--random-file <file>"
! 2019: Specify the path name to file containing what will be considered as random
! 2020: data. The data may be used to seed the random engine for SSL connections. See
! 2021: also the \fI--egd-file\fP option.
! 2022: .IP "-r, --range <range>"
! 2023: (HTTP FTP SFTP FILE) Retrieve a byte range (i.e. a partial document) from an HTTP/1.1, FTP or SFTP
! 2024: server or a local FILE. Ranges can be specified in a number of ways.
! 2025: .RS
! 2026: .TP 10
! 2027: .B 0-499
! 2028: specifies the first 500 bytes
! 2029: .TP
! 2030: .B 500-999
! 2031: specifies the second 500 bytes
! 2032: .TP
! 2033: .B -500
! 2034: specifies the last 500 bytes
! 2035: .TP
! 2036: .B 9500-
! 2037: specifies the bytes from offset 9500 and forward
! 2038: .TP
! 2039: .B 0-0,-1
! 2040: specifies the first and last byte only(*)(HTTP)
! 2041: .TP
! 2042: .B 100-199,500-599
! 2043: specifies two separate 100-byte ranges(*) (HTTP)
! 2044: .RE
! 2045: .IP
! 2046: (*) = NOTE that this will cause the server to reply with a multipart
! 2047: response!
! 2048:
! 2049: Only digit characters (0-9) are valid in the 'start' and 'stop' fields of the
! 2050: \&'start-stop' range syntax. If a non-digit character is given in the range,
! 2051: the server's response will be unspecified, depending on the server's
! 2052: configuration.
! 2053:
! 2054: You should also be aware that many HTTP/1.1 servers do not have this feature
! 2055: enabled, so that when you attempt to get a range, you'll instead get the whole
! 2056: document.
! 2057:
! 2058: FTP and SFTP range downloads only support the simple 'start-stop' syntax
! 2059: (optionally with one of the numbers omitted). FTP use depends on the extended
! 2060: FTP command SIZE.
! 2061:
! 2062: If this option is used several times, the last one will be used.
! 2063: .IP "--raw"
! 2064: (HTTP) When used, it disables all internal HTTP decoding of content or transfer
! 2065: encodings and instead makes them passed on unaltered, raw.
! 2066:
! 2067: Added in 7.16.2.
! 2068: .IP "-e, --referer <URL>"
! 2069: (HTTP) Sends the "Referrer Page" information to the HTTP server. This can also be set
! 2070: with the \fI-H, --header\fP flag of course. When used with \fI-L, --location\fP you can append
! 2071: ";auto" to the \fI-e, --referer\fP URL to make curl automatically set the previous URL
! 2072: when it follows a Location: header. The \&";auto" string can be used alone,
! 2073: even if you don't set an initial \fI-e, --referer\fP.
! 2074:
! 2075: If this option is used several times, the last one will be used.
! 2076:
! 2077: See also \fI-A, --user-agent\fP and \fI-H, --header\fP.
! 2078: .IP "-J, --remote-header-name"
! 2079: (HTTP) This option tells the \fI-O, --remote-name\fP option to use the server-specified
! 2080: Content-Disposition filename instead of extracting a filename from the URL.
! 2081:
! 2082: If the server specifies a file name and a file with that name already exists
! 2083: in the current working directory it will not be overwritten and an error will
! 2084: occur. If the server doesn't specify a file name then this option has no
! 2085: effect.
! 2086:
! 2087: There's no attempt to decode %-sequences (yet) in the provided file name, so
! 2088: this option may provide you with rather unexpected file names.
! 2089:
! 2090: \fBWARNING\fP: Exercise judicious use of this option, especially on Windows. A
! 2091: rogue server could send you the name of a DLL or other file that could possibly
! 2092: be loaded automatically by Windows or some third party software.
! 2093: .IP "--remote-name-all"
! 2094: This option changes the default action for all given URLs to be dealt with as
! 2095: if \fI-O, --remote-name\fP were used for each one. So if you want to disable that for a
! 2096: specific URL after \fI--remote-name-all\fP has been used, you must use "-o -" or
! 2097: --no-remote-name.
! 2098:
! 2099: Added in 7.19.0.
! 2100: .IP "-O, --remote-name"
! 2101: Write output to a local file named like the remote file we get. (Only the file
! 2102: part of the remote file is used, the path is cut off.)
! 2103:
! 2104: The file will be saved in the current working directory. If you want the file
! 2105: saved in a different directory, make sure you change the current working
! 2106: directory before invoking curl with this option.
! 2107:
! 2108: The remote file name to use for saving is extracted from the given URL,
! 2109: nothing else, and if it already exists it will be overwritten. If you want the
! 2110: server to be able to choose the file name refer to \fI-J, --remote-header-name\fP which
! 2111: can be used in addition to this option. If the server chooses a file name and
! 2112: that name already exists it will not be overwritten.
! 2113:
! 2114: There is no URL decoding done on the file name. If it has %20 or other URL
! 2115: encoded parts of the name, they will end up as-is as file name.
! 2116:
! 2117: You may use this option as many times as the number of URLs you have.
! 2118: .IP "-R, --remote-time"
! 2119: When used, this will make curl attempt to figure out the timestamp of the
! 2120: remote file, and if that is available make the local file get that same
! 2121: timestamp.
! 2122: .IP "--request-target"
! 2123: (HTTP) Tells curl to use an alternative "target" (path) instead of using the path as
! 2124: provided in the URL. Particularly useful when wanting to issue HTTP requests
! 2125: without leading slash or other data that doesn't follow the regular URL
! 2126: pattern, like "OPTIONS *".
! 2127:
! 2128: Added in 7.55.0.
! 2129: .IP "-X, --request <command>"
! 2130: (HTTP) Specifies a custom request method to use when communicating with the
! 2131: HTTP server. The specified request method will be used instead of the method
! 2132: otherwise used (which defaults to GET). Read the HTTP 1.1 specification for
! 2133: details and explanations. Common additional HTTP requests include PUT and
! 2134: DELETE, but related technologies like WebDAV offers PROPFIND, COPY, MOVE and
! 2135: more.
! 2136:
! 2137: Normally you don't need this option. All sorts of GET, HEAD, POST and PUT
! 2138: requests are rather invoked by using dedicated command line options.
! 2139:
! 2140: This option only changes the actual word used in the HTTP request, it does not
! 2141: alter the way curl behaves. So for example if you want to make a proper HEAD
! 2142: request, using -X HEAD will not suffice. You need to use the \fI-I, --head\fP option.
! 2143:
! 2144: The method string you set with \fI-X, --request\fP will be used for all requests, which
! 2145: if you for example use \fI-L, --location\fP may cause unintended side-effects when curl
! 2146: doesn't change request method according to the HTTP 30x response codes - and
! 2147: similar.
! 2148:
! 2149: (FTP)
! 2150: Specifies a custom FTP command to use instead of LIST when doing file lists
! 2151: with FTP.
! 2152:
! 2153: (POP3)
! 2154: Specifies a custom POP3 command to use instead of LIST or RETR. (Added in
! 2155: 7.26.0)
! 2156:
! 2157: (IMAP)
! 2158: Specifies a custom IMAP command to use instead of LIST. (Added in 7.30.0)
! 2159:
! 2160: (SMTP)
! 2161: Specifies a custom SMTP command to use instead of HELP or VRFY. (Added in 7.34.0)
! 2162:
! 2163: If this option is used several times, the last one will be used.
! 2164: .IP "--resolve <host:port:address[,address]...>"
! 2165: Provide a custom address for a specific host and port pair. Using this, you
! 2166: can make the curl requests(s) use a specified address and prevent the
! 2167: otherwise normally resolved address to be used. Consider it a sort of
! 2168: /etc/hosts alternative provided on the command line. The port number should be
! 2169: the number used for the specific protocol the host will be used for. It means
! 2170: you need several entries if you want to provide address for the same host but
! 2171: different ports.
! 2172:
! 2173: By specifying '*' as host you can tell curl to resolve any host and specific
! 2174: port pair to the specified address. Wildcard is resolved last so any \fI--resolve\fP
! 2175: with a specific host and port will be used first.
! 2176:
! 2177: The provided address set by this option will be used even if \fI-4, --ipv4\fP or \fI-6, --ipv6\fP
! 2178: is set to make curl use another IP version.
! 2179:
! 2180: Support for providing the IP address within [brackets] was added in 7.57.0.
! 2181:
! 2182: Support for providing multiple IP addresses per entry was added in 7.59.0.
! 2183:
! 2184: Support for resolving with wildcard was added in 7.64.0.
! 2185:
! 2186: This option can be used many times to add many host names to resolve.
! 2187:
! 2188: Added in 7.21.3.
! 2189: .IP "--retry-connrefused"
! 2190: In addition to the other conditions, consider ECONNREFUSED as a transient
! 2191: error too for \fI--retry\fP. This option is used together with --retry.
! 2192:
! 2193: Added in 7.52.0.
! 2194: .IP "--retry-delay <seconds>"
! 2195: Make curl sleep this amount of time before each retry when a transfer has
! 2196: failed with a transient error (it changes the default backoff time algorithm
! 2197: between retries). This option is only interesting if \fI--retry\fP is also
! 2198: used. Setting this delay to zero will make curl use the default backoff time.
! 2199:
! 2200: If this option is used several times, the last one will be used.
! 2201:
! 2202: Added in 7.12.3.
! 2203: .IP "--retry-max-time <seconds>"
! 2204: The retry timer is reset before the first transfer attempt. Retries will be
! 2205: done as usual (see \fI--retry\fP) as long as the timer hasn't reached this given
! 2206: limit. Notice that if the timer hasn't reached the limit, the request will be
! 2207: made and while performing, it may take longer than this given time period. To
! 2208: limit a single request\'s maximum time, use \fI-m, --max-time\fP. Set this option to
! 2209: zero to not timeout retries.
! 2210:
! 2211: If this option is used several times, the last one will be used.
! 2212:
! 2213: Added in 7.12.3.
! 2214: .IP "--retry <num>"
! 2215: If a transient error is returned when curl tries to perform a transfer, it
! 2216: will retry this number of times before giving up. Setting the number to 0
! 2217: makes curl do no retries (which is the default). Transient error means either:
! 2218: a timeout, an FTP 4xx response code or an HTTP 408 or 5xx response code.
! 2219:
! 2220: When curl is about to retry a transfer, it will first wait one second and then
! 2221: for all forthcoming retries it will double the waiting time until it reaches
! 2222: 10 minutes which then will be the delay between the rest of the retries. By
! 2223: using \fI--retry-delay\fP you disable this exponential backoff algorithm. See also
! 2224: \fI--retry-max-time\fP to limit the total time allowed for retries.
! 2225:
! 2226: Since curl 7.66.0, curl will comply with the Retry-After: response header if
! 2227: one was present to know when to issue the next retry.
! 2228:
! 2229: If this option is used several times, the last one will be used.
! 2230:
! 2231: Added in 7.12.3.
! 2232: .IP "--sasl-authzid"
! 2233: Use this authorisation identity (authzid), during SASL PLAIN authentication,
! 2234: in addition to the authentication identity (authcid) as specified by \fI-u, --user\fP.
! 2235:
! 2236: If the option isn't specified, the server will derive the authzid from the
! 2237: authcid, but if specified, and depending on the server implementation, it may
! 2238: be used to access another user's inbox, that the user has been granted access
! 2239: to, or a shared mailbox for example.
! 2240:
! 2241: Added in 7.66.0.
! 2242: .IP "--sasl-ir"
! 2243: Enable initial response in SASL authentication.
! 2244:
! 2245: Added in 7.31.0.
! 2246: .IP "--service-name <name>"
! 2247: This option allows you to change the service name for SPNEGO.
! 2248:
! 2249: Examples: \fI--negotiate\fP \fI--service-name\fP sockd would use sockd/server-name.
! 2250:
! 2251: Added in 7.43.0.
! 2252: .IP "-S, --show-error"
! 2253: When used with \fI-s, --silent\fP, it makes curl show an error message if it fails.
! 2254: .IP "-s, --silent"
! 2255: Silent or quiet mode. Don't show progress meter or error messages. Makes Curl
! 2256: mute. It will still output the data you ask for, potentially even to the
! 2257: terminal/stdout unless you redirect it.
! 2258:
! 2259: Use \fI-S, --show-error\fP in addition to this option to disable progress meter but
! 2260: still show error messages.
! 2261:
! 2262: See also \fI-v, --verbose\fP and \fI--stderr\fP.
! 2263: .IP "--socks4 <host[:port]>"
! 2264: Use the specified SOCKS4 proxy. If the port number is not specified, it is
! 2265: assumed at port 1080.
! 2266:
! 2267: This option overrides any previous use of \fI-x, --proxy\fP, as they are mutually
! 2268: exclusive.
! 2269:
! 2270: Since 7.21.7, this option is superfluous since you can specify a socks4 proxy
! 2271: with \fI-x, --proxy\fP using a socks4:// protocol prefix.
! 2272:
! 2273: Since 7.52.0, \fI--preproxy\fP can be used to specify a SOCKS proxy at the same time
! 2274: \fI-x, --proxy\fP is used with an HTTP/HTTPS proxy. In such a case curl first connects to
! 2275: the SOCKS proxy and then connects (through SOCKS) to the HTTP or HTTPS proxy.
! 2276:
! 2277: If this option is used several times, the last one will be used.
! 2278:
! 2279: Added in 7.15.2.
! 2280: .IP "--socks4a <host[:port]>"
! 2281: Use the specified SOCKS4a proxy. If the port number is not specified, it is
! 2282: assumed at port 1080.
! 2283:
! 2284: This option overrides any previous use of \fI-x, --proxy\fP, as they are mutually
! 2285: exclusive.
! 2286:
! 2287: Since 7.21.7, this option is superfluous since you can specify a socks4a proxy
! 2288: with \fI-x, --proxy\fP using a socks4a:// protocol prefix.
! 2289:
! 2290: Since 7.52.0, \fI--preproxy\fP can be used to specify a SOCKS proxy at the same time
! 2291: \fI-x, --proxy\fP is used with an HTTP/HTTPS proxy. In such a case curl first connects to
! 2292: the SOCKS proxy and then connects (through SOCKS) to the HTTP or HTTPS proxy.
! 2293:
! 2294: If this option is used several times, the last one will be used.
! 2295:
! 2296: Added in 7.18.0.
! 2297: .IP "--socks5-basic"
! 2298: Tells curl to use username/password authentication when connecting to a SOCKS5
! 2299: proxy. The username/password authentication is enabled by default. Use
! 2300: \fI--socks5-gssapi\fP to force GSS-API authentication to SOCKS5 proxies.
! 2301:
! 2302: Added in 7.55.0.
! 2303: .IP "--socks5-gssapi-nec"
! 2304: As part of the GSS-API negotiation a protection mode is negotiated. RFC 1961
! 2305: says in section 4.3/4.4 it should be protected, but the NEC reference
! 2306: implementation does not. The option \fI--socks5-gssapi-nec\fP allows the
! 2307: unprotected exchange of the protection mode negotiation.
! 2308:
! 2309: Added in 7.19.4.
! 2310: .IP "--socks5-gssapi-service <name>"
! 2311: The default service name for a socks server is rcmd/server-fqdn. This option
! 2312: allows you to change it.
! 2313:
! 2314: Examples: \fI--socks5\fP proxy-name \fI--socks5-gssapi-service\fP sockd would use
! 2315: sockd/proxy-name \fI--socks5\fP proxy-name \fI--socks5-gssapi-service\fP sockd/real-name
! 2316: would use sockd/real-name for cases where the proxy-name does not match the
! 2317: principal name.
! 2318:
! 2319: Added in 7.19.4.
! 2320: .IP "--socks5-gssapi"
! 2321: Tells curl to use GSS-API authentication when connecting to a SOCKS5 proxy.
! 2322: The GSS-API authentication is enabled by default (if curl is compiled with
! 2323: GSS-API support). Use \fI--socks5-basic\fP to force username/password authentication
! 2324: to SOCKS5 proxies.
! 2325:
! 2326: Added in 7.55.0.
! 2327: .IP "--socks5-hostname <host[:port]>"
! 2328: Use the specified SOCKS5 proxy (and let the proxy resolve the host name). If
! 2329: the port number is not specified, it is assumed at port 1080.
! 2330:
! 2331: This option overrides any previous use of \fI-x, --proxy\fP, as they are mutually
! 2332: exclusive.
! 2333:
! 2334: Since 7.21.7, this option is superfluous since you can specify a socks5
! 2335: hostname proxy with \fI-x, --proxy\fP using a socks5h:// protocol prefix.
! 2336:
! 2337: Since 7.52.0, \fI--preproxy\fP can be used to specify a SOCKS proxy at the same time
! 2338: \fI-x, --proxy\fP is used with an HTTP/HTTPS proxy. In such a case curl first connects to
! 2339: the SOCKS proxy and then connects (through SOCKS) to the HTTP or HTTPS proxy.
! 2340:
! 2341: If this option is used several times, the last one will be used.
! 2342:
! 2343: Added in 7.18.0.
! 2344: .IP "--socks5 <host[:port]>"
! 2345: Use the specified SOCKS5 proxy - but resolve the host name locally. If the
! 2346: port number is not specified, it is assumed at port 1080.
! 2347:
! 2348: This option overrides any previous use of \fI-x, --proxy\fP, as they are mutually
! 2349: exclusive.
! 2350:
! 2351: Since 7.21.7, this option is superfluous since you can specify a socks5 proxy
! 2352: with \fI-x, --proxy\fP using a socks5:// protocol prefix.
! 2353:
! 2354: Since 7.52.0, \fI--preproxy\fP can be used to specify a SOCKS proxy at the same time
! 2355: \fI-x, --proxy\fP is used with an HTTP/HTTPS proxy. In such a case curl first connects to
! 2356: the SOCKS proxy and then connects (through SOCKS) to the HTTP or HTTPS proxy.
! 2357:
! 2358: If this option is used several times, the last one will be used.
! 2359:
! 2360: This option (as well as \fI--socks4\fP) does not work with IPV6, FTPS or LDAP.
! 2361:
! 2362: Added in 7.18.0.
! 2363: .IP "-Y, --speed-limit <speed>"
! 2364: If a download is slower than this given speed (in bytes per second) for
! 2365: speed-time seconds it gets aborted. speed-time is set with \fI-y, --speed-time\fP and is
! 2366: 30 if not set.
! 2367:
! 2368: If this option is used several times, the last one will be used.
! 2369: .IP "-y, --speed-time <seconds>"
! 2370: If a download is slower than speed-limit bytes per second during a speed-time
! 2371: period, the download gets aborted. If speed-time is used, the default
! 2372: speed-limit will be 1 unless set with \fI-Y, --speed-limit\fP.
! 2373:
! 2374: This option controls transfers and thus will not affect slow connects etc. If
! 2375: this is a concern for you, try the \fI--connect-timeout\fP option.
! 2376:
! 2377: If this option is used several times, the last one will be used.
! 2378: .IP "--ssl-allow-beast"
! 2379: This option tells curl to not work around a security flaw in the SSL3 and
! 2380: TLS1.0 protocols known as BEAST. If this option isn't used, the SSL layer may
! 2381: use workarounds known to cause interoperability problems with some older SSL
! 2382: implementations. WARNING: this option loosens the SSL security, and by using
! 2383: this flag you ask for exactly that.
! 2384:
! 2385: Added in 7.25.0.
! 2386: .IP "--ssl-no-revoke"
! 2387: (Schannel) This option tells curl to disable certificate revocation checks.
! 2388: WARNING: this option loosens the SSL security, and by using this flag you ask
! 2389: for exactly that.
! 2390:
! 2391: Added in 7.44.0.
! 2392: .IP "--ssl-reqd"
! 2393: (FTP IMAP POP3 SMTP) Require SSL/TLS for the connection. Terminates the connection if the server
! 2394: doesn't support SSL/TLS.
! 2395:
! 2396: This option was formerly known as --ftp-ssl-reqd.
! 2397:
! 2398: Added in 7.20.0.
! 2399: .IP "--ssl-revoke-best-effort"
! 2400: (Schannel) This option tells curl to ignore certificate revocation checks when
! 2401: they failed due to missing/offline distribution points for the revocation check
! 2402: lists.
! 2403:
! 2404: Added in 7.70.0.
! 2405: .IP "--ssl"
! 2406: (FTP IMAP POP3 SMTP)
! 2407: Try to use SSL/TLS for the connection. Reverts to a non-secure connection if
! 2408: the server doesn't support SSL/TLS. See also \fI--ftp-ssl-control\fP and \fI--ssl-reqd\fP
! 2409: for different levels of encryption required.
! 2410:
! 2411: This option was formerly known as --ftp-ssl (Added in 7.11.0). That option
! 2412: name can still be used but will be removed in a future version.
! 2413:
! 2414: Added in 7.20.0.
! 2415: .IP "-2, --sslv2"
! 2416: (SSL) Forces curl to use SSL version 2 when negotiating with a remote SSL
! 2417: server. Sometimes curl is built without SSLv2 support. SSLv2 is widely
! 2418: considered insecure (see RFC 6176).
! 2419:
! 2420: See also \fI--http1.1\fP and \fI--http2\fP. \fI-2, --sslv2\fP requires that the underlying libcurl was built to support TLS. This option overrides \fI-3, --sslv3\fP and \fI-1, --tlsv1\fP and \fI--tlsv1.1\fP and \fI--tlsv1.2\fP.
! 2421: .IP "-3, --sslv3"
! 2422: (SSL) Forces curl to use SSL version 3 when negotiating with a remote SSL
! 2423: server. Sometimes curl is built without SSLv3 support. SSLv3 is widely
! 2424: considered insecure (see RFC 7568).
! 2425:
! 2426: See also \fI--http1.1\fP and \fI--http2\fP. \fI-3, --sslv3\fP requires that the underlying libcurl was built to support TLS. This option overrides \fI-2, --sslv2\fP and \fI-1, --tlsv1\fP and \fI--tlsv1.1\fP and \fI--tlsv1.2\fP.
! 2427: .IP "--stderr"
! 2428: Redirect all writes to stderr to the specified file instead. If the file name
! 2429: is a plain '-', it is instead written to stdout.
! 2430:
! 2431: If this option is used several times, the last one will be used.
! 2432:
! 2433: See also \fI-v, --verbose\fP and \fI-s, --silent\fP.
! 2434: .IP "--styled-output"
! 2435: Enables the automatic use of bold font styles when writing HTTP headers to the
! 2436: terminal. Use --no-styled-output to switch them off.
! 2437:
! 2438: Added in 7.61.0.
! 2439: .IP "--suppress-connect-headers"
! 2440: When \fI-p, --proxytunnel\fP is used and a CONNECT request is made don't output proxy
! 2441: CONNECT response headers. This option is meant to be used with \fI-D, --dump-header\fP or
! 2442: \fI-i, --include\fP which are used to show protocol headers in the output. It has no
! 2443: effect on debug options such as \fI-v, --verbose\fP or \fI--trace\fP, or any statistics.
! 2444:
! 2445: See also \fI-D, --dump-header\fP and \fI-i, --include\fP and \fI-p, --proxytunnel\fP.
! 2446: .IP "--tcp-fastopen"
! 2447: Enable use of TCP Fast Open (RFC7413).
! 2448:
! 2449: Added in 7.49.0.
! 2450: .IP "--tcp-nodelay"
! 2451: Turn on the TCP_NODELAY option. See the \fIcurl_easy_setopt(3)\fP man page for
! 2452: details about this option.
! 2453:
! 2454: Since 7.50.2, curl sets this option by default and you need to explicitly
! 2455: switch it off if you don't want it on.
! 2456:
! 2457: Added in 7.11.2.
! 2458: .IP "-t, --telnet-option <opt=val>"
! 2459: Pass options to the telnet protocol. Supported options are:
! 2460:
! 2461: TTYPE=<term> Sets the terminal type.
! 2462:
! 2463: XDISPLOC=<X display> Sets the X display location.
! 2464:
! 2465: NEW_ENV=<var,val> Sets an environment variable.
! 2466: .IP "--tftp-blksize <value>"
! 2467: (TFTP) Set TFTP BLKSIZE option (must be >512). This is the block size that curl will
! 2468: try to use when transferring data to or from a TFTP server. By default 512
! 2469: bytes will be used.
! 2470:
! 2471: If this option is used several times, the last one will be used.
! 2472:
! 2473: Added in 7.20.0.
! 2474: .IP "--tftp-no-options"
! 2475: (TFTP) Tells curl not to send TFTP options requests.
! 2476:
! 2477: This option improves interop with some legacy servers that do not acknowledge
! 2478: or properly implement TFTP options. When this option is used \fI--tftp-blksize\fP is
! 2479: ignored.
! 2480:
! 2481: Added in 7.48.0.
! 2482: .IP "-z, --time-cond <time>"
! 2483: (HTTP FTP) Request a file that has been modified later than the given time and date, or
! 2484: one that has been modified before that time. The <date expression> can be all
! 2485: sorts of date strings or if it doesn't match any internal ones, it is taken as
! 2486: a filename and tries to get the modification date (mtime) from <file>
! 2487: instead. See the \fIcurl_getdate(3)\fP man pages for date expression details.
! 2488:
! 2489: Start the date expression with a dash (-) to make it request for a document
! 2490: that is older than the given date/time, default is a document that is newer
! 2491: than the specified date/time.
! 2492:
! 2493: If this option is used several times, the last one will be used.
! 2494: .IP "--tls-max <VERSION>"
! 2495: (SSL) VERSION defines maximum supported TLS version. The minimum acceptable version
! 2496: is set by tlsv1.0, tlsv1.1, tlsv1.2 or tlsv1.3.
! 2497:
! 2498: .RS
! 2499: .IP "default"
! 2500: Use up to recommended TLS version.
! 2501: .IP "1.0"
! 2502: Use up to TLSv1.0.
! 2503: .IP "1.1"
! 2504: Use up to TLSv1.1.
! 2505: .IP "1.2"
! 2506: Use up to TLSv1.2.
! 2507: .IP "1.3"
! 2508: Use up to TLSv1.3.
! 2509: .RE
! 2510:
! 2511: See also \fI--tlsv1.0\fP and \fI--tlsv1.1\fP and \fI--tlsv1.2\fP and \fI--tlsv1.3\fP. \fI--tls-max\fP requires that the underlying libcurl was built to support TLS. Added in 7.54.0.
! 2512: .IP "--tls13-ciphers <list of TLS 1.3 ciphersuites>"
! 2513: (TLS) Specifies which cipher suites to use in the connection if it negotiates TLS
! 2514: 1.3. The list of ciphers suites must specify valid ciphers. Read up on TLS 1.3
! 2515: cipher suite details on this URL:
! 2516:
! 2517: https://curl.haxx.se/docs/ssl-ciphers.html
! 2518:
! 2519: This option is currently used only when curl is built to use OpenSSL 1.1.1 or
! 2520: later. If you are using a different SSL backend you can try setting TLS 1.3
! 2521: cipher suites by using the \fI--ciphers\fP option.
! 2522:
! 2523: If this option is used several times, the last one will be used.
! 2524: .IP "--tlsauthtype <type>"
! 2525: Set TLS authentication type. Currently, the only supported option is "SRP",
! 2526: for TLS-SRP (RFC 5054). If \fI--tlsuser\fP and \fI--tlspassword\fP are specified but
! 2527: \fI--tlsauthtype\fP is not, then this option defaults to "SRP". This option works
! 2528: only if the underlying libcurl is built with TLS-SRP support, which requires
! 2529: OpenSSL or GnuTLS with TLS-SRP support.
! 2530:
! 2531: Added in 7.21.4.
! 2532: .IP "--tlspassword"
! 2533: Set password for use with the TLS authentication method specified with
! 2534: \fI--tlsauthtype\fP. Requires that \fI--tlsuser\fP also be set.
! 2535:
! 2536: This doesn't work with TLS 1.3.
! 2537:
! 2538: Added in 7.21.4.
! 2539: .IP "--tlsuser <name>"
! 2540: Set username for use with the TLS authentication method specified with
! 2541: \fI--tlsauthtype\fP. Requires that \fI--tlspassword\fP also is set.
! 2542:
! 2543: This doesn't work with TLS 1.3.
! 2544:
! 2545: Added in 7.21.4.
! 2546: .IP "--tlsv1.0"
! 2547: (TLS) Forces curl to use TLS version 1.0 or later when connecting to a remote TLS server.
! 2548:
! 2549: In old versions of curl this option was documented to allow _only_ TLS 1.0,
! 2550: but behavior was inconsistent depending on the TLS library. Use \fI--tls-max\fP if
! 2551: you want to set a maximum TLS version.
! 2552:
! 2553: Added in 7.34.0.
! 2554: .IP "--tlsv1.1"
! 2555: (TLS) Forces curl to use TLS version 1.1 or later when connecting to a remote TLS server.
! 2556:
! 2557: In old versions of curl this option was documented to allow _only_ TLS 1.1,
! 2558: but behavior was inconsistent depending on the TLS library. Use \fI--tls-max\fP if
! 2559: you want to set a maximum TLS version.
! 2560:
! 2561: Added in 7.34.0.
! 2562: .IP "--tlsv1.2"
! 2563: (TLS) Forces curl to use TLS version 1.2 or later when connecting to a remote TLS server.
! 2564:
! 2565: In old versions of curl this option was documented to allow _only_ TLS 1.2,
! 2566: but behavior was inconsistent depending on the TLS library. Use \fI--tls-max\fP if
! 2567: you want to set a maximum TLS version.
! 2568:
! 2569: Added in 7.34.0.
! 2570: .IP "--tlsv1.3"
! 2571: (TLS) Forces curl to use TLS version 1.3 or later when connecting to a remote TLS server.
! 2572:
! 2573: Note that TLS 1.3 is only supported by a subset of TLS backends. At the time
! 2574: of this writing, they are BoringSSL, NSS, and Secure Transport (on iOS 11 or
! 2575: later, and macOS 10.13 or later).
! 2576:
! 2577: Added in 7.52.0.
! 2578: .IP "-1, --tlsv1"
! 2579: (SSL) Tells curl to use at least TLS version 1.x when negotiating with a remote TLS
! 2580: server. That means TLS version 1.0 or higher
! 2581:
! 2582: See also \fI--http1.1\fP and \fI--http2\fP. \fI-1, --tlsv1\fP requires that the underlying libcurl was built to support TLS. This option overrides \fI--tlsv1.1\fP and \fI--tlsv1.2\fP and \fI--tlsv1.3\fP.
! 2583: .IP "--tr-encoding"
! 2584: (HTTP) Request a compressed Transfer-Encoding response using one of the algorithms
! 2585: curl supports, and uncompress the data while receiving it.
! 2586:
! 2587: Added in 7.21.6.
! 2588: .IP "--trace-ascii <file>"
! 2589: Enables a full trace dump of all incoming and outgoing data, including
! 2590: descriptive information, to the given output file. Use "-" as filename to have
! 2591: the output sent to stdout.
! 2592:
! 2593: This is very similar to \fI--trace\fP, but leaves out the hex part and only shows
! 2594: the ASCII part of the dump. It makes smaller output that might be easier to
! 2595: read for untrained humans.
! 2596:
! 2597: If this option is used several times, the last one will be used.
! 2598:
! 2599: This option overrides \fI--trace\fP and \fI-v, --verbose\fP.
! 2600: .IP "--trace-time"
! 2601: Prepends a time stamp to each trace or verbose line that curl displays.
! 2602:
! 2603: Added in 7.14.0.
! 2604: .IP "--trace <file>"
! 2605: Enables a full trace dump of all incoming and outgoing data, including
! 2606: descriptive information, to the given output file. Use "-" as filename to have
! 2607: the output sent to stdout. Use "%" as filename to have the output sent to
! 2608: stderr.
! 2609:
! 2610: If this option is used several times, the last one will be used.
! 2611:
! 2612: This option overrides \fI-v, --verbose\fP and \fI--trace-ascii\fP.
! 2613: .IP "--unix-socket <path>"
! 2614: (HTTP) Connect through this Unix domain socket, instead of using the network.
! 2615:
! 2616: Added in 7.40.0.
! 2617: .IP "-T, --upload-file <file>"
! 2618: This transfers the specified local file to the remote URL. If there is no file
! 2619: part in the specified URL, curl will append the local file name. NOTE that you
! 2620: must use a trailing / on the last directory to really prove to Curl that there
! 2621: is no file name or curl will think that your last directory name is the remote
! 2622: file name to use. That will most likely cause the upload operation to fail. If
! 2623: this is used on an HTTP(S) server, the PUT command will be used.
! 2624:
! 2625: Use the file name "-" (a single dash) to use stdin instead of a given file.
! 2626: Alternately, the file name "." (a single period) may be specified instead
! 2627: of "-" to use stdin in non-blocking mode to allow reading server output
! 2628: while stdin is being uploaded.
! 2629:
! 2630: You can specify one \fI-T, --upload-file\fP for each URL on the command line. Each
! 2631: \fI-T, --upload-file\fP + URL pair specifies what to upload and to where. curl also
! 2632: supports "globbing" of the \fI-T, --upload-file\fP argument, meaning that you can upload
! 2633: multiple files to a single URL by using the same URL globbing style supported
! 2634: in the URL, like this:
! 2635:
! 2636: curl --upload-file "{file1,file2}" http://www.example.com
! 2637:
! 2638: or even
! 2639:
! 2640: curl -T "img[1-1000].png" ftp://ftp.example.com/upload/
! 2641:
! 2642: When uploading to an SMTP server: the uploaded data is assumed to be RFC 5322
! 2643: formatted. It has to feature the necessary set of headers and mail body
! 2644: formatted correctly by the user as curl will not transcode nor encode it
! 2645: further in any way.
! 2646: .IP "--url <url>"
! 2647: Specify a URL to fetch. This option is mostly handy when you want to specify
! 2648: URL(s) in a config file.
! 2649:
! 2650: If the given URL is missing a scheme name (such as "http://" or "ftp://" etc)
! 2651: then curl will make a guess based on the host. If the outermost sub-domain
! 2652: name matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then that protocol will be
! 2653: used, otherwise HTTP will be used. Since 7.45.0 guessing can be disabled by
! 2654: setting a default protocol, see \fI--proto-default\fP for details.
! 2655:
! 2656: This option may be used any number of times. To control where this URL is
! 2657: written, use the \fI-o, --output\fP or the \fI-O, --remote-name\fP options.
! 2658:
! 2659: Warning: On Windows, particular file:// accesses can be converted to network
! 2660: accesses by the operating system. Beware!
! 2661: .IP "-B, --use-ascii"
! 2662: (FTP LDAP) Enable ASCII transfer. For FTP, this can also be enforced by using a URL that
! 2663: ends with ";type=A". This option causes data sent to stdout to be in text mode
! 2664: for win32 systems.
! 2665: .IP "-A, --user-agent <name>"
! 2666: (HTTP)
! 2667: Specify the User-Agent string to send to the HTTP server. To encode blanks in
! 2668: the string, surround the string with single quote marks. This header can also
! 2669: be set with the \fI-H, --header\fP or the \fI--proxy-header\fP options.
! 2670:
! 2671: If this option is used several times, the last one will be used.
! 2672: .IP "-u, --user <user:password>"
! 2673: Specify the user name and password to use for server authentication. Overrides
! 2674: \fI-n, --netrc\fP and \fI--netrc-optional\fP.
! 2675:
! 2676: If you simply specify the user name, curl will prompt for a password.
! 2677:
! 2678: The user name and passwords are split up on the first colon, which makes it
! 2679: impossible to use a colon in the user name with this option. The password can,
! 2680: still.
! 2681:
! 2682: On systems where it works, curl will hide the given option argument from
! 2683: process listings. This is not enough to protect credentials from possibly
! 2684: getting seen by other users on the same system as they will still be visible
! 2685: for a brief moment before cleared. Such sensitive data should be retrieved
! 2686: from a file instead or similar and never used in clear text in a command line.
! 2687:
! 2688: When using Kerberos V5 with a Windows based server you should include the
! 2689: Windows domain name in the user name, in order for the server to successfully
! 2690: obtain a Kerberos Ticket. If you don't then the initial authentication
! 2691: handshake may fail.
! 2692:
! 2693: When using NTLM, the user name can be specified simply as the user name,
! 2694: without the domain, if there is a single domain and forest in your setup
! 2695: for example.
! 2696:
! 2697: To specify the domain name use either Down-Level Logon Name or UPN (User
! 2698: Principal Name) formats. For example, EXAMPLE\\user and user@example.com
! 2699: respectively.
! 2700:
! 2701: If you use a Windows SSPI-enabled curl binary and perform Kerberos V5,
! 2702: Negotiate, NTLM or Digest authentication then you can tell curl to select
! 2703: the user name and password from your environment by specifying a single colon
! 2704: with this option: "-u :".
! 2705:
! 2706: If this option is used several times, the last one will be used.
! 2707: .IP "-v, --verbose"
! 2708: Makes curl verbose during the operation. Useful for debugging and seeing
! 2709: what's going on "under the hood". A line starting with '>' means "header data"
! 2710: sent by curl, '<' means "header data" received by curl that is hidden in
! 2711: normal cases, and a line starting with '*' means additional info provided by
! 2712: curl.
! 2713:
! 2714: If you only want HTTP headers in the output, \fI-i, --include\fP might be the option
! 2715: you're looking for.
! 2716:
! 2717: If you think this option still doesn't give you enough details, consider using
! 2718: \fI--trace\fP or \fI--trace-ascii\fP instead.
! 2719:
! 2720: Use \fI-s, --silent\fP to make curl really quiet.
! 2721:
! 2722: See also \fI-i, --include\fP. This option overrides \fI--trace\fP and \fI--trace-ascii\fP.
! 2723: .IP "-V, --version"
! 2724: Displays information about curl and the libcurl version it uses.
! 2725:
! 2726: The first line includes the full version of curl, libcurl and other 3rd party
! 2727: libraries linked with the executable.
! 2728:
! 2729: The second line (starts with "Protocols:") shows all protocols that libcurl
! 2730: reports to support.
! 2731:
! 2732: The third line (starts with "Features:") shows specific features libcurl
! 2733: reports to offer. Available features include:
! 2734: .RS
! 2735: .IP "IPv6"
! 2736: You can use IPv6 with this.
! 2737: .IP "krb4"
! 2738: Krb4 for FTP is supported.
! 2739: .IP "SSL"
! 2740: SSL versions of various protocols are supported, such as HTTPS, FTPS, POP3S
! 2741: and so on.
! 2742: .IP "libz"
! 2743: Automatic decompression of compressed files over HTTP is supported.
! 2744: .IP "NTLM"
! 2745: NTLM authentication is supported.
! 2746: .IP "Debug"
! 2747: This curl uses a libcurl built with Debug. This enables more error-tracking
! 2748: and memory debugging etc. For curl-developers only!
! 2749: .IP "AsynchDNS"
! 2750: This curl uses asynchronous name resolves. Asynchronous name resolves can be
! 2751: done using either the c-ares or the threaded resolver backends.
! 2752: .IP "SPNEGO"
! 2753: SPNEGO authentication is supported.
! 2754: .IP "Largefile"
! 2755: This curl supports transfers of large files, files larger than 2GB.
! 2756: .IP "IDN"
! 2757: This curl supports IDN - international domain names.
! 2758: .IP "GSS-API"
! 2759: GSS-API is supported.
! 2760: .IP "SSPI"
! 2761: SSPI is supported.
! 2762: .IP "TLS-SRP"
! 2763: SRP (Secure Remote Password) authentication is supported for TLS.
! 2764: .IP "HTTP2"
! 2765: HTTP/2 support has been built-in.
! 2766: .IP "UnixSockets"
! 2767: Unix sockets support is provided.
! 2768: .IP "HTTPS-proxy"
! 2769: This curl is built to support HTTPS proxy.
! 2770: .IP "Metalink"
! 2771: This curl supports Metalink (both version 3 and 4 (RFC 5854)), which
! 2772: describes mirrors and hashes. curl will use mirrors for failover if
! 2773: there are errors (such as the file or server not being available).
! 2774: .IP "PSL"
! 2775: PSL is short for Public Suffix List and means that this curl has been built
! 2776: with knowledge about "public suffixes".
! 2777: .IP "MultiSSL"
! 2778: This curl supports multiple TLS backends.
! 2779: .RE
! 2780: .IP "-w, --write-out <format>"
! 2781: Make curl display information on stdout after a completed transfer. The format
! 2782: is a string that may contain plain text mixed with any number of
! 2783: variables. The format can be specified as a literal "string", or you can have
! 2784: curl read the format from a file with "@filename" and to tell curl to read the
! 2785: format from stdin you write "@-".
! 2786:
! 2787: The variables present in the output format will be substituted by the value or
! 2788: text that curl thinks fit, as described below. All variables are specified as
! 2789: %{variable_name} and to output a normal % you just write them as %%. You can
! 2790: output a newline by using \\n, a carriage return with \\r and a tab space with
! 2791: \\t.
! 2792:
! 2793: The output will be written to standard output, but this can be switched to
! 2794: standard error by using %{stderr}.
! 2795:
! 2796: .B NOTE:
! 2797: The %-symbol is a special symbol in the win32-environment, where all
! 2798: occurrences of % must be doubled when using this option.
! 2799:
! 2800: The variables available are:
! 2801: .RS
! 2802: .TP 15
! 2803: .B content_type
! 2804: The Content-Type of the requested document, if there was any.
! 2805: .TP
! 2806: .B filename_effective
! 2807: The ultimate filename that curl writes out to. This is only meaningful if curl
! 2808: is told to write to a file with the \fI-O, --remote-name\fP or \fI-o, --output\fP
! 2809: option. It's most useful in combination with the \fI-J, --remote-header-name\fP
! 2810: option. (Added in 7.26.0)
! 2811: .TP
! 2812: .B ftp_entry_path
! 2813: The initial path curl ended up in when logging on to the remote FTP
! 2814: server. (Added in 7.15.4)
! 2815: .TP
! 2816: .B http_code
! 2817: The numerical response code that was found in the last retrieved HTTP(S) or
! 2818: FTP(s) transfer. In 7.18.2 the alias \fBresponse_code\fP was added to show the
! 2819: same info.
! 2820: .TP
! 2821: .B http_connect
! 2822: The numerical code that was found in the last response (from a proxy) to a
! 2823: curl CONNECT request. (Added in 7.12.4)
! 2824: .TP
! 2825: .B http_version
! 2826: The http version that was effectively used. (Added in 7.50.0)
! 2827: .TP
! 2828: .B json
! 2829: A JSON object with all available keys.
! 2830: .TP
! 2831: .B local_ip
! 2832: The IP address of the local end of the most recently done connection - can be
! 2833: either IPv4 or IPv6 (Added in 7.29.0)
! 2834: .TP
! 2835: .B local_port
! 2836: The local port number of the most recently done connection (Added in 7.29.0)
! 2837: .TP
! 2838: .B num_connects
! 2839: Number of new connects made in the recent transfer. (Added in 7.12.3)
! 2840: .TP
! 2841: .B num_redirects
! 2842: Number of redirects that were followed in the request. (Added in 7.12.3)
! 2843: .TP
! 2844: .B proxy_ssl_verify_result
! 2845: The result of the HTTPS proxy's SSL peer certificate verification that was
! 2846: requested. 0 means the verification was successful. (Added in 7.52.0)
! 2847: .TP
! 2848: .B redirect_url
! 2849: When an HTTP request was made without \fI-L, --location\fP to follow redirects (or when
! 2850: --max-redir is met), this variable will show the actual URL a redirect
! 2851: \fIwould\fP have gone to. (Added in 7.18.2)
! 2852: .TP
! 2853: .B remote_ip
! 2854: The remote IP address of the most recently done connection - can be either
! 2855: IPv4 or IPv6 (Added in 7.29.0)
! 2856: .TP
! 2857: .B remote_port
! 2858: The remote port number of the most recently done connection (Added in 7.29.0)
! 2859: .TP
! 2860: .B scheme
! 2861: The URL scheme (sometimes called protocol) that was effectively used (Added in 7.52.0)
! 2862: .TP
! 2863: .B size_download
! 2864: The total amount of bytes that were downloaded.
! 2865: .TP
! 2866: .B size_header
! 2867: The total amount of bytes of the downloaded headers.
! 2868: .TP
! 2869: .B size_request
! 2870: The total amount of bytes that were sent in the HTTP request.
! 2871: .TP
! 2872: .B size_upload
! 2873: The total amount of bytes that were uploaded.
! 2874: .TP
! 2875: .B speed_download
! 2876: The average download speed that curl measured for the complete download. Bytes
! 2877: per second.
! 2878: .TP
! 2879: .B speed_upload
! 2880: The average upload speed that curl measured for the complete upload. Bytes per
! 2881: second.
! 2882: .TP
! 2883: .B ssl_verify_result
! 2884: The result of the SSL peer certificate verification that was requested. 0
! 2885: means the verification was successful. (Added in 7.19.0)
! 2886: .TP
! 2887: .B stderr
! 2888: From this point on, the \fI-w, --write-out\fP output will be written to standard
! 2889: error. (Added in 7.63.0)
! 2890: .TP
! 2891: .B stdout
! 2892: From this point on, the \fI-w, --write-out\fP output will be written to standard output.
! 2893: This is the default, but can be used to switch back after switching to stderr.
! 2894: (Added in 7.63.0)
! 2895: .TP
! 2896: .B time_appconnect
! 2897: The time, in seconds, it took from the start until the SSL/SSH/etc
! 2898: connect/handshake to the remote host was completed. (Added in 7.19.0)
! 2899: .TP
! 2900: .B time_connect
! 2901: The time, in seconds, it took from the start until the TCP connect to the
! 2902: remote host (or proxy) was completed.
! 2903: .TP
! 2904: .B time_namelookup
! 2905: The time, in seconds, it took from the start until the name resolving was
! 2906: completed.
! 2907: .TP
! 2908: .B time_pretransfer
! 2909: The time, in seconds, it took from the start until the file transfer was just
! 2910: about to begin. This includes all pre-transfer commands and negotiations that
! 2911: are specific to the particular protocol(s) involved.
! 2912: .TP
! 2913: .B time_redirect
! 2914: The time, in seconds, it took for all redirection steps including name lookup,
! 2915: connect, pretransfer and transfer before the final transaction was
! 2916: started. time_redirect shows the complete execution time for multiple
! 2917: redirections. (Added in 7.12.3)
! 2918: .TP
! 2919: .B time_starttransfer
! 2920: The time, in seconds, it took from the start until the first byte was just
! 2921: about to be transferred. This includes time_pretransfer and also the time the
! 2922: server needed to calculate the result.
! 2923: .TP
! 2924: .B time_total
! 2925: The total time, in seconds, that the full operation lasted.
! 2926: .TP
! 2927: .B url_effective
! 2928: The URL that was fetched last. This is most meaningful if you've told curl
! 2929: to follow location: headers.
! 2930: .RE
! 2931: .IP
! 2932: If this option is used several times, the last one will be used.
! 2933: .IP "--xattr"
! 2934: When saving output to a file, this option tells curl to store certain file
! 2935: metadata in extended file attributes. Currently, the URL is stored in the
! 2936: xdg.origin.url attribute and, for HTTP, the content type is stored in
! 2937: the mime_type attribute. If the file system does not support extended
! 2938: attributes, a warning is issued.
! 2939: .SH FILES
! 2940: .I ~/.curlrc
! 2941: .RS
! 2942: Default config file, see \fI-K, --config\fP for details.
! 2943: .SH ENVIRONMENT
! 2944: The environment variables can be specified in lower case or upper case. The
! 2945: lower case version has precedence. http_proxy is an exception as it is only
! 2946: available in lower case.
! 2947:
! 2948: Using an environment variable to set the proxy has the same effect as using
! 2949: the \fI-x, --proxy\fP option.
! 2950:
! 2951: .IP "http_proxy [protocol://]<host>[:port]"
! 2952: Sets the proxy server to use for HTTP.
! 2953: .IP "HTTPS_PROXY [protocol://]<host>[:port]"
! 2954: Sets the proxy server to use for HTTPS.
! 2955: .IP "[url-protocol]_PROXY [protocol://]<host>[:port]"
! 2956: Sets the proxy server to use for [url-protocol], where the protocol is a
! 2957: protocol that curl supports and as specified in a URL. FTP, FTPS, POP3, IMAP,
! 2958: SMTP, LDAP etc.
! 2959: .IP "ALL_PROXY [protocol://]<host>[:port]"
! 2960: Sets the proxy server to use if no protocol-specific proxy is set.
! 2961: .IP "NO_PROXY <comma-separated list of hosts/domains>"
! 2962: list of host names that shouldn't go through any proxy. If set to an asterisk
! 2963: \&'*' only, it matches all hosts. Each name in this list is matched as either
! 2964: a domain name which contains the hostname, or the hostname itself.
! 2965:
! 2966: This environment variable disables use of the proxy even when specified with
! 2967: the \fI-x, --proxy\fP option. That is
! 2968: .B NO_PROXY=direct.example.com curl -x http://proxy.example.com
! 2969: .B http://direct.example.com
! 2970: accesses the target URL directly, and
! 2971: .B NO_PROXY=direct.example.com curl -x http://proxy.example.com
! 2972: .B http://somewhere.example.com
! 2973: accesses the target URL through the proxy.
! 2974:
! 2975: The list of host names can also be include numerical IP addresses, and IPv6
! 2976: versions should then be given without enclosing brackets.
! 2977:
! 2978: .SH "PROXY PROTOCOL PREFIXES"
! 2979: Since curl version 7.21.7, the proxy string may be specified with a
! 2980: protocol:// prefix to specify alternative proxy protocols.
! 2981:
! 2982: If no protocol is specified in the proxy string or if the string doesn't match
! 2983: a supported one, the proxy will be treated as an HTTP proxy.
! 2984:
! 2985: The supported proxy protocol prefixes are as follows:
! 2986: .IP "http://"
! 2987: Makes it use it as an HTTP proxy. The default if no scheme prefix is used.
! 2988: .IP "https://"
! 2989: Makes it treated as an \fBHTTPS\fP proxy.
! 2990: .IP "socks4://"
! 2991: Makes it the equivalent of \fI--socks4\fP
! 2992: .IP "socks4a://"
! 2993: Makes it the equivalent of \fI--socks4a\fP
! 2994: .IP "socks5://"
! 2995: Makes it the equivalent of \fI--socks5\fP
! 2996: .IP "socks5h://"
! 2997: Makes it the equivalent of \fI--socks5-hostname\fP
! 2998: .SH EXIT CODES
! 2999: There are a bunch of different error codes and their corresponding error
! 3000: messages that may appear during bad conditions. At the time of this writing,
! 3001: the exit codes are:
! 3002: .IP 1
! 3003: Unsupported protocol. This build of curl has no support for this protocol.
! 3004: .IP 2
! 3005: Failed to initialize.
! 3006: .IP 3
! 3007: URL malformed. The syntax was not correct.
! 3008: .IP 4
! 3009: A feature or option that was needed to perform the desired request was not
! 3010: enabled or was explicitly disabled at build-time. To make curl able to do
! 3011: this, you probably need another build of libcurl!
! 3012: .IP 5
! 3013: Couldn't resolve proxy. The given proxy host could not be resolved.
! 3014: .IP 6
! 3015: Couldn't resolve host. The given remote host was not resolved.
! 3016: .IP 7
! 3017: Failed to connect to host.
! 3018: .IP 8
! 3019: Weird server reply. The server sent data curl couldn't parse.
! 3020: .IP 9
! 3021: FTP access denied. The server denied login or denied access to the particular
! 3022: resource or directory you wanted to reach. Most often you tried to change to a
! 3023: directory that doesn't exist on the server.
! 3024: .IP 10
! 3025: FTP accept failed. While waiting for the server to connect back when an active
! 3026: FTP session is used, an error code was sent over the control connection or
! 3027: similar.
! 3028: .IP 11
! 3029: FTP weird PASS reply. Curl couldn't parse the reply sent to the PASS request.
! 3030: .IP 12
! 3031: During an active FTP session while waiting for the server to connect back to
! 3032: curl, the timeout expired.
! 3033: .IP 13
! 3034: FTP weird PASV reply, Curl couldn't parse the reply sent to the PASV request.
! 3035: .IP 14
! 3036: FTP weird 227 format. Curl couldn't parse the 227-line the server sent.
! 3037: .IP 15
! 3038: FTP can't get host. Couldn't resolve the host IP we got in the 227-line.
! 3039: .IP 16
! 3040: HTTP/2 error. A problem was detected in the HTTP2 framing layer. This is
! 3041: somewhat generic and can be one out of several problems, see the error message
! 3042: for details.
! 3043: .IP 17
! 3044: FTP couldn't set binary. Couldn't change transfer method to binary.
! 3045: .IP 18
! 3046: Partial file. Only a part of the file was transferred.
! 3047: .IP 19
! 3048: FTP couldn't download/access the given file, the RETR (or similar) command
! 3049: failed.
! 3050: .IP 21
! 3051: FTP quote error. A quote command returned error from the server.
! 3052: .IP 22
! 3053: HTTP page not retrieved. The requested url was not found or returned another
! 3054: error with the HTTP error code being 400 or above. This return code only
! 3055: appears if \fI-f, --fail\fP is used.
! 3056: .IP 23
! 3057: Write error. Curl couldn't write data to a local filesystem or similar.
! 3058: .IP 25
! 3059: FTP couldn't STOR file. The server denied the STOR operation, used for FTP
! 3060: uploading.
! 3061: .IP 26
! 3062: Read error. Various reading problems.
! 3063: .IP 27
! 3064: Out of memory. A memory allocation request failed.
! 3065: .IP 28
! 3066: Operation timeout. The specified time-out period was reached according to the
! 3067: conditions.
! 3068: .IP 30
! 3069: FTP PORT failed. The PORT command failed. Not all FTP servers support the PORT
! 3070: command, try doing a transfer using PASV instead!
! 3071: .IP 31
! 3072: FTP couldn't use REST. The REST command failed. This command is used for
! 3073: resumed FTP transfers.
! 3074: .IP 33
! 3075: HTTP range error. The range "command" didn't work.
! 3076: .IP 34
! 3077: HTTP post error. Internal post-request generation error.
! 3078: .IP 35
! 3079: SSL connect error. The SSL handshaking failed.
! 3080: .IP 36
! 3081: Bad download resume. Couldn't continue an earlier aborted download.
! 3082: .IP 37
! 3083: FILE couldn't read file. Failed to open the file. Permissions?
! 3084: .IP 38
! 3085: LDAP cannot bind. LDAP bind operation failed.
! 3086: .IP 39
! 3087: LDAP search failed.
! 3088: .IP 41
! 3089: Function not found. A required LDAP function was not found.
! 3090: .IP 42
! 3091: Aborted by callback. An application told curl to abort the operation.
! 3092: .IP 43
! 3093: Internal error. A function was called with a bad parameter.
! 3094: .IP 45
! 3095: Interface error. A specified outgoing interface could not be used.
! 3096: .IP 47
! 3097: Too many redirects. When following redirects, curl hit the maximum amount.
! 3098: .IP 48
! 3099: Unknown option specified to libcurl. This indicates that you passed a weird
! 3100: option to curl that was passed on to libcurl and rejected. Read up in the
! 3101: manual!
! 3102: .IP 49
! 3103: Malformed telnet option.
! 3104: .IP 51
! 3105: The peer's SSL certificate or SSH MD5 fingerprint was not OK.
! 3106: .IP 52
! 3107: The server didn't reply anything, which here is considered an error.
! 3108: .IP 53
! 3109: SSL crypto engine not found.
! 3110: .IP 54
! 3111: Cannot set SSL crypto engine as default.
! 3112: .IP 55
! 3113: Failed sending network data.
! 3114: .IP 56
! 3115: Failure in receiving network data.
! 3116: .IP 58
! 3117: Problem with the local certificate.
! 3118: .IP 59
! 3119: Couldn't use specified SSL cipher.
! 3120: .IP 60
! 3121: Peer certificate cannot be authenticated with known CA certificates.
! 3122: .IP 61
! 3123: Unrecognized transfer encoding.
! 3124: .IP 62
! 3125: Invalid LDAP URL.
! 3126: .IP 63
! 3127: Maximum file size exceeded.
! 3128: .IP 64
! 3129: Requested FTP SSL level failed.
! 3130: .IP 65
! 3131: Sending the data requires a rewind that failed.
! 3132: .IP 66
! 3133: Failed to initialise SSL Engine.
! 3134: .IP 67
! 3135: The user name, password, or similar was not accepted and curl failed to log in.
! 3136: .IP 68
! 3137: File not found on TFTP server.
! 3138: .IP 69
! 3139: Permission problem on TFTP server.
! 3140: .IP 70
! 3141: Out of disk space on TFTP server.
! 3142: .IP 71
! 3143: Illegal TFTP operation.
! 3144: .IP 72
! 3145: Unknown TFTP transfer ID.
! 3146: .IP 73
! 3147: File already exists (TFTP).
! 3148: .IP 74
! 3149: No such user (TFTP).
! 3150: .IP 75
! 3151: Character conversion failed.
! 3152: .IP 76
! 3153: Character conversion functions required.
! 3154: .IP 77
! 3155: Problem with reading the SSL CA cert (path? access rights?).
! 3156: .IP 78
! 3157: The resource referenced in the URL does not exist.
! 3158: .IP 79
! 3159: An unspecified error occurred during the SSH session.
! 3160: .IP 80
! 3161: Failed to shut down the SSL connection.
! 3162: .IP 82
! 3163: Could not load CRL file, missing or wrong format (added in 7.19.0).
! 3164: .IP 83
! 3165: Issuer check failed (added in 7.19.0).
! 3166: .IP 84
! 3167: The FTP PRET command failed
! 3168: .IP 85
! 3169: RTSP: mismatch of CSeq numbers
! 3170: .IP 86
! 3171: RTSP: mismatch of Session Identifiers
! 3172: .IP 87
! 3173: unable to parse FTP file list
! 3174: .IP 88
! 3175: FTP chunk callback reported error
! 3176: .IP 89
! 3177: No connection available, the session will be queued
! 3178: .IP 90
! 3179: SSL public key does not matched pinned public key
! 3180: .IP 91
! 3181: Invalid SSL certificate status.
! 3182: .IP 92
! 3183: Stream error in HTTP/2 framing layer.
! 3184: .IP XX
! 3185: More error codes will appear here in future releases. The existing ones
! 3186: are meant to never change.
! 3187: .SH AUTHORS / CONTRIBUTORS
! 3188: Daniel Stenberg is the main author, but the whole list of contributors is
! 3189: found in the separate THANKS file.
! 3190: .SH WWW
! 3191: https://curl.haxx.se
! 3192: .SH "SEE ALSO"
! 3193: .BR ftp (1),
! 3194: .BR wget (1)
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to curl.1 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / curl / docs