write-out.md (12308B)
1 --- 2 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3 SPDX-License-Identifier: curl 4 Long: write-out 5 Short: w 6 Arg: <format> 7 Help: Output FORMAT after completion 8 Category: verbose 9 Added: 6.5 10 Multi: single 11 See-also: 12 - verbose 13 - head 14 Example: 15 - -w '%{response_code}\n' $URL 16 --- 17 18 # `--write-out` 19 20 Make curl display information on stdout after a completed transfer. The format 21 is a string that may contain plain text mixed with any number of variables. 22 The format can be specified as a literal "string", or you can have curl read 23 the format from a file with "@filename" and to tell curl to read the format 24 from stdin you write "@-". 25 26 The variables present in the output format are substituted by the value or 27 text that curl thinks fit, as described below. All variables are specified as 28 %{variable_name} and to output a normal % you just write them as %%. You can 29 output a newline by using \n, a carriage return with \r and a tab space with 30 \t. 31 32 The output is by default written to standard output, but can be changed with 33 %{stderr} and %output{}. 34 35 Output HTTP header values from the transfer's most recent server response by 36 using *%header{name}* where *name* is the case insensitive name of the header 37 (without the trailing colon). The header contents are exactly as delivered over 38 the network but with leading and trailing whitespace and newlines stripped off 39 (added in 7.84.0). 40 41 Select a specific target destination file to write the output to, by using 42 *%output{name}* (added in curl 8.3.0) where *name* is the full filename. The 43 output following that instruction is then written to that file. More than one 44 *%output{}* instruction can be specified in the same write-out argument. If 45 the filename cannot be created, curl leaves the output destination to the one 46 used prior to the *%output{}* instruction. Use *%output{\>\>name}* to append 47 data to an existing file. 48 49 This output is done independently of if the file transfer was successful or 50 not. 51 52 If the specified action or output specified with this option fails in any way, 53 it does not make curl return a (different) error. 54 55 **NOTE:** On Windows, the %-symbol is a special symbol used to expand 56 environment variables. In batch files, all occurrences of % must be doubled 57 when using this option to properly escape. If this option is used at the 58 command prompt then the % cannot be escaped and unintended expansion is 59 possible. 60 61 The variables available are: 62 63 ## `certs` 64 Output the certificate chain with details. Supported only by the OpenSSL, 65 GnuTLS, Schannel and Rustls backends. (Added in 7.88.0) 66 67 ## `conn_id` 68 The connection identifier last used by the transfer. The connection id is 69 unique number among all connections using the same connection cache. 70 (Added in 8.2.0) 71 72 ## `content_type` 73 The Content-Type of the requested document, if there was any. 74 75 ## `errormsg` 76 The error message. (Added in 7.75.0) 77 78 ## `exitcode` 79 The numerical exit code of the transfer. (Added in 7.75.0) 80 81 ## `filename_effective` 82 The ultimate filename that curl writes out to. This is only meaningful if curl 83 is told to write to a file with the --remote-name or --output option. It is 84 most useful in combination with the --remote-header-name option. 85 (Added in 7.26.0) 86 87 ## `ftp_entry_path` 88 The initial path curl ended up in when logging on to the remote FTP 89 server. (Added in 7.15.4) 90 91 ## `header{name}` 92 The value of header `name` from the transfer's most recent server response. 93 Unlike other variables, the variable name `header` is not in braces. For 94 example `%header{date}`. Refer to --write-out remarks. (Added in 7.84.0) 95 96 ## `header_json` 97 A JSON object with all HTTP response headers from the recent transfer. Values 98 are provided as arrays, since in the case of multiple headers there can be 99 multiple values. (Added in 7.83.0) 100 101 The header names provided in lowercase, listed in order of appearance over the 102 wire. Except for duplicated headers. They are grouped on the first occurrence 103 of that header, each value is presented in the JSON array. 104 105 ## `http_code` 106 The numerical response code that was found in the last retrieved HTTP(S) or 107 FTP(s) transfer. 108 109 ## `http_connect` 110 The numerical code that was found in the last response (from a proxy) to a 111 curl CONNECT request. (Added in 7.12.4) 112 113 ## `http_version` 114 The http version that was effectively used. (Added in 7.50.0) 115 116 ## `json` 117 A JSON object with all available keys. (Added in 7.70.0) 118 119 ## `local_ip` 120 The IP address of the local end of the most recently done connection - can be 121 either IPv4 or IPv6. (Added in 7.29.0) 122 123 ## `local_port` 124 The local port number of the most recently done connection. (Added in 7.29.0) 125 126 ## `method` 127 The http method used in the most recent HTTP request. (Added in 7.72.0) 128 129 ## `num_certs` 130 Number of server certificates received in the TLS handshake. Supported only by 131 the OpenSSL, GnuTLS, Schannel and Rustls backends. (Added in 7.88.0) 132 133 ## `num_connects` 134 Number of new connects made in the recent transfer. (Added in 7.12.3) 135 136 ## `num_headers` 137 The number of response headers in the most recent request (restarted at each 138 redirect). Note that the status line IS NOT a header. (Added in 7.73.0) 139 140 ## `num_redirects` 141 Number of redirects that were followed in the request. (Added in 7.12.3) 142 143 ## `num_retries` 144 Number of retries actually performed when `--retry` has been used. 145 (Added in 8.9.0) 146 147 ## `onerror` 148 The rest of the output is only shown if the transfer returned a non-zero error. 149 (Added in 7.75.0) 150 151 ## `output{filename}` 152 From this point on, the --write-out output is written to the filename specified 153 in braces. The filename can be prefixed with `>>` to append to the file. Unlike 154 other variables, the variable name `output` is not in braces. For example 155 `%output{>>stats.txt}`. Refer to --write-out remarks. (Added in 8.3.0) 156 157 ## `proxy_ssl_verify_result` 158 The result of the HTTPS proxy's SSL peer certificate verification that was 159 requested. 0 means the verification was successful. (Added in 7.52.0) 160 161 ## `proxy_used` 162 Returns 1 if the previous transfer used a proxy, otherwise 0. Useful to for 163 example determine if a `NOPROXY` pattern matched the hostname or not. (Added 164 in 8.7.0) 165 166 ## `redirect_url` 167 When an HTTP request was made without --location to follow redirects (or when 168 --max-redirs is met), this variable shows the actual URL a redirect 169 *would* have gone to. (Added in 7.18.2) 170 171 ## `referer` 172 The Referer: header, if there was any. (Added in 7.76.0) 173 174 ## `remote_ip` 175 The remote IP address of the most recently done connection - can be either 176 IPv4 or IPv6. (Added in 7.29.0) 177 178 ## `remote_port` 179 The remote port number of the most recently done connection. (Added in 7.29.0) 180 181 ## `response_code` 182 The numerical response code that was found in the last transfer (formerly 183 known as "http_code"). (Added in 7.18.2) 184 185 ## `scheme` 186 The URL scheme (sometimes called protocol) that was effectively used. (Added in 7.52.0) 187 188 ## `size_download` 189 The total amount of bytes that were downloaded. This is the size of the 190 body/data that was transferred, excluding headers. 191 192 ## `size_header` 193 The total amount of bytes of the downloaded headers. 194 195 ## `size_request` 196 The total amount of bytes that were sent in the HTTP request. 197 198 ## `size_upload` 199 The total amount of bytes that were uploaded. This is the size of the 200 body/data that was transferred, excluding headers. 201 202 ## `speed_download` 203 The average download speed that curl measured for the complete download. Bytes 204 per second. 205 206 ## `speed_upload` 207 The average upload speed that curl measured for the complete upload. Bytes per 208 second. 209 210 ## `ssl_verify_result` 211 The result of the SSL peer certificate verification that was requested. 0 212 means the verification was successful. (Added in 7.19.0) 213 214 ## `stderr` 215 From this point on, the --write-out output is written to standard 216 error. (Added in 7.63.0) 217 218 ## `stdout` 219 From this point on, the --write-out output is written to standard output. 220 This is the default, but can be used to switch back after switching to stderr. 221 (Added in 7.63.0) 222 223 ## `time_appconnect` 224 The time, in seconds, it took from the start until the SSL/SSH/etc 225 connect/handshake to the remote host was completed. (Added in 7.19.0) 226 227 ## `time_connect` 228 The time, in seconds, it took from the start until the TCP connect to the 229 remote host (or proxy) was completed. 230 231 ## `time_namelookup` 232 The time, in seconds, it took from the start until the name resolving was 233 completed. 234 235 ## `time_posttransfer` 236 The time it took from the start until the last byte is sent by libcurl. 237 In microseconds. (Added in 8.10.0) 238 239 ## `time_pretransfer` 240 The time, in seconds, it took from the start until the file transfer was just 241 about to begin. This includes all pre-transfer commands and negotiations that 242 are specific to the particular protocol(s) involved. 243 244 ## `time_queue` 245 The time, in seconds, the transfer was queued during its run. This adds 246 the queue time for each redirect step that may have happened. Transfers 247 may be queued for significant amounts of time when connection or parallel 248 limits are in place. (Added in 8.12.0) 249 250 ## `time_redirect` 251 The time, in seconds, it took for all redirection steps including name lookup, 252 connect, pretransfer and transfer before the final transaction was 253 started. `time_redirect` shows the complete execution time for multiple 254 redirections. (Added in 7.12.3) 255 256 ## `time_starttransfer` 257 The time, in seconds, it took from the start until the first byte was received. 258 This includes time_pretransfer and also the time the server needed to calculate 259 the result. 260 261 ## `time_total` 262 The total time, in seconds, that the full operation lasted. 263 264 ## `tls_earlydata` 265 The amount of bytes that were sent as TLSv1.3 early data. This is 0 266 if this TLS feature was not used and negative if the data sent had 267 been rejected by the server. The use of early data is enabled via 268 the command line option `--tls-earlydata`. (Added in 8.12.0) 269 270 ## `url` 271 The URL that was fetched. (Added in 7.75.0) 272 273 ## `url.scheme` 274 The scheme part of the URL that was fetched. (Added in 8.1.0) 275 276 ## `url.user` 277 The user part of the URL that was fetched. (Added in 8.1.0) 278 279 ## `url.password` 280 The password part of the URL that was fetched. (Added in 8.1.0) 281 282 ## `url.options` 283 The options part of the URL that was fetched. (Added in 8.1.0) 284 285 ## `url.host` 286 The host part of the URL that was fetched. (Added in 8.1.0) 287 288 ## `url.port` 289 The port number of the URL that was fetched. If no port number was specified 290 and the URL scheme is known, that scheme's default port number is 291 shown. (Added in 8.1.0) 292 293 ## `url.path` 294 The path part of the URL that was fetched. (Added in 8.1.0) 295 296 ## `url.query` 297 The query part of the URL that was fetched. (Added in 8.1.0) 298 299 ## `url.fragment` 300 The fragment part of the URL that was fetched. (Added in 8.1.0) 301 302 ## `url.zoneid` 303 The zone id part of the URL that was fetched. (Added in 8.1.0) 304 305 ## `urle.scheme` 306 The scheme part of the effective (last) URL that was fetched. (Added in 8.1.0) 307 308 ## `urle.user` 309 The user part of the effective (last) URL that was fetched. (Added in 8.1.0) 310 311 ## `urle.password` 312 The password part of the effective (last) URL that was fetched. (Added in 8.1.0) 313 314 ## `urle.options` 315 The options part of the effective (last) URL that was fetched. (Added in 8.1.0) 316 317 ## `urle.host` 318 The host part of the effective (last) URL that was fetched. (Added in 8.1.0) 319 320 ## `urle.port` 321 The port number of the effective (last) URL that was fetched. If no port 322 number was specified, but the URL scheme is known, that scheme's default port 323 number is shown. (Added in 8.1.0) 324 325 ## `urle.path` 326 The path part of the effective (last) URL that was fetched. (Added in 8.1.0) 327 328 ## `urle.query` 329 The query part of the effective (last) URL that was fetched. (Added in 8.1.0) 330 331 ## `urle.fragment` 332 The fragment part of the effective (last) URL that was fetched. (Added in 8.1.0) 333 334 ## `urle.zoneid` 335 The zone id part of the effective (last) URL that was fetched. (Added in 8.1.0) 336 337 ## `urlnum` 338 The URL index number of this transfer, 0-indexed. Unglobbed URLs share the 339 same index number as the origin globbed URL. (Added in 7.75.0) 340 341 ## `url_effective` 342 The URL that was fetched last. This is most meaningful if you have told curl 343 to follow location: headers. 344 345 ## `xfer_id` 346 The numerical identifier of the last transfer done. -1 if no transfer has been 347 started yet for the handle. The transfer id is unique among all transfers 348 performed using the same connection cache. 349 (Added in 8.2.0)