docs/libcurl/curl_easy_getinfo.3

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