libcurl Manual curleasygetinfo(3)
NAME
curleasygetinfo - extract information from a curl handle
SYNOPSIS
#include
CURLcode curleasygetinfo(CURL *curl, CURLINFO info, ... );
DESCRIPTION
Request internal information from the curl session with this
function. The third argument MUST be a pointer to a long, a
pointer to a char *, a pointer to a struct curlslist * 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
CURLEOK. 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.
AVAILABLE INFORMATION
The following information can be extracted:
CURLINFOEFECTIVEURL
Pass a pointer to a 'char *' to receive the last used
effective URL.
CURLINFORESPONSECODE
Pass a pointer to a long to receive the last received
HTP or FTP code. This option was known as
CURLINFOHTPCODE in libcurl 7.10.7 and earlier. This
will be zero if no server response code has been
received. Note that a proxy's CONECT response should
be read with CURLINFOHTPCONECTCODE and not this.
CURLINFOHTPCONECTCODE
Pass a pointer to a long to receive the last received
proxy response code to a CONECT request.
CURLINFOFILETIME
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 col-
lect this information before the transfer is made, by
using the CURLOPTFILETIME option to
curleasysetopt(3) or you will unconditionally get a
libcurl 7.19.4 Last change: 11 Feb 2009 1
libcurl Manual curleasygetinfo(3)
-1 back. (Added in 7.5)
CURLINFOTOTALTIME
Pass a pointer to a double to receive the total time in
seconds for the previous transfer, including name
resolving, TCP connect etc.
CURLINFONAMELOKUPTIME
Pass a pointer to a double to receive the time, in
seconds, it took from the start until the name resolv-
ing was completed.
CURLINFOCONECTIME
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.
CURLINFOAPCONECTIME
Pass a pointer to a double to receive the time, in
seconds, it took from the start until the SL/SH
connect/handshake to the remote host was completed.
This time is most often very near to the PRETRANSFER
time, except for cases such as HTP pippelining where
the pretransfer time can be delayed due to waits in
line for the pipeline and more. (Added in 7.19.0)
CURLINFOPRETRANSFERTIME
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 par-
ticular protocol(s) involved.
CURLINFOSTARTRANSFERTIME
Pass a pointer to a double to receive the time, in
seconds, it took from the start until the first byte is
just about to be transferred. This includes
CURLINFOPRETRANSFERTIME and also the time the server
needs to calculate the result.
CURLINFOREDIRECTIME
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. CURLINFOREDIRECTIME
contains the complete execution time for multiple
redirections. (Added in 7.9.7)
CURLINFOREDIRECTCOUNT
Pass a pointer to a long to receive the total number of
redirections that were actually followed. (Added in
7.9.7)
libcurl 7.19.4 Last change: 11 Feb 2009 2
libcurl Manual curleasygetinfo(3)
CURLINFOREDIRECTURL
Pass a pointer to a char pointer to receive the URL a
redirect would take you to if you would enable
CURLOPTFOLOWLOCATION. 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)
CURLINFOSIZEUPLOAD
Pass a pointer to a double to receive the total amount
of bytes that were uploaded.
CURLINFOSIZEDOWNLOAD
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.
CURLINFOSPEDOWNLOAD
Pass a pointer to a double to receive the average down-
load speed that curl measured for the complete down-
load. Measured in bytes/second.
CURLINFOSPEDUPLOAD
Pass a pointer to a double to receive the average
upload speed that curl measured for the complete
upload. Measured in bytes/second.
CURLINFOHEADERSIZE
Pass a pointer to a long to receive the total size of
all the headers received. Measured in number of bytes.
CURLINFOREQUESTSIZE
Pass a pointer to a long to receive the total size of
the issued requests. This is so far only for HTP
requests. Note that this may be more than one request
if FOLOWLOCATION is true.
CURLINFOSLVERIFYRESULT
Pass a pointer to a long to receive the result of the
certification verification that was requested (using
the CURLOPTSLVERIFYPER option to
curleasysetopt(3)).
CURLINFOSLENGINES
Pass the address of a 'struct curlslist *' to receive
a linked-list of OpenSL 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. NOTE: you must call
curlslistfreeall(3) on the list pointer once you're
libcurl 7.19.4 Last change: 11 Feb 2009 3
libcurl Manual curleasygetinfo(3)
done with it, as libcurl will not free the data for
you. (Added in 7.12.3)
CURLINFOCONTENTLENGTHDOWNLOAD
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.
CURLINFOCONTENTLENGTHUPLOAD
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.
CURLINFOCONTENTYPE
Pass a pointer to a 'char *' to receive the content-
type of the downloaded object. This is the value read
from the Content-Type: field. If you get NUL, it means
that the server didn't send a valid Content-Type header
or that the protocol used doesn't support this.
CURLINFOPRIVATE
Pass a pointer to a 'char *' to receive the pointer to
the private data associated with the curl handle (set
with the CURLOPTPRIVATE option to
curleasysetopt(3)). Please note that for internal
reasons, the value is returned as a 'char *', although
effectively being a 'void *'. (Added in 7.10.3)
CURLINFOHTPAUTHAVAIL
Pass a pointer to a long to receive a bitmask indicat-
ing the authentication method(s) available. The meaning
of the bits is explained in the CURLOPTHTPAUTH option
for curleasysetopt(3). (Added in 7.10.8)
CURLINFOPROXYAUTHAVAIL
Pass a pointer to a long to receive a bitmask indicat-
ing the authentication method(s) available for your
proxy authentication. (Added in 7.10.8)
CURLINFOSERNO
Pass a pointer to a long to receive the errno variable
from a connect failure. (Added in 7.12.2)
CURLINFONUMCONECTS
Pass a pointer to a long to receive how many new con-
nections libcurl had to create to achieve the previous
transfer (only the successful connects are counted).
Combined with CURLINFOREDIRECTCOUNT you are able to
know how many times libcurl successfully reused exist-
ing connection(s) or not. See the Connection Options
of curleasysetopt(3) to see how libcurl tries to make
libcurl 7.19.4 Last change: 11 Feb 2009 4
libcurl Manual curleasygetinfo(3)
persistent connections to save time. (Added in 7.12.3)
CURLINFOPRIMARYIP
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 curl 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)
CURLINFOCOKIELIST
Pass a pointer to a 'struct curlslist *' to receive a
linked-list of all cookies cURL knows (expired ones,
too). Don't forget to curlslistfreeall(3) the list
after it has been used. If there are no cookies (cook-
ies for the handle have not been enabled or simply none
have been received) 'struct curlslist *' will be set
to point to NUL. (Added in 7.14.1)
CURLINFOLASTSOCKET
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 curleasycleanup() as usual and
let libcurl close the socket and cleanup other
resources associated with the handle. This is typically
used in combination with CURLOPTCONECTONLY. (Added
in 7.15.2)
CURLINFOFTPENTRYPATH
Pass a pointer to a 'char *' 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 NUL as pointer if
something is wrong. (Added in 7.15.4)
CURLINFOCERTINFO
Pass a pointer to a 'struct curlcertinfo *' 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 CURLOPTCERTINFO enabled when the pre-
vious 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 OpenSL
support. (Added in 7.19.1)
CURLINFOCONDITIONUNMET
libcurl 7.19.4 Last change: 11 Feb 2009 5
libcurl Manual curleasygetinfo(3)
Pass a pointer to a long to receive the number 1 if the
condition provided in the previous request didn't match
(see CURLOPTIMECONDITION). 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)
TIMES
An overview of the six time values available from
curleasygetinfo()
curleasyperform()
--NAMELOKUP
----CONECT
------APCONECT
--------PRETRANSFER
----------STARTRANSFER
------------TOTAL
------------REDIRECT
NAMELOKUP
CURLINFONAMELOKUPTIME. The time it took from the
start until the name resolving was completed.
CONECT
CURLINFOCONECTIME. The time it took from the start
until the connect to the remote host (or proxy) was
completed.
APCONECT
CURLINFOAPCONECTIME. The time it took from the
start until the SL connect/handshake with the remote
host was completed. (Added in in 7.19.0)
PRETRANSFER
CURLINFOPRETRANSFERTIME. The time it took from the
start until the file transfer is just about to begin.
This includes all pre-transfer commands and negotia-
tions that are specific to the particular protocol(s)
involved.
STARTRANSFER
CURLINFOSTARTRANSFERTIME. The time it took from the
start until the first byte is just about to be
transferred.
TOTAL
CURLINFOTOTALTIME. Total time of the previous
request.
libcurl 7.19.4 Last change: 11 Feb 2009 6
libcurl Manual curleasygetinfo(3)
REDIRECT
CURLINFOREDIRECTIME. The time it took for all
redirection steps include name lookup, connect, pre-
transfer and transfer before final transaction was
started. So, this is zero if no redirection took place.
RETURN VALUE
If the operation was successful, CURLEOK is returned. Oth-
erwise an appropriate error code will be returned.
SEE ALSO
curleasysetopt(3)
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWcurl
Interface Stability Uncommitted
NOTES
Source for C-URL is available on http:/opensolaris.org.
libcurl 7.19.4 Last change: 11 Feb 2009 7
|
