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, FTP
35 or SMTP response code. This option was previously known as
36 CURLINFO_HTTP_CODE in libcurl 7.10.7 and earlier. The value will
37 be zero if no server response code has been received. Note that
38 a proxy's CONNECT response should be read with
39 CURLINFO_HTTP_CONNECTCODE and not this.
40 Support for SMTP responses added in 7.25.0.
42 CURLINFO_HTTP_CONNECTCODE
44 Pass a pointer to a long to receive the last received proxy
45 response code to a CONNECT request.
46 CURLINFO_FILETIME
48 Pass a pointer to a long to receive the remote time of the
49 retrieved document (in number of seconds since 1 jan 1970 in the
50 GMT/UTC time zone). If you get -1, it can be because of many
51 reasons (unknown, the server hides it or the server doesn't sup‐
52 port the command that tells document time etc) and the time of
53 the document is unknown. Note that you must tell the server to
54 collect this information before the transfer is made, by using
55 the CURLOPT_FILETIME option to curl_easy_setopt(3) or you will
56 unconditionally get a -1 back. (Added in 7.5)
57 CURLINFO_TOTAL_TIME
59 Pass a pointer to a double to receive the total time in seconds
60 for the previous transfer, including name resolving, TCP connect
61 etc.
62 CURLINFO_NAMELOOKUP_TIME
64 Pass a pointer to a double to receive the time, in seconds, it
65 took from the start until the name resolving was completed.
66 CURLINFO_CONNECT_TIME
68 Pass a pointer to a double to receive the time, in seconds, it
69 took from the start until the connect to the remote host (or
70 proxy) was completed.
71 CURLINFO_APPCONNECT_TIME
73 Pass a pointer to a double to receive the time, in seconds, it
74 took from the start until the SSL/SSH connect/handshake to the
75 remote host was completed. This time is most often very near to
76 the PRETRANSFER time, except for cases such as HTTP pippelining
77 where the pretransfer time can be delayed due to waits in line
78 for the pipeline and more. (Added in 7.19.0)
79 CURLINFO_PRETRANSFER_TIME
81 Pass a pointer to a double to receive the time, in seconds, it
82 took from the start until the file transfer is just about to
83 begin. This includes all pre-transfer commands and negotiations
84 that are specific to the particular protocol(s) involved. It
85 does not involve the sending of the protocol- specific request
86 that triggers a transfer.
87 CURLINFO_STARTTRANSFER_TIME
89 Pass a pointer to a double to receive the time, in seconds, it
90 took from the start until the first byte is received by libcurl.
91 This includes CURLINFO_PRETRANSFER_TIME and also the time the
92 server needs to calculate the result.
93 CURLINFO_REDIRECT_TIME
95 Pass a pointer to a double to receive the total time, in sec‐
96 onds, it took for all redirection steps include name lookup,
97 connect, pretransfer and transfer before final transaction was
98 started. CURLINFO_REDIRECT_TIME contains the complete execution
99 time for multiple redirections. (Added in 7.9.7)
100 CURLINFO_REDIRECT_COUNT
102 Pass a pointer to a long to receive the total number of redirec‐
103 tions that were actually followed. (Added in 7.9.7)
104 CURLINFO_REDIRECT_URL
106 Pass a pointer to a char pointer to receive the URL a redirect
107 would take you to if you would enable CURLOPT_FOLLOWLOCATION.
108 This can come very handy if you think using the built-in libcurl
109 redirect logic isn't good enough for you but you would still
110 prefer to avoid implementing all the magic of figuring out the
111 new URL. (Added in 7.18.2)
112 CURLINFO_SIZE_UPLOAD
114 Pass a pointer to a double to receive the total amount of bytes
115 that were uploaded.
116 CURLINFO_SIZE_DOWNLOAD
118 Pass a pointer to a double to receive the total amount of bytes
119 that were downloaded. The amount is only for the latest transfer
120 and will be reset again for each new transfer.
121 CURLINFO_SPEED_DOWNLOAD
123 Pass a pointer to a double to receive the average download speed
124 that curl measured for the complete download. Measured in
125 bytes/second.
126 CURLINFO_SPEED_UPLOAD
128 Pass a pointer to a double to receive the average upload speed
129 that curl measured for the complete upload. Measured in
130 bytes/second.
131 CURLINFO_HEADER_SIZE
133 Pass a pointer to a long to receive the total size of all the
134 headers received. Measured in number of bytes.
135 CURLINFO_REQUEST_SIZE
137 Pass a pointer to a long to receive the total size of the issued
138 requests. This is so far only for HTTP requests. Note that this
139 may be more than one request if FOLLOWLOCATION is true.
140 CURLINFO_SSL_VERIFYRESULT
142 Pass a pointer to a long to receive the result of the certifica‐
143 tion verification that was requested (using the CURLOPT_SSL_VER‐
144 IFYPEER option to curl_easy_setopt(3)).
145 CURLINFO_SSL_ENGINES
147 Pass the address of a 'struct curl_slist *' to receive a linked-
148 list of OpenSSL crypto-engines supported. Note that engines are
149 normally implemented in separate dynamic libraries. Hence not
150 all the returned engines may be available at run-time. NOTE: you
151 must call curl_slist_free_all(3) on the list pointer once you're
152 done with it, as libcurl will not free the data for you. (Added
153 in 7.12.3)
154 CURLINFO_CONTENT_LENGTH_DOWNLOAD
156 Pass a pointer to a double to receive the content-length of the
157 download. This is the value read from the Content-Length: field.
158 Since 7.19.4, this returns -1 if the size isn't known.
159 CURLINFO_CONTENT_LENGTH_UPLOAD
161 Pass a pointer to a double to receive the specified size of the
162 upload. Since 7.19.4, this returns -1 if the size isn't known.
163 CURLINFO_CONTENT_TYPE
165 Pass a pointer to a char pointer to receive the content-type of
166 the downloaded object. This is the value read from the Content-
167 Type: field. If you get NULL, it means that the server didn't
168 send a valid Content-Type header or that the protocol used
169 doesn't support this.
170 CURLINFO_PRIVATE
172 Pass a pointer to a char pointer to receive the pointer to the
173 private data associated with the curl handle (set with the CUR‐
174 LOPT_PRIVATE option to curl_easy_setopt(3)). Please note that
175 for internal reasons, the value is returned as a char pointer,
176 although effectively being a 'void *'. (Added in 7.10.3)
177 CURLINFO_HTTPAUTH_AVAIL
179 Pass a pointer to a long to receive a bitmask indicating the
180 authentication method(s) available. The meaning of the bits is
181 explained in the CURLOPT_HTTPAUTH option for
182 curl_easy_setopt(3). (Added in 7.10.8)
183 CURLINFO_PROXYAUTH_AVAIL
185 Pass a pointer to a long to receive a bitmask indicating the
186 authentication method(s) available for your proxy authentica‐
187 tion. (Added in 7.10.8)
188 CURLINFO_OS_ERRNO
190 Pass a pointer to a long to receive the errno variable from a
191 connect failure. Note that the value is only set on failure, it
192 is not reset upon a successful operation. (Added in 7.12.2)
193 CURLINFO_NUM_CONNECTS
195 Pass a pointer to a long to receive how many new connections
196 libcurl had to create to achieve the previous transfer (only the
197 successful connects are counted). Combined with CURLINFO_REDI‐
198 RECT_COUNT you are able to know how many times libcurl success‐
199 fully reused existing connection(s) or not. See the Connection
200 Options of curl_easy_setopt(3) to see how libcurl tries to make
201 persistent connections to save time. (Added in 7.12.3)
202 CURLINFO_PRIMARY_IP
204 Pass a pointer to a char pointer to receive the pointer to a
205 zero-terminated string holding the IP address of the most recent
206 connection done with this curl handle. This string may be IPv6
207 if that's enabled. Note that you get a pointer to a memory area
208 that will be re-used at next request so you need to copy the
209 string if you want to keep the information. (Added in 7.19.0)
210 CURLINFO_PRIMARY_PORT
212 Pass a pointer to a long to receive the destination port of the
213 most recent connection done with this curl handle. (Added in
214 7.21.0)
215 CURLINFO_LOCAL_IP
217 Pass a pointer to a char pointer to receive the pointer to a
218 zero-terminated string holding the local (source) IP address of
219 the most recent connection done with this curl handle. This
220 string may be IPv6 if that's enabled. The same restrictions
221 apply as to CURLINFO_PRIMARY_IP. (Added in 7.21.0)
222 CURLINFO_LOCAL_PORT
224 Pass a pointer to a long to receive the local (source) port of
225 the most recent connection done with this curl handle. (Added in
226 7.21.0)
227 CURLINFO_COOKIELIST
229 Pass a pointer to a 'struct curl_slist *' to receive a linked-
230 list of all cookies cURL knows (expired ones, too). Don't forget
231 to curl_slist_free_all(3) the list after it has been used. If
232 there are no cookies (cookies for the handle have not been
233 enabled or simply none have been received) 'struct curl_slist *'
234 will be set to point to NULL. (Added in 7.14.1)
235 CURLINFO_LASTSOCKET
237 Pass a pointer to a long to receive the last socket used by this
238 curl session. If the socket is no longer valid, -1 is returned.
239 When you finish working with the socket, you must call
240 curl_easy_cleanup() as usual and let libcurl close the socket
241 and cleanup other resources associated with the handle. This is
242 typically used in combination with CURLOPT_CONNECT_ONLY. (Added
243 in 7.15.2)
244 NOTE: this API is not really working on win64, since the SOCKET
246 type on win64 is 64 bit large while its 'long' is only 32 bits.
247 CURLINFO_FTP_ENTRY_PATH
249 Pass a pointer to a char pointer to receive a pointer to a
250 string holding the path of the entry path. That is the initial
251 path libcurl ended up in when logging on to the remote FTP
252 server. This stores a NULL as pointer if something is wrong.
253 (Added in 7.15.4)
254 Also works for SFTP since 7.21.4
256 CURLINFO_CERTINFO
258 Pass a pointer to a 'struct curl_certinfo *' and you'll get it
259 set to point to struct that holds a number of linked lists with
260 info about the certificate chain, assuming you had CURLOPT_CERT‐
261 INFO enabled when the previous request was done. The struct
262 reports how many certs it found and then you can extract info
263 for each of those certs by following the linked lists. The info
264 chain is provided in a series of data in the format "name:con‐
265 tent" where the content is for the specific named data. See also
266 the certinfo.c example. NOTE: this option is only available in
267 libcurl built with OpenSSL support. (Added in 7.19.1)
268 CURLINFO_CONDITION_UNMET
270 Pass a pointer to a long to receive the number 1 if the condi‐
271 tion provided in the previous request didn't match (see CUR‐
272 LOPT_TIMECONDITION). Alas, if this returns a 1 you know that the
273 reason you didn't get data in return is because it didn't ful‐
274 fill the condition. The long ths argument points to will get a
275 zero stored if the condition instead was met. (Added in 7.19.4)
276 CURLINFO_RTSP_SESSION_ID
278 Pass a pointer to a char pointer to receive a pointer to a
279 string holding the most recent RTSP Session ID.
280 Applications wishing to resume an RTSP session on another con‐
282 nection should retreive this info before closing the active con‐
283 nection.
284 CURLINFO_RTSP_CLIENT_CSEQ
286 Pass a pointer to a long to receive the next CSeq that will be
287 used by the application.
288 CURLINFO_RTSP_SERVER_CSEQ
290 Pass a pointer to a long to receive the next server CSeq that
291 will be expected by the application.
292 (NOTE: listening for server initiated requests is currently
294 unimplemented).
295 Applications wishing to resume an RTSP session on another con‐
297 nection should retreive this info before closing the active con‐
298 nection.
299 CURLINFO_RTSP_CSEQ_RECV
301 Pass a pointer to a long to receive the most recently received
302 CSeq from the server. If your application encounters a
303 CURLE_RTSP_CSEQ_ERROR then you may wish to troubleshoot and/or
304 fix the CSeq mismatch by peeking at this value.
305
307 An overview of the six time values available from curl_easy_getinfo()
308 curl_easy_perform()
310 |
311 |--NAMELOOKUP
312 |--|--CONNECT
313 |--|--|--APPCONNECT
314 |--|--|--|--PRETRANSFER
315 |--|--|--|--|--STARTTRANSFER
316 |--|--|--|--|--|--TOTAL
317 |--|--|--|--|--|--REDIRECT
318 NAMELOOKUP
320 CURLINFO_NAMELOOKUP_TIME. The time it took from the start until
321 the name resolving was completed.
322 CONNECT
324 CURLINFO_CONNECT_TIME. The time it took from the start until the
325 connect to the remote host (or proxy) was completed.
326 APPCONNECT
328 CURLINFO_APPCONNECT_TIME. The time it took from the start until
329 the SSL connect/handshake with the remote host was completed.
330 (Added in in 7.19.0)
331 PRETRANSFER
333 CURLINFO_PRETRANSFER_TIME. The time it took from the start until
334 the file transfer is just about to begin. This includes all pre-
335 transfer commands and negotiations that are specific to the par‐
336 ticular protocol(s) involved.
337 STARTTRANSFER
339 CURLINFO_STARTTRANSFER_TIME. The time it took from the start
340 until the first byte is received by libcurl.
341 TOTAL CURLINFO_TOTAL_TIME. Total time of the previous request.
343 REDIRECT
345 CURLINFO_REDIRECT_TIME. The time it took for all redirection
346 steps include name lookup, connect, pretransfer and transfer
347 before final transaction was started. So, this is zero if no re‐
348 direction took place.
349
351 If the operation was successful, CURLE_OK is returned. Otherwise an
352 appropriate error code will be returned.
353
355 curl_easy_setopt(3)
356libcurl 7.19.4 11 Feb 2009 curl_easy_getinfo(3)