curl_easy_getinfo.3 10 KB

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