docs/libcurl/curl_easy_getinfo.3

   1 .\" **************************************************************************
   2 .\" *                                  _   _ ____  _
   3 .\" *  Project                     ___| | | |  _ \| |
   4 .\" *                             / __| | | | |_) | |
   5 .\" *                            | (__| |_| |  _ <| |___
   6 .\" *                             \___|\___/|_| \_\_____|
   7 .\" *
   8 .\" * Copyright (C) 1998 - 2016, Daniel Stenberg, <daniel@haxx.se>, et al.
   9 .\" *
  10 .\" * This software is licensed as described in the file COPYING, which
  11 .\" * you should have received as part of this distribution. The terms
  12 .\" * are also available at https://curl.haxx.se/docs/copyright.html.
  13 .\" *
  14 .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
  15 .\" * copies of the Software, and permit persons to whom the Software is
  16 .\" * furnished to do so, under the terms of the COPYING file.
  17 .\" *
  18 .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
  19 .\" * KIND, either express or implied.
  20 .\" *
  21 .\" **************************************************************************
  22 .\"
  23 .TH curl_easy_getinfo 3 "11 Feb 2009" "libcurl 7.19.4" "libcurl Manual"
  24 .SH NAME
  25 curl_easy_getinfo - extract information from a curl handle
  26 .SH SYNOPSIS
  27 .B #include <curl/curl.h>
  28
  29 .B "CURLcode curl_easy_getinfo(CURL *curl, CURLINFO info, ... );"
  30
  31 .SH DESCRIPTION
  32 Request internal information from the curl session with this function.  The
  33 third argument \fBMUST\fP be a pointer to a long, a pointer to a char *, a
  34 pointer to a struct curl_slist * or a pointer to a double (as this
  35 documentation describes further down).  The data pointed-to will be filled in
  36 accordingly and can be relied upon only if the function returns CURLE_OK.  Use
  37 this function AFTER a performed transfer if you want to get transfer related
  38 data.
  39
  40 You should not free the memory returned by this function unless it is
  41 explicitly mentioned below.
  42 .SH AVAILABLE INFORMATION
  43 The following information can be extracted:
  44 .IP CURLINFO_EFFECTIVE_URL
  45 Last used URL.
  46 See \fICURLINFO_EFFECTIVE_URL(3)\fP
  47 .IP CURLINFO_RESPONSE_CODE
  48 Last received response code.
  49 See \fICURLINFO_RESPONSE_CODE(3)\fP
  50 .IP CURLINFO_HTTP_CONNECTCODE
  51 Last proxy CONNECT response code.
  52 See \fICURLINFO_HTTP_CONNECTCODE(3)\fP
  53 .IP CURLINFO_HTTP_VERSION
  54 The http version used in the connection.
  55 See \fICURLINFO_HTTP_VERSION(3)\fP
  56 .IP CURLINFO_FILETIME
  57 Remote time of the retrieved document.
  58 See \fICURLINFO_FILETIME(3)\fP
  59 .IP CURLINFO_TOTAL_TIME
  60 Total time of previous transfer.
  61 See \fICURLINFO_TOTAL_TIME(3)\fP
  62 .IP CURLINFO_NAMELOOKUP_TIME
  63 Time from start until name resolving completed.
  64 See \fICURLINFO_NAMELOOKUP_TIME(3)\fP
  65 .IP CURLINFO_CONNECT_TIME
  66 Time from start until remote host or proxy completed.
  67 See \fICURLINFO_CONNECT_TIME(3)\fP
  68 .IP CURLINFO_APPCONNECT_TIME
  69 Time from start until SSL/SSH handshake completed.
  70 See \fICURLINFO_APPCONNECT_TIME(3)\fP
  71 .IP CURLINFO_PRETRANSFER_TIME
  72 Time from start until just before the transfer begins.
  73 See \fICURLINFO_PRETRANSFER_TIME(3)\fP
  74 .IP CURLINFO_STARTTRANSFER_TIME
  75 Time from start until just when the first byte is received.
  76 See \fICURLINFO_STARTTRANSFER_TIME(3)\fP
  77 .IP CURLINFO_REDIRECT_TIME
  78 Time taken for all redirect steps before the final transfer.
  79 See \fICURLINFO_REDIRECT_TIME(3)\fP
  80 .IP CURLINFO_REDIRECT_COUNT
  81 Total number of redirects that were followed.
  82 See \fICURLINFO_REDIRECT_COUNT(3)\fP
  83 .IP CURLINFO_REDIRECT_URL
  84 URL a redirect would take you to, had you enabled redirects.
  85 See \fICURLINFO_REDIRECT_URL(3)\fP
  86 .IP CURLINFO_SIZE_UPLOAD
  87 Number of bytes uploaded.
  88 See \fICURLINFO_SIZE_UPLOAD(3)\fP
  89 .IP CURLINFO_SIZE_DOWNLOAD
  90 Number of bytes downloaded.
  91 See \fICURLINFO_SIZE_DOWNLOAD(3)\fP
  92 .IP CURLINFO_SPEED_DOWNLOAD
  93 Average download speed.
  94 See \fICURLINFO_SPEED_DOWNLOAD(3)\fP
  95 .IP CURLINFO_SPEED_UPLOAD
  96 Average upload speed.
  97 See \fICURLINFO_SPEED_UPLOAD(3)\fP
  98 .IP CURLINFO_HEADER_SIZE
  99 Number of bytes of all headers received.
 100 See \fICURLINFO_HEADER_SIZE(3)\fP
 101 .IP CURLINFO_REQUEST_SIZE
 102 Number of bytes sent in the issued HTTP requests.
 103 See \fICURLINFO_REQUEST_SIZE(3)\fP
 104 .IP CURLINFO_SSL_VERIFYRESULT
 105 Certificate verification result.
 106 See \fICURLINFO_SSL_VERIFYRESULT(3)\fP
 107 .IP CURLINFO_PROXY_SSL_VERIFYRESULT
 108 Proxy certificate verification result.
 109 See \fICURLINFO_PROXY_SSL_VERIFYRESULT(3)\fP
 110 .IP CURLINFO_SSL_ENGINES
 111 A list of OpenSSL crypto engines.
 112 See \fICURLINFO_SSL_ENGINES(3)\fP
 113 .IP CURLINFO_CONTENT_LENGTH_DOWNLOAD
 114 Content length from the Content-Length header.
 115 See \fICURLINFO_CONTENT_LENGTH_DOWNLOAD(3)\fP
 116 .IP CURLINFO_CONTENT_LENGTH_UPLOAD
 117 Upload size.
 118 See \fICURLINFO_CONTENT_LENGTH_UPLOAD(3)\fP
 119 .IP CURLINFO_CONTENT_TYPE
 120 Content type from the Content-Type header.
 121 See \fICURLINFO_CONTENT_TYPE(3)\fP
 122 .IP CURLINFO_PRIVATE
 123 User's private data pointer.
 124 See \fICURLINFO_PRIVATE(3)\fP
 125 .IP CURLINFO_HTTPAUTH_AVAIL
 126 Available HTTP authentication methods.
 127 See \fICURLINFO_HTTPAUTH_AVAIL(3)\fP
 128 .IP CURLINFO_PROXYAUTH_AVAIL
 129 Available HTTP proxy authentication methods.
 130 See \fICURLINFO_PROXYAUTH_AVAIL(3)\fP
 131 .IP CURLINFO_OS_ERRNO
 132 The errno from the last failure to connect.
 133 See \fICURLINFO_OS_ERRNO(3)\fP
 134 .IP CURLINFO_NUM_CONNECTS
 135 Number of new successful connections used for previous transfer.
 136 See \fICURLINFO_NUM_CONNECTS(3)\fP
 137 .IP CURLINFO_PRIMARY_IP
 138 IP address of the last connection.
 139 See \fICURLINFO_PRIMARY_IP(3)\fP
 140 .IP CURLINFO_PRIMARY_PORT
 141 Port of the last connection.
 142 See \fICURLINFO_PRIMARY_PORT(3)\fP
 143 .IP CURLINFO_LOCAL_IP
 144 Local-end IP address of last connection.
 145 See \fICURLINFO_LOCAL_IP(3)\fP
 146 .IP CURLINFO_LOCAL_PORT
 147 Local-end port of last connection.
 148 See \fICURLINFO_LOCAL_PORT(3)\fP
 149 .IP CURLINFO_COOKIELIST
 150 List of all known cookies.
 151 See \fICURLINFO_COOKIELIST(3)\fP
 152 .IP CURLINFO_LASTSOCKET
 153 Last socket used.
 154 See \fICURLINFO_LASTSOCKET(3)\fP
 155 .IP CURLINFO_ACTIVESOCKET
 156 The session's active socket.
 157 See \fICURLINFO_ACTIVESOCKET(3)\fP
 158 .IP CURLINFO_FTP_ENTRY_PATH
 159 The entry path after logging in to an FTP server.
 160 See \fICURLINFO_FTP_ENTRY_PATH(3)\fP
 161 .IP CURLINFO_CERTINFO
 162 Certificate chain.
 163 See \fICURLINFO_CERTINFO(3)\fP
 164 .IP CURLINFO_TLS_SSL_PTR
 165 TLS session info that can be used for further processing.
 166 See \fICURLINFO_TLS_SSL_PTR(3)\fP
 167 .IP CURLINFO_TLS_SESSION
 168 TLS session info that can be used for further processing.  See
 169 \fICURLINFO_TLS_SESSION(3)\fP. Deprecated option, use
 170 \fICURLINFO_TLS_SSL_PTR(3)\fP instead!
 171 .IP CURLINFO_CONDITION_UNMET
 172 Whether or not a time conditional was met.
 173 See \fICURLINFO_CONDITION_UNMET(3)\fP
 174 .IP CURLINFO_RTSP_SESSION_ID
 175 RTSP session ID.
 176 See \fICURLINFO_RTSP_SESSION_ID(3)\fP
 177 .IP CURLINFO_RTSP_CLIENT_CSEQ
 178 RTSP CSeq that will next be used.
 179 See \fICURLINFO_RTSP_CLIENT_CSEQ(3)\fP
 180 .IP CURLINFO_RTSP_SERVER_CSEQ
 181 RTSP CSeq that will next be expected.
 182 See \fICURLINFO_RTSP_SERVER_CSEQ(3)\fP
 183 .IP CURLINFO_RTSP_CSEQ_RECV
 184 RTSP CSeq last received.
 185 See \fICURLINFO_RTSP_CSEQ_RECV(3)\fP
 186 .IP CURLINFO_PROTOCOL
 187 The protocol used for the connection. (Added in 7.52.0)
 188 See \fICURLINFO_PROTOCOL(3)\fP
 189 .IP CURLINFO_SCHEME
 190 The scheme used for the connection. (Added in 7.52.0)
 191 See \fICURLINFO_SCHEME(3)\fP
 192 .SH TIMES
 193 .nf
 194 An overview of the six time values available from curl_easy_getinfo()
 195
 196 curl_easy_perform()
 197     |
 198     |--NAMELOOKUP
 199     |--|--CONNECT
 200     |--|--|--APPCONNECT
 201     |--|--|--|--PRETRANSFER
 202     |--|--|--|--|--STARTTRANSFER
 203     |--|--|--|--|--|--TOTAL
 204     |--|--|--|--|--|--REDIRECT
 205 .fi
 206 .IP NAMELOOKUP
 207 \fICURLINFO_NAMELOOKUP_TIME\fP. The time it took from the start until the name
 208 resolving was completed.
 209 .IP CONNECT
 210 \fICURLINFO_CONNECT_TIME\fP. The time it took from the start until the connect
 211 to the remote host (or proxy) was completed.
 212 .IP APPCONNECT
 213 \fICURLINFO_APPCONNECT_TIME\fP. The time it took from the start until the SSL
 214 connect/handshake with the remote host was completed. (Added in in 7.19.0)
 215 .IP PRETRANSFER
 216 \fICURLINFO_PRETRANSFER_TIME\fP. The time it took from the start until the
 217 file transfer is just about to begin. This includes all pre-transfer commands
 218 and negotiations that are specific to the particular protocol(s) involved.
 219 .IP STARTTRANSFER
 220 \fICURLINFO_STARTTRANSFER_TIME\fP. The time it took from the start until the
 221 first byte is received by libcurl.
 222 .IP TOTAL
 223 \fICURLINFO_TOTAL_TIME\fP. Total time of the previous request.
 224 .IP REDIRECT
 225 \fICURLINFO_REDIRECT_TIME\fP. The time it took for all redirection steps
 226 include name lookup, connect, pretransfer and transfer before final
 227 transaction was started. So, this is zero if no redirection took place.
 228 .SH RETURN VALUE
 229 If the operation was successful, CURLE_OK is returned. Otherwise an
 230 appropriate error code will be returned.
 231 .SH "SEE ALSO"
 232 .BR curl_easy_setopt "(3)"