1curl_easy_getinfo(3) libcurl Manual curl_easy_getinfo(3)
2
6 curl_easy_getinfo - extract information from a curl handle
7
9 #include <curl/curl.h>
10 CURLcode curl_easy_getinfo(CURL *curl, CURLINFO info, ... );
12
15 Request internal information from the curl session with this function.
16 The third argument MUST be a pointer to a long, a pointer to a char *,
17 a pointer to a struct curl_slist * or a pointer to a double (as this
18 documentation describes further down). The data pointed-to will be
19 filled in accordingly and can be relied upon only if the function
20 returns CURLE_OK. Use this function AFTER a performed transfer if you
21 want to get transfer- oriented data.
22 You should not free the memory returned by this function unless it is
24 explicitly mentioned below.
25
27 The following information can be extracted:
28 CURLINFO_EFFECTIVE_URL
30 Pass a pointer to a char pointer to receive the last used effec‐
31 tive URL.
32 CURLINFO_RESPONSE_CODE
34 Pass a pointer to a long to receive the last received HTTP or
35 FTP code. This option was known as CURLINFO_HTTP_CODE in libcurl
36 7.10.7 and earlier. This will be zero if no server response code
37 has been received. Note that a proxy's CONNECT response should
38 be read with CURLINFO_HTTP_CONNECTCODE and not this.
39 CURLINFO_HTTP_CONNECTCODE
41 Pass a pointer to a long to receive the last received proxy
42 response code to a CONNECT request.
43 CURLINFO_FILETIME
45 Pass a pointer to a long to receive the remote time of the
46 retrieved document (in number of seconds since 1 jan 1970 in the
47 GMT/UTC time zone). If you get -1, it can be because of many
48 reasons (unknown, the server hides it or the server doesn't sup‐
49 port the command that tells document time etc) and the time of
50 the document is unknown. Note that you must tell the server to
51 collect this information before the transfer is made, by using
52 the CURLOPT_FILETIME option to curl_easy_setopt(3) or you will
53 unconditionally get a -1 back. (Added in 7.5)
54 CURLINFO_TOTAL_TIME
56 Pass a pointer to a double to receive the total time in seconds
57 for the previous transfer, including name resolving, TCP connect
58 etc.
59 CURLINFO_NAMELOOKUP_TIME
61 Pass a pointer to a double to receive the time, in seconds, it
62 took from the start until the name resolving was completed.
63 CURLINFO_CONNECT_TIME
65 Pass a pointer to a double to receive the time, in seconds, it
66 took from the start until the connect to the remote host (or
67 proxy) was completed.
68 CURLINFO_APPCONNECT_TIME
70 Pass a pointer to a double to receive the time, in seconds, it
71 took from the start until the SSL/SSH connect/handshake to the
72 remote host was completed. This time is most often very near to
73 the PRETRANSFER time, except for cases such as HTTP pippelining
74 where the pretransfer time can be delayed due to waits in line
75 for the pipeline and more. (Added in 7.19.0)
76 CURLINFO_PRETRANSFER_TIME
78 Pass a pointer to a double to receive the time, in seconds, it
79 took from the start until the file transfer is just about to
80 begin. This includes all pre-transfer commands and negotiations
81 that are specific to the particular protocol(s) involved.
82 CURLINFO_STARTTRANSFER_TIME
84 Pass a pointer to a double to receive the time, in seconds, it
85 took from the start until the first byte is just about to be
86 transferred. This includes CURLINFO_PRETRANSFER_TIME and also
87 the time the server needs to calculate the result.
88 CURLINFO_REDIRECT_TIME
90 Pass a pointer to a double to receive the total time, in sec‐
91 onds, it took for all redirection steps include name lookup,
92 connect, pretransfer and transfer before final transaction was
93 started. CURLINFO_REDIRECT_TIME contains the complete execution
94 time for multiple redirections. (Added in 7.9.7)
95 CURLINFO_REDIRECT_COUNT
97 Pass a pointer to a long to receive the total number of redirec‐
98 tions that were actually followed. (Added in 7.9.7)
99 CURLINFO_REDIRECT_URL
101 Pass a pointer to a char pointer to receive the URL a redirect
102 would take you to if you would enable CURLOPT_FOLLOWLOCATION.
103 This can come very handy if you think using the built-in libcurl
104 redirect logic isn't good enough for you but you would still
105 prefer to avoid implementing all the magic of figuring out the
106 new URL. (Added in 7.18.2)
107 CURLINFO_SIZE_UPLOAD
109 Pass a pointer to a double to receive the total amount of bytes
110 that were uploaded.
111 CURLINFO_SIZE_DOWNLOAD
113 Pass a pointer to a double to receive the total amount of bytes
114 that were downloaded. The amount is only for the latest transfer
115 and will be reset again for each new transfer.
116 CURLINFO_SPEED_DOWNLOAD
118 Pass a pointer to a double to receive the average download speed
119 that curl measured for the complete download. Measured in
120 bytes/second.
121 CURLINFO_SPEED_UPLOAD
123 Pass a pointer to a double to receive the average upload speed
124 that curl measured for the complete upload. Measured in
125 bytes/second.
126 CURLINFO_HEADER_SIZE
128 Pass a pointer to a long to receive the total size of all the
129 headers received. Measured in number of bytes.
130 CURLINFO_REQUEST_SIZE
132 Pass a pointer to a long to receive the total size of the issued
133 requests. This is so far only for HTTP requests. Note that this
134 may be more than one request if FOLLOWLOCATION is true.
135 CURLINFO_SSL_VERIFYRESULT
137 Pass a pointer to a long to receive the result of the certifica‐
138 tion verification that was requested (using the CURLOPT_SSL_VER‐
139 IFYPEER option to curl_easy_setopt(3)).
140 CURLINFO_SSL_ENGINES
142 Pass the address of a 'struct curl_slist *' to receive a linked-
143 list of OpenSSL crypto-engines supported. Note that engines are
144 normally implemented in separate dynamic libraries. Hence not
145 all the returned engines may be available at run-time. NOTE: you
146 must call curl_slist_free_all(3) on the list pointer once you're
147 done with it, as libcurl will not free the data for you. (Added
148 in 7.12.3)
149 CURLINFO_CONTENT_LENGTH_DOWNLOAD
151 Pass a pointer to a double to receive the content-length of the
152 download. This is the value read from the Content-Length: field.
153 Since 7.19.4, this returns -1 if the size isn't known.
154 CURLINFO_CONTENT_LENGTH_UPLOAD
156 Pass a pointer to a double to receive the specified size of the
157 upload. Since 7.19.4, this returns -1 if the size isn't known.
158 CURLINFO_CONTENT_TYPE
160 Pass a pointer to a char pointer to receive the content-type of
161 the downloaded object. This is the value read from the Content-
162 Type: field. If you get NULL, it means that the server didn't
163 send a valid Content-Type header or that the protocol used
164 doesn't support this.
165 CURLINFO_PRIVATE
167 Pass a pointer to a char pointer to receive the pointer to the
168 private data associated with the curl handle (set with the CUR‐
169 LOPT_PRIVATE option to curl_easy_setopt(3)). Please note that
170 for internal reasons, the value is returned as a char pointer,
171 although effectively being a 'void *'. (Added in 7.10.3)
172 CURLINFO_HTTPAUTH_AVAIL
174 Pass a pointer to a long to receive a bitmask indicating the
175 authentication method(s) available. The meaning of the bits is
176 explained in the CURLOPT_HTTPAUTH option for
177 curl_easy_setopt(3). (Added in 7.10.8)
178 CURLINFO_PROXYAUTH_AVAIL
180 Pass a pointer to a long to receive a bitmask indicating the
181 authentication method(s) available for your proxy authentica‐
182 tion. (Added in 7.10.8)
183 CURLINFO_OS_ERRNO
185 Pass a pointer to a long to receive the errno variable from a
186 connect failure. Note that the value is only set on failure, it
187 is not reset upon a successful operation. (Added in 7.12.2)
188 CURLINFO_NUM_CONNECTS
190 Pass a pointer to a long to receive how many new connections
191 libcurl had to create to achieve the previous transfer (only the
192 successful connects are counted). Combined with CURLINFO_REDI‐
193 RECT_COUNT you are able to know how many times libcurl success‐
194 fully reused existing connection(s) or not. See the Connection
195 Options of curl_easy_setopt(3) to see how libcurl tries to make
196 persistent connections to save time. (Added in 7.12.3)
197 CURLINFO_PRIMARY_IP
199 Pass a pointer to a char pointer to receive the pointer to a
200 zero-terminated string holding the IP address of the most recent
201 connection done with this curl handle. This string may be IPv6
202 if that's enabled. Note that you get a pointer to a memory area
203 that will be re-used at next request so you need to copy the
204 string if you want to keep the information. (Added in 7.19.0)
205 CURLINFO_COOKIELIST
207 Pass a pointer to a 'struct curl_slist *' to receive a linked-
208 list of all cookies cURL knows (expired ones, too). Don't forget
209 to curl_slist_free_all(3) the list after it has been used. If
210 there are no cookies (cookies for the handle have not been
211 enabled or simply none have been received) 'struct curl_slist *'
212 will be set to point to NULL. (Added in 7.14.1)
213 CURLINFO_LASTSOCKET
215 Pass a pointer to a long to receive the last socket used by this
216 curl session. If the socket is no longer valid, -1 is returned.
217 When you finish working with the socket, you must call
218 curl_easy_cleanup() as usual and let libcurl close the socket
219 and cleanup other resources associated with the handle. This is
220 typically used in combination with CURLOPT_CONNECT_ONLY. (Added
221 in 7.15.2)
222 CURLINFO_FTP_ENTRY_PATH
224 Pass a pointer to a char pointer to receive a pointer to a
225 string holding the path of the entry path. That is the initial
226 path libcurl ended up in when logging on to the remote FTP
227 server. This stores a NULL as pointer if something is wrong.
228 (Added in 7.15.4)
229 CURLINFO_CERTINFO
231 Pass a pointer to a 'struct curl_certinfo *' and you'll get it
232 set to point to struct that holds a number of linked lists with
233 info about the certificate chain, assuming you had CURLOPT_CERT‐
234 INFO enabled when the previous request was done. The struct
235 reports how many certs it found and then you can extract info
236 for each of those certs by following the linked lists. The info
237 chain is provided in a series of data in the format "name:con‐
238 tent" where the content is for the specific named data. See also
239 the certinfo.c example. NOTE: this option is only available in
240 libcurl built with OpenSSL support. (Added in 7.19.1)
241 CURLINFO_CONDITION_UNMET
243 Pass a pointer to a long to receive the number 1 if the condi‐
244 tion provided in the previous request didn't match (see CUR‐
245 LOPT_TIMECONDITION). Alas, if this returns a 1 you know that the
246 reason you didn't get data in return is because it didn't ful‐
247 fill the condition. The long ths argument points to will get a
248 zero stored if the condition instead was met. (Added in 7.19.4)
249
251 An overview of the six time values available from curl_easy_getinfo()
252 curl_easy_perform()
254 |
255 |--NAMELOOKUP
256 |--|--CONNECT
257 |--|--|--APPCONNECT
258 |--|--|--|--PRETRANSFER
259 |--|--|--|--|--STARTTRANSFER
260 |--|--|--|--|--|--TOTAL
261 |--|--|--|--|--|--REDIRECT
262 NAMELOOKUP
264 CURLINFO_NAMELOOKUP_TIME. The time it took from the start until
265 the name resolving was completed.
266 CONNECT
268 CURLINFO_CONNECT_TIME. The time it took from the start until the
269 connect to the remote host (or proxy) was completed.
270 APPCONNECT
272 CURLINFO_APPCONNECT_TIME. The time it took from the start until
273 the SSL connect/handshake with the remote host was completed.
274 (Added in in 7.19.0)
275 PRETRANSFER
277 CURLINFO_PRETRANSFER_TIME. The time it took from the start until
278 the file transfer is just about to begin. This includes all pre-
279 transfer commands and negotiations that are specific to the par‐
280 ticular protocol(s) involved.
281 STARTTRANSFER
283 CURLINFO_STARTTRANSFER_TIME. The time it took from the start
284 until the first byte is just about to be transferred.
285 TOTAL CURLINFO_TOTAL_TIME. Total time of the previous request.
287 REDIRECT
289 CURLINFO_REDIRECT_TIME. The time it took for all redirection
290 steps include name lookup, connect, pretransfer and transfer
291 before final transaction was started. So, this is zero if no re‐
292 direction took place.
293
295 If the operation was successful, CURLE_OK is returned. Otherwise an
296 appropriate error code will be returned.
297
299 curl_easy_setopt(3)
300libcurl 7.19.4 11 Feb 2009 curl_easy_getinfo(3)