mirror/curl
2
0
Fork 0
mirror of https://github.com/curl/curl.git synced 2024-12-21 06:50:10 +08:00
Code Issues Packages Projects Releases Wiki Activity
85ce7f8070
curl/docs/libcurl/curl_easy_getinfo.3
Daniel Stenberg 5b060a4108
docs: rewrite to present tense 
... instead of using future tense.

+ numerous cleanups and improvements
+ stick to "reuse" not "re-use"
+ fewer contractions

Closes #11713
2023-08-23 23:26:10 +02:00

326 lines
12 KiB
Groff
Raw Blame History

.\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 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 https://curl.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.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH curl_easy_getinfo 3 "11 Feb 2009" "libcurl" "libcurl"
.SH NAME
curl_easy_getinfo - extract information from a curl handle
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *curl, CURLINFO info, ... );
.fi
.SH DESCRIPTION
Get the \fIinfo\fP kept in the \fIcurl\fP handle. The third argument
\fBMUST\fP be pointing to the specific type of the used option which is
documented in each man page of the \fIinfo\fP option. The data is stored
accordingly and can be relied upon only if this function returns CURLE_OK. Use
this function after a performed transfer if you want to get transfer related
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_METHOD
Last used HTTP method.
See \fICURLINFO_EFFECTIVE_METHOD(3)\fP
.IP CURLINFO_EFFECTIVE_URL
Last used URL.
See \fICURLINFO_EFFECTIVE_URL(3)\fP
.IP CURLINFO_RESPONSE_CODE
Last received response code.
See \fICURLINFO_RESPONSE_CODE(3)\fP
.IP CURLINFO_REFERER
Referrer header.
See \fICURLINFO_REFERER(3)\fP
.IP CURLINFO_HTTP_CONNECTCODE
Last proxy CONNECT response code.
See \fICURLINFO_HTTP_CONNECTCODE(3)\fP
.IP CURLINFO_HTTP_VERSION
The http version used in the connection.
See \fICURLINFO_HTTP_VERSION(3)\fP
.IP CURLINFO_FILETIME
Remote time of the retrieved document. See \fICURLINFO_FILETIME(3)\fP
.IP CURLINFO_FILETIME_T
Remote time of the retrieved document. See \fICURLINFO_FILETIME_T(3)\fP
.IP CURLINFO_TOTAL_TIME
Total time of previous transfer.
See \fICURLINFO_TOTAL_TIME(3)\fP
.IP CURLINFO_TOTAL_TIME_T
Total time of previous transfer.
See \fICURLINFO_TOTAL_TIME_T(3)\fP
.IP CURLINFO_NAMELOOKUP_TIME
Time from start until name resolving completed.
See \fICURLINFO_NAMELOOKUP_TIME(3)\fP
.IP CURLINFO_NAMELOOKUP_TIME_T
Time from start until name resolving completed.
See \fICURLINFO_NAMELOOKUP_TIME_T(3)\fP
.IP CURLINFO_CONNECT_TIME
Time from start until remote host or proxy completed.
See \fICURLINFO_CONNECT_TIME(3)\fP
.IP CURLINFO_CONNECT_TIME_T
Time from start until remote host or proxy completed.
See \fICURLINFO_CONNECT_TIME_T(3)\fP
.IP CURLINFO_APPCONNECT_TIME
Time from start until SSL/SSH handshake completed.
See \fICURLINFO_APPCONNECT_TIME(3)\fP
.IP CURLINFO_APPCONNECT_TIME_T
Time from start until SSL/SSH handshake completed.
See \fICURLINFO_APPCONNECT_TIME_T(3)\fP
.IP CURLINFO_PRETRANSFER_TIME
Time from start until just before the transfer begins.
See \fICURLINFO_PRETRANSFER_TIME(3)\fP
.IP CURLINFO_PRETRANSFER_TIME_T
Time from start until just before the transfer begins.
See \fICURLINFO_PRETRANSFER_TIME_T(3)\fP
.IP CURLINFO_STARTTRANSFER_TIME
Time from start until just when the first byte is received.
See \fICURLINFO_STARTTRANSFER_TIME(3)\fP
.IP CURLINFO_STARTTRANSFER_TIME_T
Time from start until just when the first byte is received.
See \fICURLINFO_STARTTRANSFER_TIME_T(3)\fP
.IP CURLINFO_REDIRECT_TIME
Time taken for all redirect steps before the final transfer.
See \fICURLINFO_REDIRECT_TIME(3)\fP
.IP CURLINFO_REDIRECT_TIME_T
Time taken for all redirect steps before the final transfer.
See \fICURLINFO_REDIRECT_TIME_T(3)\fP
.IP CURLINFO_REDIRECT_COUNT
Total number of redirects that were followed.
See \fICURLINFO_REDIRECT_COUNT(3)\fP
.IP CURLINFO_REDIRECT_URL
URL a redirect would take you to, had you enabled redirects.
See \fICURLINFO_REDIRECT_URL(3)\fP
.IP CURLINFO_SIZE_UPLOAD
(Deprecated) Number of bytes uploaded.
See \fICURLINFO_SIZE_UPLOAD(3)\fP
.IP CURLINFO_SIZE_UPLOAD_T
Number of bytes uploaded.
See \fICURLINFO_SIZE_UPLOAD_T(3)\fP
.IP CURLINFO_SIZE_DOWNLOAD
(Deprecated) Number of bytes downloaded.
See \fICURLINFO_SIZE_DOWNLOAD(3)\fP
.IP CURLINFO_SIZE_DOWNLOAD_T
Number of bytes downloaded.
See \fICURLINFO_SIZE_DOWNLOAD_T(3)\fP
.IP CURLINFO_SPEED_DOWNLOAD
(Deprecated) Average download speed.
See \fICURLINFO_SPEED_DOWNLOAD(3)\fP
.IP CURLINFO_SPEED_DOWNLOAD_T
Average download speed.
See \fICURLINFO_SPEED_DOWNLOAD_T(3)\fP
.IP CURLINFO_SPEED_UPLOAD
(Deprecated) Average upload speed.
See \fICURLINFO_SPEED_UPLOAD(3)\fP
.IP CURLINFO_SPEED_UPLOAD_T
Average upload speed.
See \fICURLINFO_SPEED_UPLOAD_T(3)\fP
.IP CURLINFO_HEADER_SIZE
Number of bytes of all headers received.
See \fICURLINFO_HEADER_SIZE(3)\fP
.IP CURLINFO_REQUEST_SIZE
Number of bytes sent in the issued HTTP requests.
See \fICURLINFO_REQUEST_SIZE(3)\fP
.IP CURLINFO_SSL_VERIFYRESULT
Certificate verification result.
See \fICURLINFO_SSL_VERIFYRESULT(3)\fP
.IP CURLINFO_PROXY_ERROR
Detailed proxy error.
See \fICURLINFO_PROXY_ERROR(3)\fP
.IP CURLINFO_PROXY_SSL_VERIFYRESULT
Proxy certificate verification result.
See \fICURLINFO_PROXY_SSL_VERIFYRESULT(3)\fP
.IP CURLINFO_SSL_ENGINES
A list of OpenSSL crypto engines.
See \fICURLINFO_SSL_ENGINES(3)\fP
.IP CURLINFO_CONTENT_LENGTH_DOWNLOAD
(Deprecated) Content length from the Content-Length header.
See \fICURLINFO_CONTENT_LENGTH_DOWNLOAD(3)\fP
.IP CURLINFO_CONTENT_LENGTH_DOWNLOAD_T
Content length from the Content-Length header.
See \fICURLINFO_CONTENT_LENGTH_DOWNLOAD_T(3)\fP
.IP CURLINFO_CONTENT_LENGTH_UPLOAD
(Deprecated) Upload size. See \fICURLINFO_CONTENT_LENGTH_UPLOAD(3)\fP
.IP CURLINFO_CONTENT_LENGTH_UPLOAD_T
Upload size. See \fICURLINFO_CONTENT_LENGTH_UPLOAD_T(3)\fP
.IP CURLINFO_CONTENT_TYPE
Content type from the Content-Type header.
See \fICURLINFO_CONTENT_TYPE(3)\fP
.IP CURLINFO_RETRY_AFTER
The value from the Retry-After header.
See \fICURLINFO_RETRY_AFTER(3)\fP
.IP CURLINFO_PRIVATE
User's private data pointer.
See \fICURLINFO_PRIVATE(3)\fP
.IP CURLINFO_HTTPAUTH_AVAIL
Available HTTP authentication methods.
See \fICURLINFO_HTTPAUTH_AVAIL(3)\fP
.IP CURLINFO_PROXYAUTH_AVAIL
Available HTTP proxy authentication methods.
See \fICURLINFO_PROXYAUTH_AVAIL(3)\fP
.IP CURLINFO_OS_ERRNO
The errno from the last failure to connect.
See \fICURLINFO_OS_ERRNO(3)\fP
.IP CURLINFO_NUM_CONNECTS
Number of new successful connections used for previous transfer.
See \fICURLINFO_NUM_CONNECTS(3)\fP
.IP CURLINFO_PRIMARY_IP
IP address of the last connection.
See \fICURLINFO_PRIMARY_IP(3)\fP
.IP CURLINFO_PRIMARY_PORT
Port of the last connection.
See \fICURLINFO_PRIMARY_PORT(3)\fP
.IP CURLINFO_LOCAL_IP
Local-end IP address of last connection.
See \fICURLINFO_LOCAL_IP(3)\fP
.IP CURLINFO_LOCAL_PORT
Local-end port of last connection.
See \fICURLINFO_LOCAL_PORT(3)\fP
.IP CURLINFO_COOKIELIST
List of all known cookies.
See \fICURLINFO_COOKIELIST(3)\fP
.IP CURLINFO_LASTSOCKET
(Deprecated) Last socket used.
See \fICURLINFO_LASTSOCKET(3)\fP
.IP CURLINFO_ACTIVESOCKET
The session's active socket.
See \fICURLINFO_ACTIVESOCKET(3)\fP
.IP CURLINFO_FTP_ENTRY_PATH
The entry path after logging in to an FTP server.
See \fICURLINFO_FTP_ENTRY_PATH(3)\fP
.IP CURLINFO_CAPATH
Get the default value for \fICURLOPT_CAPATH(3)\fP.
See \fICURLINFO_CAPATH(3)\fP
.IP CURLINFO_CAINFO
Get the default value for \fICURLOPT_CAINFO(3)\fP.
See \fICURLINFO_CAINFO(3)\fP
.IP CURLINFO_CERTINFO
Certificate chain.
See \fICURLINFO_CERTINFO(3)\fP
.IP CURLINFO_TLS_SSL_PTR
TLS session info that can be used for further processing.
See \fICURLINFO_TLS_SSL_PTR(3)\fP
.IP CURLINFO_TLS_SESSION
TLS session info that can be used for further processing. See
\fICURLINFO_TLS_SESSION(3)\fP. Deprecated option, use
\fICURLINFO_TLS_SSL_PTR(3)\fP instead!
.IP CURLINFO_CONDITION_UNMET
Whether or not a time conditional was met or 304 HTTP response.
See \fICURLINFO_CONDITION_UNMET(3)\fP
.IP CURLINFO_RTSP_SESSION_ID
RTSP session ID.
See \fICURLINFO_RTSP_SESSION_ID(3)\fP
.IP CURLINFO_RTSP_CLIENT_CSEQ
The RTSP client CSeq that is expected next.
See \fICURLINFO_RTSP_CLIENT_CSEQ(3)\fP
.IP CURLINFO_RTSP_SERVER_CSEQ
The RTSP server CSeq that is expected next.
See \fICURLINFO_RTSP_SERVER_CSEQ(3)\fP
.IP CURLINFO_RTSP_CSEQ_RECV
RTSP CSeq last received.
See \fICURLINFO_RTSP_CSEQ_RECV(3)\fP
.IP CURLINFO_PROTOCOL
(Deprecated) The protocol used for the connection. (Added in 7.52.0)
See \fICURLINFO_PROTOCOL(3)\fP
.IP CURLINFO_SCHEME
The scheme used for the connection. (Added in 7.52.0)
See \fICURLINFO_SCHEME(3)\fP
.IP CURLINFO_CONN_ID
The ID of the last connection used by the transfer. (Added in 8.2.0)
See \fICURLINFO_CONN_ID(3)\fP
.IP CURLINFO_XFER_ID
The ID of the transfer. (Added in 8.2.0)
See \fICURLINFO_XFER_ID(3)\fP
.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 and \fICURLINFO_NAMELOOKUP_TIME_T\fP.
The time it took from the start until the name resolving was completed.
.IP CONNECT
\fICURLINFO_CONNECT_TIME\fP and \fICURLINFO_CONNECT_TIME_T\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 and \fICURLINFO_APPCONNECT_TIME_T\fP.
The time it took from the start until the SSL
connect/handshake with the remote host was completed. (Added in 7.19.0)
The latter is the integer version (measuring microseconds). (Added in 7.60.0)
.IP PRETRANSFER
\fICURLINFO_PRETRANSFER_TIME\fP and \fICURLINFO_PRETRANSFER_TIME_T\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 and \fICURLINFO_STARTTRANSFER_TIME_T\fP.
The time it took from the start until the
first byte is received by libcurl.
.IP TOTAL
\fICURLINFO_TOTAL_TIME\fP and \fICURLINFO_TOTAL_TIME_T\fP.
Total time of the previous request.
.IP REDIRECT
\fICURLINFO_REDIRECT_TIME\fP and \fICURLINFO_REDIRECT_TIME_T\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 EXAMPLE
.nf
curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://www.example.com/");
res = curl_easy_perform(curl);
if(CURLE_OK == res) {
char *ct;
/* ask for the content-type */
res = curl_easy_getinfo(curl, CURLINFO_CONTENT_TYPE, &ct);
if((CURLE_OK == res) && ct)
printf("We received Content-Type: %s\\n", ct);
}
/* always cleanup */
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.4.1
.SH RETURN VALUE
If the operation was successful, CURLE_OK is returned. Otherwise an
appropriate error code is returned.
.SH "SEE ALSO"
.BR curl_easy_setopt "(3)"
Reference in New Issue View Git Blame Copy Permalink