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