docs/libcurl/curl_easy_getinfo.3

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