page-header 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254
  1. .\" **************************************************************************
  2. .\" * _ _ ____ _
  3. .\" * Project ___| | | | _ \| |
  4. .\" * / __| | | | |_) | |
  5. .\" * | (__| |_| | _ <| |___
  6. .\" * \___|\___/|_| \_\_____|
  7. .\" *
  8. .\" * Copyright (C) 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.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. .\" * SPDX-License-Identifier: curl
  22. .\" *
  23. .\" **************************************************************************
  24. .\"
  25. .\" DO NOT EDIT. Generated by the curl project gen.pl man page generator.
  26. .\"
  27. .TH curl 1 "%DATE" "curl %VERSION" "curl Manual"
  28. .SH NAME
  29. curl \- transfer a URL
  30. .SH SYNOPSIS
  31. .B curl [options / URLs]
  32. .SH DESCRIPTION
  33. **curl** is a tool for transferring data from or to a server using URLs. It
  34. supports these protocols: DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS,
  35. IMAP, IMAPS, LDAP, LDAPS, MQTT, POP3, POP3S, RTMP, RTMPS, RTSP, SCP, SFTP,
  36. SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS and WSS.
  37. curl is powered by libcurl for all transfer-related features. See
  38. *libcurl(3)* for details.
  39. .SH URL
  40. The URL syntax is protocol-dependent. You find a detailed description in
  41. RFC 3986.
  42. If you provide a URL without a leading **protocol://** scheme, curl guesses
  43. what protocol you want. It then defaults to HTTP but assumes others based on
  44. often-used host name prefixes. For example, for host names starting with
  45. "ftp." curl assumes you want FTP.
  46. You can specify any amount of URLs on the command line. They will be fetched
  47. in a sequential manner in the specified order unless you use --parallel. You
  48. can specify command line options and URLs mixed and in any order on the
  49. command line.
  50. curl attempts to re-use connections when doing multiple transfers, so that
  51. getting many files from the same server do not use multiple connects and setup
  52. handshakes. This improves speed. Connection re-use can only be done for URLs
  53. specified for a single command line invocation and cannot be performed between
  54. separate curl runs.
  55. Provide an IPv6 zone id in the URL with an escaped percentage sign. Like in
  56. "http://[fe80::3%25eth0]/"
  57. .SH GLOBBING
  58. You can specify multiple URLs or parts of URLs by writing lists within braces
  59. or ranges within brackets. We call this "globbing".
  60. Provide a list with three different names like this:
  61. "http://site.{one,two,three}.com"
  62. or you can get sequences of alphanumeric series by using [] as in:
  63. "ftp://ftp.example.com/file[1-100].txt"
  64. "ftp://ftp.example.com/file[001-100].txt" (with leading zeros)
  65. "ftp://ftp.example.com/file[a-z].txt"
  66. Nested sequences are not supported, but you can use several ones next to each
  67. other:
  68. "http://example.com/archive[1996-1999]/vol[1-4]/part{a,b,c}.html"
  69. You can specify a step counter for the ranges to get every Nth number or
  70. letter:
  71. "http://example.com/file[1-100:10].txt"
  72. "http://example.com/file[a-z:2].txt"
  73. When using [] or {} sequences when invoked from a command line prompt, you
  74. probably have to put the full URL within double quotes to avoid the shell from
  75. interfering with it. This also goes for other characters treated special, like
  76. for example '&', '?' and '*'.
  77. Switch off globbing with --globoff.
  78. .SH VARIABLES
  79. Starting in curl 8.3.0, curl supports command line variables. Set variables
  80. with --variable name=content or --variable name@file (where "file" can be
  81. stdin if set to a single dash (-)).
  82. Variable contents can expanded in option parameters using "{{name}}" (without
  83. the quotes) if the option name is prefixed with "--expand-". This gets the
  84. contents of the variable "name" inserted, or a blank if the name does not
  85. exist as a variable. Insert "{{" verbatim in the string by prefixing it with a
  86. backslash, like "\\{{".
  87. You an access and expand environment variables by first importing them. You
  88. can select to either require the environment variable to be set or you can
  89. provide a default value in case it is not already set. Plain --variable %name
  90. imports the variable called 'name' but exits with an error if that environment
  91. variable is not already set. To provide a default value if it is not set, use
  92. --variable %name=content or --variable %name@content.
  93. Example. Get the USER environment variable into the URL, fail if USER is not
  94. set:
  95. --variable '%USER'
  96. --expand-url = "https://example.com/api/{{USER}}/method"
  97. When expanding variables, curl supports a set of functions that can make the
  98. variable contents more convenient to use. It can trim leading and trailing
  99. white space with *trim*, it can output the contents as a JSON quoted string
  100. with *json*, URL encode the string with *url* or base64 encode it with
  101. *b64*. You apply function to a variable expansion, add them colon separated to
  102. the right side of the variable. Variable content holding null bytes that are
  103. not encoded when expanded, will cause error.
  104. Example: get the contents of a file called $HOME/.secret into a variable
  105. called "fix". Make sure that the content is trimmed and percent-encoded sent
  106. as POST data:
  107. --variable %HOME
  108. --expand-variable fix@{{HOME}}/.secret
  109. --expand-data "{{fix:trim:url}}"
  110. https://example.com/
  111. Command line variables and expansions were added in in 8.3.0.
  112. .SH OUTPUT
  113. If not told otherwise, curl writes the received data to stdout. It can be
  114. instructed to instead save that data into a local file, using the --output or
  115. --remote-name options. If curl is given multiple URLs to transfer on the
  116. command line, it similarly needs multiple options for where to save them.
  117. curl does not parse or otherwise "understand" the content it gets or writes as
  118. output. It does no encoding or decoding, unless explicitly asked to with
  119. dedicated command line options.
  120. .SH PROTOCOLS
  121. curl supports numerous protocols, or put in URL terms: schemes. Your
  122. particular build may not support them all.
  123. .IP DICT
  124. Lets you lookup words using online dictionaries.
  125. .IP FILE
  126. Read or write local files. curl does not support accessing file:// URL
  127. remotely, but when running on Microsoft Windows using the native UNC approach
  128. will work.
  129. .IP FTP(S)
  130. curl supports the File Transfer Protocol with a lot of tweaks and levers. With
  131. or without using TLS.
  132. .IP GOPHER(S)
  133. Retrieve files.
  134. .IP HTTP(S)
  135. curl supports HTTP with numerous options and variations. It can speak HTTP
  136. version 0.9, 1.0, 1.1, 2 and 3 depending on build options and the correct
  137. command line options.
  138. .IP IMAP(S)
  139. Using the mail reading protocol, curl can "download" emails for you. With or
  140. without using TLS.
  141. .IP LDAP(S)
  142. curl can do directory lookups for you, with or without TLS.
  143. .IP MQTT
  144. curl supports MQTT version 3. Downloading over MQTT equals "subscribe" to a
  145. topic while uploading/posting equals "publish" on a topic. MQTT over TLS is
  146. not supported (yet).
  147. .IP POP3(S)
  148. Downloading from a pop3 server means getting a mail. With or without using
  149. TLS.
  150. .IP RTMP(S)
  151. The **Realtime Messaging Protocol** is primarily used to serve streaming media
  152. and curl can download it.
  153. .IP RTSP
  154. curl supports RTSP 1.0 downloads.
  155. .IP SCP
  156. curl supports SSH version 2 scp transfers.
  157. .IP SFTP
  158. curl supports SFTP (draft 5) done over SSH version 2.
  159. .IP SMB(S)
  160. curl supports SMB version 1 for upload and download.
  161. .IP SMTP(S)
  162. Uploading contents to an SMTP server means sending an email. With or without
  163. TLS.
  164. .IP TELNET
  165. Telling curl to fetch a telnet URL starts an interactive session where it
  166. sends what it reads on stdin and outputs what the server sends it.
  167. .IP TFTP
  168. curl can do TFTP downloads and uploads.
  169. .SH "PROGRESS METER"
  170. curl normally displays a progress meter during operations, indicating the
  171. amount of transferred data, transfer speeds and estimated time left, etc. The
  172. progress meter displays the transfer rate in bytes per second. The suffixes
  173. (k, M, G, T, P) are 1024 based. For example 1k is 1024 bytes. 1M is 1048576
  174. bytes.
  175. curl displays this data to the terminal by default, so if you invoke curl to
  176. do an operation and it is about to write data to the terminal, it
  177. *disables* the progress meter as otherwise it would mess up the output
  178. mixing progress meter and response data.
  179. If you want a progress meter for HTTP POST or PUT requests, you need to
  180. redirect the response output to a file, using shell redirect (>), --output or
  181. similar.
  182. This does not apply to FTP upload as that operation does not spit out any
  183. response data to the terminal.
  184. If you prefer a progress "bar" instead of the regular meter, --progress-bar is
  185. your friend. You can also disable the progress meter completely with the
  186. --silent option.
  187. .SH VERSION
  188. This man page describes curl %VERSION. If you use a later version, chances are
  189. this man page does not fully document it. If you use an earlier version, this
  190. document tries to include version information about which specific version
  191. that introduced changes.
  192. You can always learn which the latest curl version is by running
  193. curl https://curl.se/info
  194. The online version of this man page is always showing the latest incarnation:
  195. https://curl.se/docs/manpage.html
  196. .SH OPTIONS
  197. Options start with one or two dashes. Many of the options require an
  198. additional value next to them.
  199. The short "single-dash" form of the options, -d for example, may be used with
  200. or without a space between it and its value, although a space is a recommended
  201. separator. The long "double-dash" form, --data for example, requires a space
  202. between it and its value.
  203. Short version options that do not need any additional values can be used
  204. immediately next to each other, like for example you can specify all the
  205. options *-O*, *-L* and *-v* at once as *-OLv*.
  206. In general, all boolean options are enabled with --**option** and yet again
  207. disabled with --**no-**option. That is, you use the same option name but
  208. prefix it with "no-". However, in this list we mostly only list and show the
  209. *--option* version of them.
  210. When --next is used, it resets the parser state and you start again with a
  211. clean option state, except for the options that are "global". Global options
  212. will retain their values and meaning even after --next.
  213. The following options are global:
  214. %GLOBALS.