| .\" ************************************************************************** |
| .\" * _ _ ____ _ |
| .\" * Project ___| | | | _ \| | |
| .\" * / __| | | | |_) | | |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| .\" * Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al. |
| .\" * |
| .\" * This software is licensed as described in the file COPYING, which |
| .\" * you should have received as part of this distribution. The terms |
| .\" * are also available at http://curl.haxx.se/docs/copyright.html. |
| .\" * |
| .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell |
| .\" * copies of the Software, and permit persons to whom the Software is |
| .\" * furnished to do so, under the terms of the COPYING file. |
| .\" * |
| .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY |
| .\" * KIND, either express or implied. |
| .\" * |
| .\" ************************************************************************** |
| .\" |
| .TH curl_easy_getinfo 3 "11 Feb 2009" "libcurl 7.19.4" "libcurl Manual" |
| .SH NAME |
| curl_easy_getinfo - extract information from a curl handle |
| .SH SYNOPSIS |
| .B #include <curl/curl.h> |
| |
| .B "CURLcode curl_easy_getinfo(CURL *curl, CURLINFO info, ... );" |
| |
| .SH DESCRIPTION |
| Request internal information from the curl session with this function. The |
| third argument \fBMUST\fP be a pointer to a long, a pointer to a char *, a |
| pointer to a struct curl_slist * or a pointer to a double (as this |
| documentation describes further down). The data pointed-to will be filled in |
| accordingly and can be relied upon only if the function returns CURLE_OK. Use |
| this function AFTER a performed transfer if you want to get transfer- oriented |
| data. |
| |
| You should not free the memory returned by this function unless it is |
| explicitly mentioned below. |
| .SH AVAILABLE INFORMATION |
| The following information can be extracted: |
| .IP CURLINFO_EFFECTIVE_URL |
| Pass a pointer to a char pointer to receive the last used effective URL. |
| .IP CURLINFO_RESPONSE_CODE |
| Pass a pointer to a long to receive the last received HTTP, FTP or SMTP |
| response code. This option was previously known as CURLINFO_HTTP_CODE in |
| libcurl 7.10.7 and earlier. The value will be zero if no server response code |
| has been received. Note that a proxy's CONNECT response should be read with |
| \fICURLINFO_HTTP_CONNECTCODE\fP and not this. |
| |
| Support for SMTP responses added in 7.25.0. |
| .IP CURLINFO_HTTP_CONNECTCODE |
| Pass a pointer to a long to receive the last received proxy response code to a |
| CONNECT request. |
| .IP CURLINFO_FILETIME |
| Pass a pointer to a long to receive the remote time of the retrieved document |
| (in number of seconds since 1 jan 1970 in the GMT/UTC time zone). If you get |
| -1, it can be because of many reasons (unknown, the server hides it or the |
| server doesn't support the command that tells document time etc) and the time |
| of the document is unknown. Note that you must tell the server to collect this |
| information before the transfer is made, by using the CURLOPT_FILETIME option |
| to \fIcurl_easy_setopt(3)\fP or you will unconditionally get a -1 back. (Added |
| in 7.5) |
| .IP CURLINFO_TOTAL_TIME |
| Pass a pointer to a double to receive the total time in seconds for the |
| previous transfer, including name resolving, TCP connect etc. |
| .IP CURLINFO_NAMELOOKUP_TIME |
| Pass a pointer to a double to receive the time, in seconds, it took from the |
| start until the name resolving was completed. |
| .IP CURLINFO_CONNECT_TIME |
| Pass a pointer to a double to receive the time, in seconds, it took from the |
| start until the connect to the remote host (or proxy) was completed. |
| .IP CURLINFO_APPCONNECT_TIME |
| Pass a pointer to a double to receive the time, in seconds, it took from the |
| start until the SSL/SSH connect/handshake to the remote host was completed. |
| This time is most often very near to the PRETRANSFER time, except for cases |
| such as HTTP pippelining where the pretransfer time can be delayed due to |
| waits in line for the pipeline and more. (Added in 7.19.0) |
| .IP CURLINFO_PRETRANSFER_TIME |
| Pass a pointer to a double to receive the time, in seconds, it took from the |
| start until the file transfer is just about to begin. This includes all |
| pre-transfer commands and negotiations that are specific to the particular |
| protocol(s) involved. It does \fInot\fP involve the sending of the protocol- |
| specific request that triggers a transfer. |
| .IP CURLINFO_STARTTRANSFER_TIME |
| Pass a pointer to a double to receive the time, in seconds, it took from the |
| start until the first byte is received by libcurl. This includes |
| CURLINFO_PRETRANSFER_TIME and also the time the server needs to calculate the |
| result. |
| .IP CURLINFO_REDIRECT_TIME |
| Pass a pointer to a double to receive the total time, in seconds, it took for |
| all redirection steps include name lookup, connect, pretransfer and transfer |
| before final transaction was started. CURLINFO_REDIRECT_TIME contains the |
| complete execution time for multiple redirections. (Added in 7.9.7) |
| .IP CURLINFO_REDIRECT_COUNT |
| Pass a pointer to a long to receive the total number of redirections that were |
| actually followed. (Added in 7.9.7) |
| .IP CURLINFO_REDIRECT_URL |
| Pass a pointer to a char pointer to receive the URL a redirect \fIwould\fP |
| take you to if you would enable CURLOPT_FOLLOWLOCATION. This can come very |
| handy if you think using the built-in libcurl redirect logic isn't good enough |
| for you but you would still prefer to avoid implementing all the magic of |
| figuring out the new URL. (Added in 7.18.2) |
| .IP CURLINFO_SIZE_UPLOAD |
| Pass a pointer to a double to receive the total amount of bytes that were |
| uploaded. |
| .IP CURLINFO_SIZE_DOWNLOAD |
| Pass a pointer to a double to receive the total amount of bytes that were |
| downloaded. The amount is only for the latest transfer and will be reset again |
| for each new transfer. |
| .IP CURLINFO_SPEED_DOWNLOAD |
| Pass a pointer to a double to receive the average download speed that curl |
| measured for the complete download. Measured in bytes/second. |
| .IP CURLINFO_SPEED_UPLOAD |
| Pass a pointer to a double to receive the average upload speed that curl |
| measured for the complete upload. Measured in bytes/second. |
| .IP CURLINFO_HEADER_SIZE |
| Pass a pointer to a long to receive the total size of all the headers |
| received. Measured in number of bytes. |
| .IP CURLINFO_REQUEST_SIZE |
| Pass a pointer to a long to receive the total size of the issued |
| requests. This is so far only for HTTP requests. Note that this may be more |
| than one request if FOLLOWLOCATION is true. |
| .IP CURLINFO_SSL_VERIFYRESULT |
| Pass a pointer to a long to receive the result of the certification |
| verification that was requested (using the CURLOPT_SSL_VERIFYPEER option to |
| \fIcurl_easy_setopt(3)\fP). |
| .IP CURLINFO_SSL_ENGINES |
| Pass the address of a 'struct curl_slist *' to receive a linked-list of |
| OpenSSL crypto-engines supported. Note that engines are normally implemented |
| in separate dynamic libraries. Hence not all the returned engines may be |
| available at run-time. \fBNOTE:\fP you must call \fIcurl_slist_free_all(3)\fP |
| on the list pointer once you're done with it, as libcurl will not free the |
| data for you. (Added in 7.12.3) |
| .IP CURLINFO_CONTENT_LENGTH_DOWNLOAD |
| Pass a pointer to a double to receive the content-length of the download. This |
| is the value read from the Content-Length: field. Since 7.19.4, this returns -1 |
| if the size isn't known. |
| .IP CURLINFO_CONTENT_LENGTH_UPLOAD |
| Pass a pointer to a double to receive the specified size of the upload. Since |
| 7.19.4, this returns -1 if the size isn't known. |
| .IP CURLINFO_CONTENT_TYPE |
| Pass a pointer to a char pointer to receive the content-type of the downloaded |
| object. This is the value read from the Content-Type: field. If you get NULL, |
| it means that the server didn't send a valid Content-Type header or that the |
| protocol used doesn't support this. |
| .IP CURLINFO_PRIVATE |
| Pass a pointer to a char pointer to receive the pointer to the private data |
| associated with the curl handle (set with the CURLOPT_PRIVATE option to |
| \fIcurl_easy_setopt(3)\fP). Please note that for internal reasons, the |
| value is returned as a char pointer, although effectively being a 'void *'. |
| (Added in 7.10.3) |
| .IP CURLINFO_HTTPAUTH_AVAIL |
| Pass a pointer to a long to receive a bitmask indicating the authentication |
| method(s) available. The meaning of the bits is explained in the |
| CURLOPT_HTTPAUTH option for \fIcurl_easy_setopt(3)\fP. (Added in 7.10.8) |
| .IP CURLINFO_PROXYAUTH_AVAIL |
| Pass a pointer to a long to receive a bitmask indicating the authentication |
| method(s) available for your proxy authentication. (Added in 7.10.8) |
| .IP CURLINFO_OS_ERRNO |
| Pass a pointer to a long to receive the errno variable from a connect failure. |
| Note that the value is only set on failure, it is not reset upon a |
| successfull operation. (Added in 7.12.2) |
| .IP CURLINFO_NUM_CONNECTS |
| Pass a pointer to a long to receive how many new connections libcurl had to |
| create to achieve the previous transfer (only the successful connects are |
| counted). Combined with \fICURLINFO_REDIRECT_COUNT\fP you are able to know |
| how many times libcurl successfully reused existing connection(s) or not. See |
| the Connection Options of \fIcurl_easy_setopt(3)\fP to see how libcurl tries |
| to make persistent connections to save time. (Added in 7.12.3) |
| .IP CURLINFO_PRIMARY_IP |
| Pass a pointer to a char pointer to receive the pointer to a zero-terminated |
| string holding the IP address of the most recent connection done with this |
| \fBcurl\fP handle. This string may be IPv6 if that's enabled. Note that you |
| get a pointer to a memory area that will be re-used at next request so you |
| need to copy the string if you want to keep the information. (Added in 7.19.0) |
| .IP CURLINFO_PRIMARY_PORT |
| Pass a pointer to a long to receive the destination port of the most recent |
| connection done with this \fBcurl\fP handle. (Added in 7.21.0) |
| .IP CURLINFO_LOCAL_IP |
| Pass a pointer to a char pointer to receive the pointer to a zero-terminated |
| string holding the local (source) IP address of the most recent connection done |
| with this \fBcurl\fP handle. This string may be IPv6 if that's enabled. The |
| same restrictions apply as to \fICURLINFO_PRIMARY_IP\fP. (Added in 7.21.0) |
| .IP CURLINFO_LOCAL_PORT |
| Pass a pointer to a long to receive the local (source) port of the most recent |
| connection done with this \fBcurl\fP handle. (Added in 7.21.0) |
| .IP CURLINFO_COOKIELIST |
| Pass a pointer to a 'struct curl_slist *' to receive a linked-list of all |
| cookies cURL knows (expired ones, too). Don't forget to |
| \fIcurl_slist_free_all(3)\fP the list after it has been used. If there are no |
| cookies (cookies for the handle have not been enabled or simply none have been |
| received) 'struct curl_slist *' will be set to point to NULL. (Added in |
| 7.14.1) |
| .IP CURLINFO_LASTSOCKET |
| Pass a pointer to a long to receive the last socket used by this curl |
| session. If the socket is no longer valid, -1 is returned. When you finish |
| working with the socket, you must call curl_easy_cleanup() as usual and let |
| libcurl close the socket and cleanup other resources associated with the |
| handle. This is typically used in combination with \fICURLOPT_CONNECT_ONLY\fP. |
| (Added in 7.15.2) |
| |
| NOTE: this API is not really working on win64, since the SOCKET type on win64 |
| is 64 bit large while its 'long' is only 32 bits. |
| .IP CURLINFO_FTP_ENTRY_PATH |
| Pass a pointer to a char pointer to receive a pointer to a string holding the |
| path of the entry path. That is the initial path libcurl ended up in when |
| logging on to the remote FTP server. This stores a NULL as pointer if |
| something is wrong. (Added in 7.15.4) |
| |
| Also works for SFTP since 7.21.4 |
| .IP CURLINFO_CERTINFO |
| Pass a pointer to a 'struct curl_certinfo *' and you'll get it set to point to |
| struct that holds a number of linked lists with info about the certificate |
| chain, assuming you had CURLOPT_CERTINFO enabled when the previous request was |
| done. The struct reports how many certs it found and then you can extract info |
| for each of those certs by following the linked lists. The info chain is |
| provided in a series of data in the format "name:content" where the content is |
| for the specific named data. See also the certinfo.c example. NOTE: this |
| option is only available in libcurl built with OpenSSL support. (Added in |
| 7.19.1) |
| .IP CURLINFO_CONDITION_UNMET |
| Pass a pointer to a long to receive the number 1 if the condition provided in |
| the previous request didn't match (see \fICURLOPT_TIMECONDITION\fP). Alas, if |
| this returns a 1 you know that the reason you didn't get data in return is |
| because it didn't fulfill the condition. The long ths argument points to will |
| get a zero stored if the condition instead was met. (Added in 7.19.4) |
| .IP CURLINFO_RTSP_SESSION_ID |
| Pass a pointer to a char pointer to receive a pointer to a string holding the |
| most recent RTSP Session ID. |
| |
| Applications wishing to resume an RTSP session on another connection should |
| retreive this info before closing the active connection. |
| .IP CURLINFO_RTSP_CLIENT_CSEQ |
| Pass a pointer to a long to receive the next CSeq that will be used by the |
| application. |
| .IP CURLINFO_RTSP_SERVER_CSEQ |
| Pass a pointer to a long to receive the next server CSeq that will be expected |
| by the application. |
| |
| \fI(NOTE: listening for server initiated requests is currently |
| unimplemented).\fP |
| |
| Applications wishing to resume an RTSP session on another connection should |
| retreive this info before closing the active connection. |
| .IP CURLINFO_RTSP_CSEQ_RECV |
| Pass a pointer to a long to receive the most recently received CSeq from the |
| server. If your application encounters a \fICURLE_RTSP_CSEQ_ERROR\fP then you |
| may wish to troubleshoot and/or fix the CSeq mismatch by peeking at this value. |
| .SH TIMES |
| .nf |
| An overview of the six time values available from curl_easy_getinfo() |
| |
| curl_easy_perform() |
| | |
| |--NAMELOOKUP |
| |--|--CONNECT |
| |--|--|--APPCONNECT |
| |--|--|--|--PRETRANSFER |
| |--|--|--|--|--STARTTRANSFER |
| |--|--|--|--|--|--TOTAL |
| |--|--|--|--|--|--REDIRECT |
| .fi |
| .IP NAMELOOKUP |
| \fICURLINFO_NAMELOOKUP_TIME\fP. The time it took from the start until the name |
| resolving was completed. |
| .IP CONNECT |
| \fICURLINFO_CONNECT_TIME\fP. The time it took from the start until the connect |
| to the remote host (or proxy) was completed. |
| .IP APPCONNECT |
| \fICURLINFO_APPCONNECT_TIME\fP. The time it took from the start until the SSL |
| connect/handshake with the remote host was completed. (Added in in 7.19.0) |
| .IP PRETRANSFER |
| \fICURLINFO_PRETRANSFER_TIME\fP. The time it took from the start until the |
| file transfer is just about to begin. This includes all pre-transfer commands |
| and negotiations that are specific to the particular protocol(s) involved. |
| .IP STARTTRANSFER |
| \fICURLINFO_STARTTRANSFER_TIME\fP. The time it took from the start until the |
| first byte is received by libcurl. |
| .IP TOTAL |
| \fICURLINFO_TOTAL_TIME\fP. Total time of the previous request. |
| .IP REDIRECT |
| \fICURLINFO_REDIRECT_TIME\fP. The time it took for all redirection steps |
| include name lookup, connect, pretransfer and transfer before final |
| transaction was started. So, this is zero if no redirection took place. |
| .SH RETURN VALUE |
| If the operation was successful, CURLE_OK is returned. Otherwise an |
| appropriate error code will be returned. |
| .SH "SEE ALSO" |
| .BR curl_easy_setopt "(3)" |
