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## `content_type` 67The Content-Type of the requested document, if there was any. 68 69## `errormsg` 70The error message. (Added in 7.75.0) 71 72## `exitcode` 73The numerical exit code of the transfer. (Added in 7.75.0) 74 75## `filename_effective` 76The ultimate filename that curl writes out to. This is only meaningful if curl 77is told to write to a file with the --remote-name or --output option. It is 78most useful in combination with the --remote-header-name option. (Added in 797.26.0) 80 81## `ftp_entry_path` 82The initial path curl ended up in when logging on to the remote FTP 83server. (Added in 7.15.4) 84 85## `header_json` 86A JSON object with all HTTP response headers from the recent transfer. Values 87are provided as arrays, since in the case of multiple headers there can be 88multiple values. (Added in 7.83.0) 89 90The header names provided in lowercase, listed in order of appearance over the 91wire. Except for duplicated headers. They are grouped on the first occurrence 92of that header, each value is presented in the JSON array. 93 94## `http_code` 95The numerical response code that was found in the last retrieved HTTP(S) or 96FTP(s) transfer. 97 98## `http_connect` 99The numerical code that was found in the last response (from a proxy) to a 100curl CONNECT request. (Added in 7.12.4) 101 102## `http_version` 103The http version that was effectively used. (Added in 7.50.0) 104 105## `json` 106A JSON object with all available keys. (Added in 7.70.0) 107 108## `local_ip` 109The IP address of the local end of the most recently done connection - can be 110either IPv4 or IPv6. (Added in 7.29.0) 111 112## `local_port` 113The local port number of the most recently done connection. (Added in 7.29.0) 114 115## `method` 116The http method used in the most recent HTTP request. (Added in 7.72.0) 117 118## `num_certs` 119Number of server certificates received in the TLS handshake. Supported only by 120the OpenSSL, GnuTLS, Schannel and Secure Transport backends. 121(Added in 7.88.0) 122 123## `num_connects` 124Number of new connects made in the recent transfer. (Added in 7.12.3) 125 126## `num_headers` 127The number of response headers in the most recent request (restarted at each 128redirect). Note that the status line IS NOT a header. (Added in 7.73.0) 129 130## `num_redirects` 131Number of redirects that were followed in the request. (Added in 7.12.3) 132 133## `onerror` 134The rest of the output is only shown if the transfer returned a non-zero error. 135(Added in 7.75.0) 136 137## `proxy_ssl_verify_result` 138The result of the HTTPS proxy's SSL peer certificate verification that was 139requested. 0 means the verification was successful. (Added in 7.52.0) 140 141## `proxy_used` 142Returns 1 if the previous transfer used a proxy, otherwise 0. Useful to for 143example determine if a `NOPROXY` pattern matched the hostname or not. (Added 144in 8.7.0) 145 146## `redirect_url` 147When an HTTP request was made without --location to follow redirects (or when 148--max-redirs is met), this variable shows the actual URL a redirect 149*would* have gone to. (Added in 7.18.2) 150 151## `referer` 152The Referer: header, if there was any. (Added in 7.76.0) 153 154## `remote_ip` 155The remote IP address of the most recently done connection - can be either 156IPv4 or IPv6. (Added in 7.29.0) 157 158## `remote_port` 159The remote port number of the most recently done connection. (Added in 7.29.0) 160 161## `response_code` 162The numerical response code that was found in the last transfer (formerly 163known as "http_code"). (Added in 7.18.2) 164 165## `scheme` 166The URL scheme (sometimes called protocol) that was effectively used. (Added in 7.52.0) 167 168## `size_download` 169The total amount of bytes that were downloaded. This is the size of the 170body/data that was transferred, excluding headers. 171 172## `size_header` 173The total amount of bytes of the downloaded headers. 174 175## `size_request` 176The total amount of bytes that were sent in the HTTP request. 177 178## `size_upload` 179The total amount of bytes that were uploaded. This is the size of the 180body/data that was transferred, excluding headers. 181 182## `speed_download` 183The average download speed that curl measured for the complete download. Bytes 184per second. 185 186## `speed_upload` 187The average upload speed that curl measured for the complete upload. Bytes per 188second. 189 190## `ssl_verify_result` 191The result of the SSL peer certificate verification that was requested. 0 192means the verification was successful. (Added in 7.19.0) 193 194## `stderr` 195From this point on, the --write-out output is written to standard 196error. (Added in 7.63.0) 197 198## `stdout` 199From this point on, the --write-out output is written to standard output. 200This is the default, but can be used to switch back after switching to stderr. 201(Added in 7.63.0) 202 203## `time_appconnect` 204The time, in seconds, it took from the start until the SSL/SSH/etc 205connect/handshake to the remote host was completed. (Added in 7.19.0) 206 207## `time_connect` 208The time, in seconds, it took from the start until the TCP connect to the 209remote host (or proxy) was completed. 210 211## `time_namelookup` 212The time, in seconds, it took from the start until the name resolving was 213completed. 214 215## `time_pretransfer` 216The time, in seconds, it took from the start until the file transfer was just 217about to begin. This includes all pre-transfer commands and negotiations that 218are specific to the particular protocol(s) involved. 219 220## `time_redirect` 221The time, in seconds, it took for all redirection steps including name lookup, 222connect, pretransfer and transfer before the final transaction was 223started. `time_redirect` shows the complete execution time for multiple 224redirections. (Added in 7.12.3) 225 226## `time_starttransfer` 227The time, in seconds, it took from the start until the first byte is received. 228This includes time_pretransfer and also the time the server needed to calculate 229the result. 230 231## `time_total` 232The total time, in seconds, that the full operation lasted. 233 234## `url` 235The URL that was fetched. (Added in 7.75.0) 236 237## `url.scheme` 238The scheme part of the URL that was fetched. (Added in 8.1.0) 239 240## `url.user` 241The user part of the URL that was fetched. (Added in 8.1.0) 242 243## `url.password` 244The password part of the URL that was fetched. (Added in 8.1.0) 245 246## `url.options` 247The options part of the URL that was fetched. (Added in 8.1.0) 248 249## `url.host` 250The host part of the URL that was fetched. (Added in 8.1.0) 251 252## `url.port` 253The port number of the URL that was fetched. If no port number was specified 254and the URL scheme is known, that scheme's default port number is 255shown. (Added in 8.1.0) 256 257## `url.path` 258The path part of the URL that was fetched. (Added in 8.1.0) 259 260## `url.query` 261The query part of the URL that was fetched. (Added in 8.1.0) 262 263## `url.fragment` 264The fragment part of the URL that was fetched. (Added in 8.1.0) 265 266## `url.zoneid` 267The zone id part of the URL that was fetched. (Added in 8.1.0) 268 269## `urle.scheme` 270The scheme part of the effective (last) URL that was fetched. (Added in 8.1.0) 271 272## `urle.user` 273The user part of the effective (last) URL that was fetched. (Added in 8.1.0) 274 275## `urle.password` 276The password part of the effective (last) URL that was fetched. (Added in 8.1.0) 277 278## `urle.options` 279The options part of the effective (last) URL that was fetched. (Added in 8.1.0) 280 281## `urle.host` 282The host part of the effective (last) URL that was fetched. (Added in 8.1.0) 283 284## `urle.port` 285The port number of the effective (last) URL that was fetched. If no port 286number was specified, but the URL scheme is known, that scheme's default port 287number is shown. (Added in 8.1.0) 288 289## `urle.path` 290The path part of the effective (last) URL that was fetched. (Added in 8.1.0) 291 292## `urle.query` 293The query part of the effective (last) URL that was fetched. (Added in 8.1.0) 294 295## `urle.fragment` 296The fragment part of the effective (last) URL that was fetched. (Added in 8.1.0) 297 298## `urle.zoneid` 299The zone id part of the effective (last) URL that was fetched. (Added in 8.1.0) 300 301## `urlnum` 302The URL index number of this transfer, 0-indexed. Unglobbed URLs share the 303same index number as the origin globbed URL. (Added in 7.75.0) 304 305## `url_effective` 306The URL that was fetched last. This is most meaningful if you have told curl 307to follow location: headers. 308
