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