mirror of
https://github.com/curl/curl.git
synced 2024-11-21 01:16:58 +08:00
328 lines
16 KiB
Groff
328 lines
16 KiB
Groff
.\" **************************************************************************
|
|
.\" * _ _ ____ _
|
|
.\" * Project ___| | | | _ \| |
|
|
.\" * / __| | | | |_) | |
|
|
.\" * | (__| |_| | _ <| |___
|
|
.\" * \___|\___/|_| \_\_____|
|
|
.\" *
|
|
.\" * Copyright (C) 1998 - 2015, 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
|
|
\fICURLOPT_FILETIME(3)\fP 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 pipelining 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 \fICURLOPT_FOLLOWLOCATION(3)\fP. 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. This counts actual payload data, what's also commonly
|
|
called body. All meta and header data are excluded and will not be counted in
|
|
this number.
|
|
.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 \fICURLOPT_SSL_VERIFYPEER(3)\fP
|
|
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 \fICURLOPT_PRIVATE(3)\fP 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
|
|
\fICURLOPT_HTTPAUTH(3)\fP 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
|
|
successful 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(3)\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 \fICURLOPT_CERTINFO(3)\fP 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, NSS or GSKit
|
|
support. (Added in 7.19.1)
|
|
.IP CURLINFO_TLS_SESSION
|
|
Pass a pointer to a 'struct curl_tlssessioninfo *'. The pointer will be
|
|
initialized to refer to a 'struct curl_tlssessioninfo *' that will contain an
|
|
enum indicating the SSL library used for the handshake and the respective
|
|
internal TLS session structure of this underlying SSL library.
|
|
|
|
This may then be used to extract certificate information in a format
|
|
convenient for further processing, such as manual validation. NOTE: this
|
|
option may not be available for all SSL backends; unsupported SSL backends
|
|
will return 'CURLSSLBACKEND_NONE' to indicate that they are not supported;
|
|
this does not mean that no SSL backend was used. (Added in 7.34.0)
|
|
|
|
.nf
|
|
struct curl_tlssessioninfo {
|
|
curl_sslbackend backend;
|
|
void *internals;
|
|
};
|
|
.fi
|
|
|
|
The \fIinternals\fP struct member will point to a TLS library specific pointer
|
|
with the following underlying types:
|
|
.RS
|
|
.IP OpenSSL
|
|
SSL_CTX *
|
|
.IP GnuTLS
|
|
gnutls_session_t
|
|
.IP NSS
|
|
PRFileDesc *
|
|
.IP gskit
|
|
gsk_handle
|
|
.RE
|
|
|
|
.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(3)\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
|
|
retrieve 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
|
|
retrieve 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)"
|