1--- 2c: Copyright (C) Daniel Stenberg, <daniel.se>, et al. 3SPDX-License-Identifier: curl 4Title: curl_easy_getinfo 5Section: 3 6Source: libcurl 7See-also: 8 - curl_easy_setopt (3) 9--- 10 11# NAME 12 13curl_easy_getinfo - extract information from a curl handle 14 15# SYNOPSIS 16 17~~~c 18#include <curl/curl.h> 19 20CURLcode curl_easy_getinfo(CURL *curl, CURLINFO info, ... ); 21~~~ 22 23# DESCRIPTION 24 25Get the *info* kept in the *curl* handle. The third argument **MUST** be 26pointing to the specific type of the used option which is documented in each 27man page of the *info* option. The data is stored accordingly and can be 28relied upon only if this function returns CURLE_OK. Use this function after a 29performed transfer if you want to get transfer related data. 30 31You should not free the memory returned by this function unless it is 32explicitly mentioned below. 33 34# AVAILABLE INFORMATION 35 36The following information can be extracted: 37 38## CURLINFO_EFFECTIVE_METHOD 39 40Last used HTTP method. See CURLINFO_EFFECTIVE_METHOD(3) 41 42## CURLINFO_EFFECTIVE_URL 43 44Last used URL. See CURLINFO_EFFECTIVE_URL(3) 45 46## CURLINFO_RESPONSE_CODE 47 48Last received response code. See CURLINFO_RESPONSE_CODE(3) 49 50## CURLINFO_REFERER 51 52Referrer header. See CURLINFO_REFERER(3) 53 54## CURLINFO_HTTP_CONNECTCODE 55 56Last proxy CONNECT response code. See CURLINFO_HTTP_CONNECTCODE(3) 57 58## CURLINFO_HTTP_VERSION 59 60The http version used in the connection. See CURLINFO_HTTP_VERSION(3) 61 62## CURLINFO_FILETIME 63 64Remote time of the retrieved document. See CURLINFO_FILETIME(3) 65 66## CURLINFO_FILETIME_T 67 68Remote time of the retrieved document. See CURLINFO_FILETIME_T(3) 69 70## CURLINFO_TOTAL_TIME 71 72Total time of previous transfer. See CURLINFO_TOTAL_TIME(3) 73 74## CURLINFO_TOTAL_TIME_T 75 76Total time of previous transfer. See CURLINFO_TOTAL_TIME_T(3) 77 78## CURLINFO_NAMELOOKUP_TIME 79 80Time from start until name resolving completed. See 81CURLINFO_NAMELOOKUP_TIME(3) 82 83## CURLINFO_NAMELOOKUP_TIME_T 84 85Time from start until name resolving completed. See 86CURLINFO_NAMELOOKUP_TIME_T(3) 87 88## CURLINFO_CONNECT_TIME 89 90Time from start until remote host or proxy completed. 91See CURLINFO_CONNECT_TIME(3) 92 93## CURLINFO_CONNECT_TIME_T 94 95Time from start until remote host or proxy completed. 96See CURLINFO_CONNECT_TIME_T(3) 97 98## CURLINFO_APPCONNECT_TIME 99 100Time from start until SSL/SSH handshake completed. 101See CURLINFO_APPCONNECT_TIME(3) 102 103## CURLINFO_APPCONNECT_TIME_T 104 105Time from start until SSL/SSH handshake completed. 106See CURLINFO_APPCONNECT_TIME_T(3) 107 108## CURLINFO_PRETRANSFER_TIME 109 110Time from start until just before the transfer begins. 111See CURLINFO_PRETRANSFER_TIME(3) 112 113## CURLINFO_PRETRANSFER_TIME_T 114 115Time from start until just before the transfer begins. 116See CURLINFO_PRETRANSFER_TIME_T(3) 117 118## CURLINFO_QUEUE_TIME_T 119 120Time during which this transfer was held in a waiting queue. 121See CURLINFO_QUEUE_TIME_T(3) 122 123## CURLINFO_STARTTRANSFER_TIME 124 125Time from start until just when the first byte is received. 126See CURLINFO_STARTTRANSFER_TIME(3) 127 128## CURLINFO_STARTTRANSFER_TIME_T 129 130Time from start until just when the first byte is received. 131See CURLINFO_STARTTRANSFER_TIME_T(3) 132 133## CURLINFO_REDIRECT_TIME 134 135Time taken for all redirect steps before the final transfer. 136See CURLINFO_REDIRECT_TIME(3) 137 138## CURLINFO_REDIRECT_TIME_T 139 140Time taken for all redirect steps before the final transfer. 141See CURLINFO_REDIRECT_TIME_T(3) 142 143## CURLINFO_REDIRECT_COUNT 144 145Total number of redirects that were followed. 146See CURLINFO_REDIRECT_COUNT(3) 147 148## CURLINFO_REDIRECT_URL 149 150URL a redirect would take you to, had you enabled redirects. 151See CURLINFO_REDIRECT_URL(3) 152 153## CURLINFO_SIZE_UPLOAD 154 155(Deprecated) Number of bytes uploaded. 156See CURLINFO_SIZE_UPLOAD(3) 157 158## CURLINFO_SIZE_UPLOAD_T 159 160Number of bytes uploaded. 161See CURLINFO_SIZE_UPLOAD_T(3) 162 163## CURLINFO_SIZE_DOWNLOAD 164 165(Deprecated) Number of bytes downloaded. 166See CURLINFO_SIZE_DOWNLOAD(3) 167 168## CURLINFO_SIZE_DOWNLOAD_T 169 170Number of bytes downloaded. 171See CURLINFO_SIZE_DOWNLOAD_T(3) 172 173## CURLINFO_SPEED_DOWNLOAD 174 175(Deprecated) Average download speed. 176See CURLINFO_SPEED_DOWNLOAD(3) 177 178## CURLINFO_SPEED_DOWNLOAD_T 179 180Average download speed. 181See CURLINFO_SPEED_DOWNLOAD_T(3) 182 183## CURLINFO_SPEED_UPLOAD 184 185(Deprecated) Average upload speed. 186See CURLINFO_SPEED_UPLOAD(3) 187 188## CURLINFO_SPEED_UPLOAD_T 189 190Average upload speed. 191See CURLINFO_SPEED_UPLOAD_T(3) 192 193## CURLINFO_HEADER_SIZE 194 195Number of bytes of all headers received. 196See CURLINFO_HEADER_SIZE(3) 197 198## CURLINFO_REQUEST_SIZE 199 200Number of bytes sent in the issued HTTP requests. 201See CURLINFO_REQUEST_SIZE(3) 202 203## CURLINFO_SSL_VERIFYRESULT 204 205Certificate verification result. 206See CURLINFO_SSL_VERIFYRESULT(3) 207 208## CURLINFO_PROXY_ERROR 209 210Detailed proxy error. 211See CURLINFO_PROXY_ERROR(3) 212 213## CURLINFO_PROXY_SSL_VERIFYRESULT 214 215Proxy certificate verification result. 216See CURLINFO_PROXY_SSL_VERIFYRESULT(3) 217 218## CURLINFO_SSL_ENGINES 219 220A list of OpenSSL crypto engines. 221See CURLINFO_SSL_ENGINES(3) 222 223## CURLINFO_CONTENT_LENGTH_DOWNLOAD 224 225(Deprecated) Content length from the Content-Length header. 226See CURLINFO_CONTENT_LENGTH_DOWNLOAD(3) 227 228## CURLINFO_CONTENT_LENGTH_DOWNLOAD_T 229 230Content length from the Content-Length header. 231See CURLINFO_CONTENT_LENGTH_DOWNLOAD_T(3) 232 233## CURLINFO_CONTENT_LENGTH_UPLOAD 234 235(Deprecated) Upload size. See CURLINFO_CONTENT_LENGTH_UPLOAD(3) 236 237## CURLINFO_CONTENT_LENGTH_UPLOAD_T 238 239Upload size. See CURLINFO_CONTENT_LENGTH_UPLOAD_T(3) 240 241## CURLINFO_CONTENT_TYPE 242 243Content type from the Content-Type header. 244See CURLINFO_CONTENT_TYPE(3) 245 246## CURLINFO_RETRY_AFTER 247 248The value from the Retry-After header. 249See CURLINFO_RETRY_AFTER(3) 250 251## CURLINFO_PRIVATE 252 253User's private data pointer. 254See CURLINFO_PRIVATE(3) 255 256## CURLINFO_HTTPAUTH_AVAIL 257 258Available HTTP authentication methods. 259See CURLINFO_HTTPAUTH_AVAIL(3) 260 261## CURLINFO_PROXYAUTH_AVAIL 262 263Available HTTP proxy authentication methods. 264See CURLINFO_PROXYAUTH_AVAIL(3) 265 266## CURLINFO_OS_ERRNO 267 268The errno from the last failure to connect. 269See CURLINFO_OS_ERRNO(3) 270 271## CURLINFO_NUM_CONNECTS 272 273Number of new successful connections used for previous transfer. 274See CURLINFO_NUM_CONNECTS(3) 275 276## CURLINFO_PRIMARY_IP 277 278Destination IP address of the last connection. 279See CURLINFO_PRIMARY_IP(3) 280 281## CURLINFO_PRIMARY_PORT 282 283Destination port of the last connection. 284See CURLINFO_PRIMARY_PORT(3) 285 286## CURLINFO_LOCAL_IP 287 288Source IP address of the last connection. 289See CURLINFO_LOCAL_IP(3) 290 291## CURLINFO_LOCAL_PORT 292 293Source port number of the last connection. 294See CURLINFO_LOCAL_PORT(3) 295 296## CURLINFO_COOKIELIST 297 298List of all known cookies. 299See CURLINFO_COOKIELIST(3) 300 301## CURLINFO_LASTSOCKET 302 303(Deprecated) Last socket used. 304See CURLINFO_LASTSOCKET(3) 305 306## CURLINFO_ACTIVESOCKET 307 308The session's active socket. 309See CURLINFO_ACTIVESOCKET(3) 310 311## CURLINFO_FTP_ENTRY_PATH 312 313The entry path after logging in to an FTP server. 314See CURLINFO_FTP_ENTRY_PATH(3) 315 316## CURLINFO_CAPATH 317 318Get the default value for CURLOPT_CAPATH(3). 319See CURLINFO_CAPATH(3) 320 321## CURLINFO_CAINFO 322 323Get the default value for CURLOPT_CAINFO(3). 324See CURLINFO_CAINFO(3) 325 326## CURLINFO_CERTINFO 327 328Certificate chain. 329See CURLINFO_CERTINFO(3) 330 331## CURLINFO_TLS_SSL_PTR 332 333TLS session info that can be used for further processing. 334See CURLINFO_TLS_SSL_PTR(3) 335 336## CURLINFO_TLS_SESSION 337 338TLS session info that can be used for further processing. See 339CURLINFO_TLS_SESSION(3). Deprecated option, use 340CURLINFO_TLS_SSL_PTR(3) instead! 341 342## CURLINFO_CONDITION_UNMET 343 344Whether or not a time conditional was met or 304 HTTP response. 345See CURLINFO_CONDITION_UNMET(3) 346 347## CURLINFO_RTSP_SESSION_ID 348 349RTSP session ID. 350See CURLINFO_RTSP_SESSION_ID(3) 351 352## CURLINFO_RTSP_CLIENT_CSEQ 353 354The RTSP client CSeq that is expected next. 355See CURLINFO_RTSP_CLIENT_CSEQ(3) 356 357## CURLINFO_RTSP_SERVER_CSEQ 358 359The RTSP server CSeq that is expected next. 360See CURLINFO_RTSP_SERVER_CSEQ(3) 361 362## CURLINFO_RTSP_CSEQ_RECV 363 364RTSP CSeq last received. 365See CURLINFO_RTSP_CSEQ_RECV(3) 366 367## CURLINFO_PROTOCOL 368 369(Deprecated) The protocol used for the connection. (Added in 7.52.0) 370See CURLINFO_PROTOCOL(3) 371 372## CURLINFO_SCHEME 373 374The scheme used for the connection. (Added in 7.52.0) 375See CURLINFO_SCHEME(3) 376 377## CURLINFO_CONN_ID 378 379The ID of the last connection used by the transfer. (Added in 8.2.0) 380See CURLINFO_CONN_ID(3) 381 382## CURLINFO_XFER_ID 383 384The ID of the transfer. (Added in 8.2.0) 385See CURLINFO_XFER_ID(3) 386 387# TIMES 388 389An overview of the time values available from curl_easy_getinfo(3) 390 391~~~ 392curl_easy_perform() 393 | 394 |--QUEUE_TIME 395 |--|--NAMELOOKUP 396 |--|--|--CONNECT 397 |--|--|--|--APPCONNECT 398 |--|--|--|--|--PRETRANSFER 399 |--|--|--|--|--|--STARTTRANSFER 400 |--|--|--|--|--|--|--TOTAL 401 |--|--|--|--|--|--|--REDIRECT 402~~~ 403 404## QUEUE_TIME 405 406CURLINFO_QUEUE_TIME_T(3). The time during which the transfer was held in a 407waiting queue before it could start for real. (Added in 8.6.0) 408 409## NAMELOOKUP 410 411CURLINFO_NAMELOOKUP_TIME(3) and CURLINFO_NAMELOOKUP_TIME_T(3). The time it 412took from the start until the name resolving was completed. 413 414## CONNECT 415 416CURLINFO_CONNECT_TIME(3) and CURLINFO_CONNECT_TIME_T(3). The time it took from 417the start until the connect to the remote host (or proxy) was completed. 418 419## APPCONNECT 420 421CURLINFO_APPCONNECT_TIME(3) and CURLINFO_APPCONNECT_TIME_T(3). The time it 422took from the start until the SSL connect/handshake with the remote host was 423completed. (Added in 7.19.0) The latter is the integer version (measuring 424microseconds). (Added in 7.60.0) 425 426## PRETRANSFER 427 428CURLINFO_PRETRANSFER_TIME(3) and CURLINFO_PRETRANSFER_TIME_T(3). The time it 429took from the start until the file transfer is just about to begin. This 430includes all pre-transfer commands and negotiations that are specific to the 431particular protocol(s) involved. 432 433## STARTTRANSFER 434 435CURLINFO_STARTTRANSFER_TIME(3) and CURLINFO_STARTTRANSFER_TIME_T(3). The time 436it took from the start until the first byte is received by libcurl. 437 438## TOTAL 439 440CURLINFO_TOTAL_TIME(3) and CURLINFO_TOTAL_TIME_T(3). Total time 441of the previous request. 442 443## REDIRECT 444 445CURLINFO_REDIRECT_TIME(3) and CURLINFO_REDIRECT_TIME_T(3). The time it took 446for all redirection steps include name lookup, connect, pretransfer and 447transfer before final transaction was started. So, this is zero if no 448redirection took place. 449 450# EXAMPLE 451 452~~~c 453int main(void) 454{ 455 CURL *curl = curl_easy_init(); 456 if(curl) { 457 CURLcode res; 458 curl_easy_setopt(curl, CURLOPT_URL, "https://www.example.com/"); 459 res = curl_easy_perform(curl); 460 461 if(CURLE_OK == res) { 462 char *ct; 463 /* ask for the content-type */ 464 res = curl_easy_getinfo(curl, CURLINFO_CONTENT_TYPE, &ct); 465 466 if((CURLE_OK == res) && ct) 467 printf("We received Content-Type: %s\n", ct); 468 } 469 470 /* always cleanup */ 471 curl_easy_cleanup(curl); 472 } 473} 474~~~ 475 476# AVAILABILITY 477 478Added in 7.4.1 479 480# RETURN VALUE 481 482If the operation was successful, CURLE_OK is returned. Otherwise an 483appropriate error code is returned. 484