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 successfull 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_PRIMARY_PORT
207 Pass a pointer to a long to receive the destination port of the
208 most recent connection done with this curl handle. (Added in
209 7.21.0)
210 CURLINFO_LOCAL_IP
212 Pass a pointer to a char pointer to receive the pointer to a
213 zero-terminated string holding the local (source) IP address of
214 the most recent connection done with this curl handle. This
215 string may be IPv6 if that's enabled. The same restrictions
216 apply as to CURLINFO_PRIMARY_IP. (Added in 7.21.0)
217 CURLINFO_LOCAL_PORT
219 Pass a pointer to a long to receive the local (source) port of
220 the most recent connection done with this curl handle. (Added in
221 7.21.0)
222 CURLINFO_COOKIELIST
224 Pass a pointer to a 'struct curl_slist *' to receive a linked-
225 list of all cookies cURL knows (expired ones, too). Don't forget
226 to curl_slist_free_all(3) the list after it has been used. If
227 there are no cookies (cookies for the handle have not been
228 enabled or simply none have been received) 'struct curl_slist *'
229 will be set to point to NULL. (Added in 7.14.1)
230 CURLINFO_LASTSOCKET
232 Pass a pointer to a long to receive the last socket used by this
233 curl session. If the socket is no longer valid, -1 is returned.
234 When you finish working with the socket, you must call
235 curl_easy_cleanup() as usual and let libcurl close the socket
236 and cleanup other resources associated with the handle. This is
237 typically used in combination with CURLOPT_CONNECT_ONLY. (Added
238 in 7.15.2)
239 CURLINFO_FTP_ENTRY_PATH
241 Pass a pointer to a char pointer to receive a pointer to a
242 string holding the path of the entry path. That is the initial
243 path libcurl ended up in when logging on to the remote FTP
244 server. This stores a NULL as pointer if something is wrong.
245 (Added in 7.15.4)
246 CURLINFO_CERTINFO
248 Pass a pointer to a 'struct curl_certinfo *' and you'll get it
249 set to point to struct that holds a number of linked lists with
250 info about the certificate chain, assuming you had CURLOPT_CERT‐
251 INFO enabled when the previous request was done. The struct
252 reports how many certs it found and then you can extract info
253 for each of those certs by following the linked lists. The info
254 chain is provided in a series of data in the format "name:con‐
255 tent" where the content is for the specific named data. See also
256 the certinfo.c example. NOTE: this option is only available in
257 libcurl built with OpenSSL support. (Added in 7.19.1)
258 CURLINFO_CONDITION_UNMET
260 Pass a pointer to a long to receive the number 1 if the condi‐
261 tion provided in the previous request didn't match (see CUR‐
262 LOPT_TIMECONDITION). Alas, if this returns a 1 you know that the
263 reason you didn't get data in return is because it didn't ful‐
264 fill the condition. The long ths argument points to will get a
265 zero stored if the condition instead was met. (Added in 7.19.4)
266 CURLINFO_RTSP_SESSION_ID
268 Pass a pointer to a char pointer to receive a pointer to a
269 string holding the most recent RTSP Session ID.
270 Applications wishing to resume an RTSP session on another con‐
272 nection should retreive this info before closing the active con‐
273 nection.
274 CURLINFO_RTSP_CLIENT_CSEQ
276 Pass a pointer to a long to receive the next CSeq that will be
277 used by the application.
278 CURLINFO_RTSP_SERVER_CSEQ
280 Pass a pointer to a long to receive the next server CSeq that
281 will be expected by the application.
282 (NOTE: listening for server initiated requests is currently
284 unimplemented).
285 Applications wishing to resume an RTSP session on another con‐
287 nection should retreive this info before closing the active con‐
288 nection.
289 CURLINFO_RTSP_CSEQ_RECV
291 Pass a pointer to a long to receive the most recently received
292 CSeq from the server. If your application encounters a
293 CURLE_RTSP_CSEQ_ERROR then you may wish to troubleshoot and/or
294 fix the CSeq mismatch by peeking at this value.
295
297 An overview of the six time values available from curl_easy_getinfo()
298 curl_easy_perform()
300 |
301 |--NAMELOOKUP
302 |--|--CONNECT
303 |--|--|--APPCONNECT
304 |--|--|--|--PRETRANSFER
305 |--|--|--|--|--STARTTRANSFER
306 |--|--|--|--|--|--TOTAL
307 |--|--|--|--|--|--REDIRECT
308 NAMELOOKUP
310 CURLINFO_NAMELOOKUP_TIME. The time it took from the start until
311 the name resolving was completed.
312 CONNECT
314 CURLINFO_CONNECT_TIME. The time it took from the start until the
315 connect to the remote host (or proxy) was completed.
316 APPCONNECT
318 CURLINFO_APPCONNECT_TIME. The time it took from the start until
319 the SSL connect/handshake with the remote host was completed.
320 (Added in in 7.19.0)
321 PRETRANSFER
323 CURLINFO_PRETRANSFER_TIME. The time it took from the start until
324 the file transfer is just about to begin. This includes all pre-
325 transfer commands and negotiations that are specific to the par‐
326 ticular protocol(s) involved.
327 STARTTRANSFER
329 CURLINFO_STARTTRANSFER_TIME. The time it took from the start
330 until the first byte is just about to be transferred.
331 TOTAL CURLINFO_TOTAL_TIME. Total time of the previous request.
333 REDIRECT
335 CURLINFO_REDIRECT_TIME. The time it took for all redirection
336 steps include name lookup, connect, pretransfer and transfer
337 before final transaction was started. So, this is zero if no re‐
338 direction took place.
339
341 If the operation was successful, CURLE_OK is returned. Otherwise an
342 appropriate error code will be returned.
343
345 curl_easy_setopt(3)
346libcurl 7.19.4 11 Feb 2009 curl_easy_getinfo(3)