Expand/Shrink

curl_easy_getinfo

Definition: include builtins\libcurl.e

{CURLcode curlcode, object res} = curl_easy_getinfo(atom curl, integer option)
Description: Extract internal information from a curl session handle.
Use this function AFTER a performed transfer if you want to get transfer related data.

The one-liners below with "See CURLINFO_XXX" have not been tested, or properly documented here.
pwa/p2js: Not supported.
AVAILABLE INFORMATION The following information can be extracted:
CURLINFO_EFFECTIVE_URL Last used URL. See CURLINFO_EFFECTIVE_URL
CURLINFO_RESPONSE_CODE Get the last received response code.

Synopsis: {CURLcode curlcode, atom res} = curl_easy_getinfo(curl, CURLINFO_RESPONSE_CODE)

Retrieves 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 stored value will be zero if no server response code has been received.
Note that a proxy’s CONNECT response should be read with CURLINFO_HTTP_CONNECTCODE and not this.

Support for SMTP responses added in 7.25.0.

Protocols: HTTP, FTP and SMTP

Example:

atom curl = curl_easy_init()
curl_easy_setopt(curl, CURLOPT_URL, "http://example.com")
atom res = curl_easy_perform(curl)
if res=CURLE_OK then
    {CURLcode curlcode, atom response_code} = curl_easy_getinfo(curl, CURLINFO_RESPONSE_CODE)
    if curlcode!=CURLE_OK then
        ?{"error",curlcode,curl_easy_strerror(curlcode)}
    else
        ?{"response code",response_code}
    end if
end if
curl_easy_cleanup(curl)
Availability: Added in 7.10.8. CURLINFO_HTTP_CODE was added in 7.4.1.

Return value: Returns CURLE_UNKNOWN_OPTION (and NULL) if the option is not supported, otherwise CURLE_OK and a response code.

See also: curl_easy_setopt, CURLINFO_HTTP_CONNECTCODE
CURLINFO_HTTP_CONNECTCODE Last proxy CONNECT response code. See CURLINFO_HTTP_CONNECTCODE
CURLINFO_HTTP_VERSION The http version used in the connection. See CURLINFO_HTTP_VERSION
CURLINFO_FILETIME Remote time of the retrieved document. See CURLINFO_FILETIME
CURLINFO_TOTAL_TIME Total time of previous transfer. See CURLINFO_TOTAL_TIME
CURLINFO_NAMELOOKUP_TIME Time from start until name resolving completed. See CURLINFO_NAMELOOKUP_TIME
CURLINFO_CONNECT_TIME Time from start until remote host or proxy completed. See CURLINFO_CONNECT_TIME
CURLINFO_APPCONNECT_TIME Time from start until the SSL/SSH connect/handshake with the remote host was completed. See CURLINFO_APPCONNECT_TIME (Added in in 7.19.0)
CURLINFO_PRETRANSFER_TIME Time from start until the transfer begins.
This includes all pre-transfer commands and negotiations that are specific to the particular protocol(s) involved. See CURLINFO_PRETRANSFER_TIME
CURLINFO_STARTTRANSFER_TIME Time from start until the first byte is received. See CURLINFO_STARTTRANSFER_TIME
CURLINFO_REDIRECT_TIME The time it took for all redirection steps including name lookup, connect, pretransfer and transfer, before the final transfer. So, this is zero if no redirection took place. See CURLINFO_REDIRECT_TIME
CURLINFO_REDIRECT_COUNT Total number of redirects that were followed. See CURLINFO_REDIRECT_COUNT
CURLINFO_REDIRECT_URL Get the URL a redirect would go to, had you enabled redirects.

Synopsis: {CURLcode curlcode, object res} = curl_easy_getinfo(curl, CURLINFO_REDIRECT_URL)

Retrieve the URL a redirect would 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.

This URL is also set if the CURLOPT_MAXREDIRS limit prevented a redirect to happen (since 7.54.1).

Protocols: HTTP(S)

Example:

atom curl = curl_easy_init()
curl_easy_setopt(curl, CURLOPT_URL, "http://example.com")
CURLcode curlcode = curl_easy_perform(curl)
if curlcode=CURLE_OK then
    object url
    {curlcode,url} = curl_easy_getinfo(curl, CURLINFO_REDIRECT_URL)
    if curlcode=CURLE_OK then
      printf(1,"Redirect to: %s\n", {url})
    end if
end if
curl_easy_cleanup(curl)
Availability: Added in 7.18.2

