xf.li | 6c8fc1e | 2023-08-12 00:11:09 -0700 | [diff] [blame] | 1 | c: Copyright (C) 1998 - 2022, Daniel Stenberg, <daniel@haxx.se>, et al. |
| 2 | SPDX-License-Identifier: curl |
| 3 | Long: write-out |
| 4 | Short: w |
| 5 | Arg: <format> |
| 6 | Help: Use output FORMAT after completion |
| 7 | Category: verbose |
| 8 | Example: -w '%{http_code}\\n' $URL |
| 9 | Added: 6.5 |
| 10 | See-also: verbose head |
| 11 | Multi: single |
| 12 | --- |
| 13 | Make curl display information on stdout after a completed transfer. The format |
| 14 | is a string that may contain plain text mixed with any number of |
| 15 | variables. The format can be specified as a literal "string", or you can have |
| 16 | curl read the format from a file with "@filename" and to tell curl to read the |
| 17 | format from stdin you write "@-". |
| 18 | |
| 19 | The variables present in the output format will be substituted by the value or |
| 20 | text that curl thinks fit, as described below. All variables are specified as |
| 21 | %{variable_name} and to output a normal % you just write them as %%. You can |
| 22 | output a newline by using \\n, a carriage return with \\r and a tab space with |
| 23 | \\t. |
| 24 | |
| 25 | The output will be written to standard output, but this can be switched to |
| 26 | standard error by using %{stderr}. |
| 27 | |
| 28 | Output HTTP headers from the most recent request by using \fB%header{name}\fP |
| 29 | where \fBname\fP is the case insensitive name of the header (without the |
| 30 | trailing colon). The header contents are exactly as sent over the network, |
| 31 | with leading and trailing whitespace trimmed. Added in curl 7.84.0. |
| 32 | |
| 33 | .B NOTE: |
| 34 | The %-symbol is a special symbol in the win32-environment, where all |
| 35 | occurrences of % must be doubled when using this option. |
| 36 | |
| 37 | The variables available are: |
| 38 | .RS |
| 39 | .TP 15 |
| 40 | .B content_type |
| 41 | The Content-Type of the requested document, if there was any. |
| 42 | .TP |
| 43 | .B errormsg |
| 44 | The error message. (Added in 7.75.0) |
| 45 | .TP |
| 46 | .B exitcode |
| 47 | The numerical exitcode of the transfer. (Added in 7.75.0) |
| 48 | .TP |
| 49 | .B filename_effective |
| 50 | The ultimate filename that curl writes out to. This is only meaningful if curl |
| 51 | is told to write to a file with the --remote-name or --output |
| 52 | option. It's most useful in combination with the --remote-header-name |
| 53 | option. (Added in 7.26.0) |
| 54 | .TP |
| 55 | .B ftp_entry_path |
| 56 | The initial path curl ended up in when logging on to the remote FTP |
| 57 | server. (Added in 7.15.4) |
| 58 | .TP |
| 59 | .B header_json |
| 60 | A JSON object with all HTTP response headers from the recent transfer. Values |
| 61 | are provided as arrays, since in the case of multiple headers there can be |
| 62 | multiple values. |
| 63 | |
| 64 | The header names provided in lowercase, listed in order of appearance over the |
| 65 | wire. Except for duplicated headers. They are grouped on the first occurrence |
| 66 | of that header, each value is presented in the JSON array. |
| 67 | .TP |
| 68 | .B http_code |
| 69 | The numerical response code that was found in the last retrieved HTTP(S) or |
| 70 | FTP(s) transfer. |
| 71 | .TP |
| 72 | .B http_connect |
| 73 | The numerical code that was found in the last response (from a proxy) to a |
| 74 | curl CONNECT request. (Added in 7.12.4) |
| 75 | .TP |
| 76 | .B http_version |
| 77 | The http version that was effectively used. (Added in 7.50.0) |
| 78 | .TP |
| 79 | .B json |
| 80 | A JSON object with all available keys. |
| 81 | .TP |
| 82 | .B local_ip |
| 83 | The IP address of the local end of the most recently done connection - can be |
| 84 | either IPv4 or IPv6. (Added in 7.29.0) |
| 85 | .TP |
| 86 | .B local_port |
| 87 | The local port number of the most recently done connection. (Added in 7.29.0) |
| 88 | .TP |
| 89 | .B method |
| 90 | The http method used in the most recent HTTP request. (Added in 7.72.0) |
| 91 | .TP |
| 92 | .B num_connects |
| 93 | Number of new connects made in the recent transfer. (Added in 7.12.3) |
| 94 | .TP |
| 95 | .B num_headers |
| 96 | The number of response headers in the most recent request (restarted at each |
| 97 | redirect). Note that the status line IS NOT a header. (Added in 7.73.0) |
| 98 | .TP |
| 99 | .B num_redirects |
| 100 | Number of redirects that were followed in the request. (Added in 7.12.3) |
| 101 | .TP |
| 102 | .B onerror |
| 103 | The rest of the output is only shown if the transfer returned a non-zero error |
| 104 | (Added in 7.75.0) |
| 105 | .TP |
| 106 | .B proxy_ssl_verify_result |
| 107 | The result of the HTTPS proxy's SSL peer certificate verification that was |
| 108 | requested. 0 means the verification was successful. (Added in 7.52.0) |
| 109 | .TP |
| 110 | .B redirect_url |
| 111 | When an HTTP request was made without --location to follow redirects (or when |
| 112 | --max-redirs is met), this variable will show the actual URL a redirect |
| 113 | *would* have gone to. (Added in 7.18.2) |
| 114 | .TP |
| 115 | .B referer |
| 116 | The Referer: header, if there was any. (Added in 7.76.0) |
| 117 | .TP |
| 118 | .B remote_ip |
| 119 | The remote IP address of the most recently done connection - can be either |
| 120 | IPv4 or IPv6. (Added in 7.29.0) |
| 121 | .TP |
| 122 | .B remote_port |
| 123 | The remote port number of the most recently done connection. (Added in 7.29.0) |
| 124 | .TP |
| 125 | .B response_code |
| 126 | The numerical response code that was found in the last transfer (formerly |
| 127 | known as "http_code"). (Added in 7.18.2) |
| 128 | .TP |
| 129 | .B scheme |
| 130 | The URL scheme (sometimes called protocol) that was effectively used. (Added in 7.52.0) |
| 131 | .TP |
| 132 | .B size_download |
| 133 | The total amount of bytes that were downloaded. This is the size of the |
| 134 | body/data that was transferred, excluding headers. |
| 135 | .TP |
| 136 | .B size_header |
| 137 | The total amount of bytes of the downloaded headers. |
| 138 | .TP |
| 139 | .B size_request |
| 140 | The total amount of bytes that were sent in the HTTP request. |
| 141 | .TP |
| 142 | .B size_upload |
| 143 | The total amount of bytes that were uploaded. This is the size of the |
| 144 | body/data that was transferred, excluding headers. |
| 145 | .TP |
| 146 | .B speed_download |
| 147 | The average download speed that curl measured for the complete download. Bytes |
| 148 | per second. |
| 149 | .TP |
| 150 | .B speed_upload |
| 151 | The average upload speed that curl measured for the complete upload. Bytes per |
| 152 | second. |
| 153 | .TP |
| 154 | .B ssl_verify_result |
| 155 | The result of the SSL peer certificate verification that was requested. 0 |
| 156 | means the verification was successful. (Added in 7.19.0) |
| 157 | .TP |
| 158 | .B stderr |
| 159 | From this point on, the --write-out output will be written to standard |
| 160 | error. (Added in 7.63.0) |
| 161 | .TP |
| 162 | .B stdout |
| 163 | From this point on, the --write-out output will be written to standard output. |
| 164 | This is the default, but can be used to switch back after switching to stderr. |
| 165 | (Added in 7.63.0) |
| 166 | .TP |
| 167 | .B time_appconnect |
| 168 | The time, in seconds, it took from the start until the SSL/SSH/etc |
| 169 | connect/handshake to the remote host was completed. (Added in 7.19.0) |
| 170 | .TP |
| 171 | .B time_connect |
| 172 | The time, in seconds, it took from the start until the TCP connect to the |
| 173 | remote host (or proxy) was completed. |
| 174 | .TP |
| 175 | .B time_namelookup |
| 176 | The time, in seconds, it took from the start until the name resolving was |
| 177 | completed. |
| 178 | .TP |
| 179 | .B time_pretransfer |
| 180 | The time, in seconds, it took from the start until the file transfer was just |
| 181 | about to begin. This includes all pre-transfer commands and negotiations that |
| 182 | are specific to the particular protocol(s) involved. |
| 183 | .TP |
| 184 | .B time_redirect |
| 185 | The time, in seconds, it took for all redirection steps including name lookup, |
| 186 | connect, pretransfer and transfer before the final transaction was |
| 187 | started. time_redirect shows the complete execution time for multiple |
| 188 | redirections. (Added in 7.12.3) |
| 189 | .TP |
| 190 | .B time_starttransfer |
| 191 | The time, in seconds, it took from the start until the first byte was just |
| 192 | about to be transferred. This includes time_pretransfer and also the time the |
| 193 | server needed to calculate the result. |
| 194 | .TP |
| 195 | .B time_total |
| 196 | The total time, in seconds, that the full operation lasted. |
| 197 | .TP |
| 198 | .B url |
| 199 | The URL that was fetched. (Added in 7.75.0) |
| 200 | .TP |
| 201 | .B urlnum |
| 202 | The URL index number of this transfer, 0-indexed. De-globbed URLs share the |
| 203 | same index number as the origin globbed URL. (Added in 7.75.0) |
| 204 | .TP |
| 205 | .B url_effective |
| 206 | The URL that was fetched last. This is most meaningful if you have told curl |
| 207 | to follow location: headers. |
| 208 | .RE |
| 209 | .IP |