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