Return value: Returns CURLE_UNKNOWN_OPTION (and "") if the option is not supported, otherwise CURLE_OK and a string.

See also: curl_easy_setopt
CURLINFO_SIZE_UPLOAD (Deprecated) Number of bytes uploaded. See CURLINFO_SIZE_UPLOAD
CURLINFO_SIZE_UPLOAD_T Number of bytes uploaded. See CURLINFO_SIZE_UPLOAD_T
CURLINFO_SIZE_DOWNLOAD (Deprecated) Number of bytes downloaded. See CURLINFO_SIZE_DOWNLOAD
CURLINFO_SIZE_DOWNLOAD_T Number of bytes downloaded. See CURLINFO_SIZE_DOWNLOAD_T
CURLINFO_SPEED_DOWNLOAD (Deprecated) Average download speed. See CURLINFO_SPEED_DOWNLOAD
CURLINFO_SPEED_DOWNLOAD_T Average download speed. See CURLINFO_SPEED_DOWNLOAD_T
CURLINFO_SPEED_UPLOAD (Deprecated) Average upload speed. See CURLINFO_SPEED_UPLOAD
CURLINFO_SPEED_UPLOAD_T Average upload speed. See CURLINFO_SPEED_UPLOAD_T
CURLINFO_HEADER_SIZE Number of bytes of all headers received. See CURLINFO_HEADER_SIZE
CURLINFO_REQUEST_SIZE Number of bytes sent in the issued HTTP requests. See CURLINFO_REQUEST_SIZE
CURLINFO_SSL_VERIFYRESULT Certificate verification result. See CURLINFO_SSL_VERIFYRESULT
CURLINFO_PROXY_SSL_VERIFYRESULT Proxy certificate verification result. See CURLINFO_PROXY_SSL_VERIFYRESULT
CURLINFO_SSL_ENGINES A list of OpenSSL crypto engines. See CURLINFO_SSL_ENGINES
CURLINFO_CONTENT_LENGTH_DOWNLOAD (Deprecated) Content length from the Content-Length header. See CURLINFO_CONTENT_LENGTH_DOWNLOAD
CURLINFO_CONTENT_LENGTH_DOWNLOAD_T Content length from the Content-Length header. See CURLINFO_CONTENT_LENGTH_DOWNLOAD_T
CURLINFO_CONTENT_LENGTH_UPLOAD (Deprecated) Upload size. See CURLINFO_CONTENT_LENGTH_UPLOAD
CURLINFO_CONTENT_LENGTH_UPLOAD_T Upload size. See CURLINFO_CONTENT_LENGTH_UPLOAD_T
CURLINFO_CONTENT_TYPE Get the Content-Type header.

Synopsis: {CURLcode curlcode, string res} = curl_easy_getinfo(curl, CURLINFO_CONTENT_TYPE)

This is the value read from the Content-Type: field.
If you get "", it means that the server didn’t send a valid Content-Type header or that the protocol used doesn’t support this.

Protocols: HTTP(S)

Example:

include builtins\libcurl.e
curl_global_init()
atom curl = curl_easy_init()
curl_easy_setopt(curl, CURLOPT_URL, "http://example.com")
CURLcode curlcode = curl_easy_perform(curl);
if curlcode!=CURLE_OK then
    ?"error"
else
    string res
    {curlcode,res} = curl_easy_getinfo(curl, CURLINFO_CONTENT_TYPE)
    if curlcode!=CURLE_OK then
        ?{"error",curlcode,curl_easy_strerror(curlcode)}
    else
        printf(1, "We received Content-Type: %s\n", {res})
    end if
end if
curl_easy_cleanup(curl)
curl_global_cleanup()
Availability: Added in 7.9.4

Return value: returns CURLE_UNKNOWN_OPTION (and "") if the option is not supported, otherwise CURLE_OK and a string.

See also: curl_easy_setopt
CURLINFO_PRIVATE User’s private data pointer. NB: the pre-built windows binaries (dll files) shipped with Phix appear to have been built without support for this, but strangely with support for curl_easy_setopt(curl,CURLINFO_PRIVATE).

Synopsis: {CURLcode curlcode, atom res} = curl_easy_getinfo(curl, CURLINFO_PRIVATE)

Retrieves the pointer to the private data associated with the curl handle (set with the CURLOPT_PRIVATE).

Protocols: All

Example:

atom curl = curl_easy_init()
curl_easy_setopt(curl, CURLOPT_URL, "http://example.com/foo.bin")
atom pointer = 0x2345454

/* set the private pointer */
curl_easy_setopt(curl, CURLOPT_PRIVATE, pointer)
atom ret = curl_easy_perform(curl)
 
/* extract the private pointer again */
{ret,pointer} = curl_easy_getinfo(curl, CURLINFO_PRIVATE)
 
curl_easy_cleanup(curl)
Availability: Added in 7.10.3

Return value: Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.

See also: curl_easy_setopt, CURLOPT_PRIVATE
CURLINFO_HTTPAUTH_AVAIL Available HTTP authentication methods. See CURLINFO_HTTPAUTH_AVAIL
CURLINFO_PROXYAUTH_AVAIL Available HTTP proxy authentication methods. See CURLINFO_PROXYAUTH_AVAIL
CURLINFO_OS_ERRNO The errno from the last failure to connect. See CURLINFO_OS_ERRNO
CURLINFO_NUM_CONNECTS Number of new successful connections used for previous transfer. See CURLINFO_NUM_CONNECTS
CURLINFO_PRIMARY_IP IP address of the last connection. See CURLINFO_PRIMARY_IP
CURLINFO_PRIMARY_PORT Port of the last connection. See CURLINFO_PRIMARY_PORT
CURLINFO_LOCAL_IP Local-end IP address of last connection. See CURLINFO_LOCAL_IP
CURLINFO_LOCAL_PORT Local-end port of last connection. See CURLINFO_LOCAL_PORT
CURLINFO_COOKIELIST Get a list of all known cookies.

Synopsis: {CURLcode curlcode, object res} = curl_easy_getinfo(curl, CURLINFO_COOKIELIST)

Returns a list of all cookies curl knows (expired ones, too).
If there are no cookies (cookies for the handle have not been enabled or simply none have been received) then {} is returned.

Since 7.43.0 cookies that were imported in the Set-Cookie format without a domain name are not exported by this option.

Protocols: HTTP(S)

Example:

include builtins\libcurl.e
curl_global_init()
atom curl = curl_easy_init()
curl_easy_setopt(curl, CURLOPT_URL, "http://example.com")
-- enable the cookie engine with a non-existing file:
curl_easy_setopt(curl, CURLOPT_COOKIEFILE, "-")
CURLcode curlcode = curl_easy_perform(curl)
if curlcode!=CURLE_OK then
    ?"error"
else
    /* extract all known cookies */
    object cookies
    {curlcode,cookies} = curl_easy_getinfo(curl, CURLINFO_COOKIELIST)
    if curlcode!=CURLE_OK then
        ?{"error",curlcode,curl_easy_strerror(curlcode)}
    else
        ?cookies
    end if
end if
curl_easy_cleanup(curl)
curl_global_cleanup()
See CURLOPT_COOKIELIST for the individual cookie format

Availability: Added in 7.14.1

Return value: Returns CURLE_UNKNOWN_OPTION (and NULL) if the option is not supported, otherwise CURLE_OK and a sequence of cookies (as strings).

See also: curl_easy_setopt, CURLOPT_COOKIELIST
CURLINFO_LASTSOCKET Get the last socket used.

Synopsis: {CURLcode curlcode, atom socket} = curl_easy_getinfo(curl, CURLINFO_LASTSOCKET)

Deprecated since 7.45.0. Use CURLINFO_ACTIVESOCKET instead.

Retrieve 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 CURLOPT_CONNECT_ONLY.

NOTE: this API is deprecated since it is not working on win64 where the SOCKET type is 64 bits large while its 'long' is 32 bits.
Use the CURLINFO_ACTIVESOCKET instead, if possible.

Protocols: All

Example

include builtins\libcurl.e
curl_global_init()
atom curl = curl_easy_init()
curl_easy_setopt(curl, CURLOPT_URL, "http://example.com")
-- Do not do the transfer - only connect to host
curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, true)
CURLcode curlcode = curl_easy_perform(curl)
if curlcode!=CURLE_OK then
    ?"error"
else
    -- Extract the socket from the curl handle
    atom socket
    {curlcode,socket} = curl_easy_getinfo(curl, CURLINFO_LASTSOCKET)
    if curlcode!=CURLE_OK then
        ?{"error",curlcode,curle_easy_strerror(curlcode)}
    else
        ?{"socket",socket}
    end if
end if
curl_easy_cleanup(curl)
curl_global_cleanup()
Availability: Added in 7.15.2

Return value: Returns CURLE_UNKNOWN_OPTION (and NULL) if the option is not supported, otherwise CURLE_OK and a socket.

See also: curl_easy_getinfo, curl_easy_setopt, CURLINFO_ACTIVESOCKET
CURLINFO_ACTIVESOCKET Get the session’s active socket.

Synopsis: {CURLcode curlcode, atom socket} = curl_easy_getinfo(curl, CURLINFO_ACTIVESOCKET)

Retrieve the active socket used by this curl session.
If the socket is no longer valid, CURL_SOCKET_BAD is returned.
When you finish working with the socket, you must call curl_easy_cleanup as usual on the easy handle and let libcurl close the socket and cleanup other resources associated with the handle.
This is typically used in combination with CURLOPT_CONNECT_ONLY.

This option was added as a replacement for CURLINFO_LASTSOCKET since that one is not working on all platforms.

Protocols: All

Example

include builtins\libcurl.e
curl_global_init()
atom curl = curl_easy_init()
curl_easy_setopt(curl, CURLOPT_URL, "http://example.com")
-- Do not do the transfer - only connect to host
curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, true)
CURLcode curlcode = curl_easy_perform(curl)
if curlcode!=CURLE_OK then
    ?"error"
else
    -- Extract the socket from the curl handle
    atom socket
    {curlcode,socket} = curl_easy_getinfo(curl, CURLINFO_ACTIVESOCKET)
    if curlcode!=CURLE_OK then
        ?{"error",curlcode,curl_easy_strerror(curlcode)}
    else
        ?{"socket",socket}
    end if
end if
curl_easy_cleanup(curl)
curl_global_cleanup()
Availability: Added in 7.45.0

Return value: Returns CURLE_UNKNOWN_OPTION (and NULL) if the option is not supported, otherwise CURLE_OK and a socket.

See also: curl_easy_setopt, CURLINFO_LASTSOCKET
CURLINFO_FTP_ENTRY_PATH The entry path after logging in to an FTP server. See CURLINFO_FTP_ENTRY_PATH
CURLINFO_CERTINFO Get the TLS certificate chain.

Protocols: All TLS-based

Availability: This option is only working in libcurl built with OpenSSL, NSS, schannel or GSKit support. schannel support added in 7.50.0 Added in 7.19.1

Return value: Returns CURLE_UNKNOWN_OPTION (and NULL) if the option is not supported, otherwise CURLE_OK and a nested sequence, one for each certificate in the chain, with each subsequence being strings describing that certificate.

See also: curl_easy_setopt
CURLINFO_TLS_SSL_PTR TLS session info that can be used for further processing. See CURLINFO_TLS_SSL_PTR
CURLINFO_TLS_SESSION TLS session info that can be used for further processing. See CURLINFO_TLS_SESSION. Deprecated option, use CURLINFO_TLS_SSL_PTR instead!
CURLINFO_CONDITION_UNMET Whether or not a time conditional was met. See CURLINFO_CONDITION_UNMET
CURLINFO_RTSP_SESSION_ID RTSP session ID. See CURLINFO_RTSP_SESSION_ID
CURLINFO_RTSP_CLIENT_CSEQ RTSP CSeq that will next be used. See CURLINFO_RTSP_CLIENT_CSEQ
CURLINFO_RTSP_SERVER_CSEQ RTSP CSeq that will next be expected. See CURLINFO_RTSP_SERVER_CSEQ
CURLINFO_RTSP_CSEQ_RECV RTSP CSeq last received. See CURLINFO_RTSP_CSEQ_RECV
CURLINFO_PROTOCOL The protocol used for the connection. (Added in 7.52.0) See CURLINFO_PROTOCOL
CURLINFO_SCHEME The scheme used for the connection. (Added in 7.52.0) See CURLINFO_SCHEME
TIMES An overview of the six time values available from curl_easy_getinfo()

curl_easy_perform()
    |
    |--NAMELOOKUP - until the name resolving was completed
    |--|--CONNECT - until connect to remote host (or proxy) was completed
    |--|--|--APPCONNECT - until SSL connect/handshake with remote host completed
    |--|--|--|--PRETRANSFER - until the file transfer is just about to begin
    |--|--|--|--|--STARTTRANSFER - until the first byte is received by libcurl
    |--|--|--|--|--|--TOTAL - total time of the previous request
    |--|--|--|--|--|--REDIRECT - for all redirection steps before final transaction started
See Also: curl_easy_setopt