curl_easy_header.3 6.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153
  1. .\" **************************************************************************
  2. .\" * _ _ ____ _
  3. .\" * Project ___| | | | _ \| |
  4. .\" * / __| | | | |_) | |
  5. .\" * | (__| |_| | _ <| |___
  6. .\" * \___|\___/|_| \_\_____|
  7. .\" *
  8. .\" * Copyright (C) 1998 - 2022, 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.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. .\" * SPDX-License-Identifier: curl
  22. .\" *
  23. .\" **************************************************************************
  24. .TH curl_easy_header 3 "13 March 2022" "libcurl 7.83.0" "libcurl Manual"
  25. .SH NAME
  26. curl_easy_header - get an HTTP header
  27. .SH SYNOPSIS
  28. .nf
  29. #include <curl/curl.h>
  30. CURLHcode curl_easy_header(CURL *easy,
  31. const char *name,
  32. size_t index,
  33. unsigned int origin,
  34. int request,
  35. struct curl_header **hout);
  36. .SH DESCRIPTION
  37. \fIcurl_easy_header(3)\fP returns a pointer to a "curl_header" struct in
  38. \fBhout\fP with data for the HTTP response header \fIname\fP. The case
  39. insensitive null-terminated header name should be specified without colon.
  40. \fIindex\fP 0 means asking for the first instance of the header. If the
  41. returned header struct has \fBamount\fP set larger than 1, it means there are
  42. more instances of the same header name available to get. Asking for a too big
  43. index makes \fBCURLHE_BADINDEX\fP get returned.
  44. The \fIorigin\fP argument is for specifying which headers to receive, as a
  45. single HTTP transfer might provide headers from several different places and
  46. they may then have different importance to the user and headers using the same
  47. name might be used. The \fIorigin\fP is a bitmask for what header sources you
  48. want. See the descriptions below.
  49. The \fIrequest\fP argument tells libcurl from which request you want headers
  50. from. A single transfer might consist of a series of HTTP requests and this
  51. argument lets you specify which particular individual request you want the
  52. headers from. 0 being the first request and then the number increases for
  53. further redirects or when multi-state authentication is used. Passing in -1 is
  54. a shortcut to "the last" request in the series, independently of the actual
  55. amount of requests used.
  56. libcurl stores and provides the actually used "correct" headers. If for
  57. example two headers with the same name arrive and the latter overrides the
  58. former, then only the latter will be provided. If the first header survives
  59. the second, then only the first one will be provided. An application using
  60. this API does not have to bother about multiple headers used wrongly.
  61. The memory for the returned struct is associated with the easy handle and
  62. subsequent calls to \fIcurl_easy_header(3)\fP will clobber the struct used in
  63. the previous calls for the same easy handle. Applications need to copy the
  64. data if it wants to keep it around. The memory used for the struct gets freed
  65. with calling \fIcurl_easy_cleanup(3)\fP of the easy handle.
  66. The first line in an HTTP response is called the status line. It is not
  67. considered a header by this function. Headers are the "name: value" lines
  68. following the status.
  69. This function can be used before (all) headers have been received and is fine
  70. to call from within libcurl callbacks. It will always return the state of the
  71. headers at the time it is called.
  72. .SH "The header struct"
  73. .nf
  74. struct curl_header {
  75. char *name;
  76. char *value;
  77. size_t amount;
  78. size_t index;
  79. unsigned int origin;
  80. void *anchor;
  81. };
  82. .fi
  83. The data \fBname\fP field points to, will be the same as the requested name
  84. but it might have a different case.
  85. The data \fBvalue\fP field points to, comes exactly as delivered over the
  86. network but with leading and trailing whitespace and newlines stripped
  87. off. The `value` data is null-terminated. For legacy HTTP/1 "folded headers",
  88. this API provides the full single value in an unfolded manner with a single
  89. whitespace between the lines.
  90. \fBamount\fP is how many headers using this name that exist, within the origin
  91. and request scope asked for.
  92. \fBindex\fP is the zero based entry number of this particular header, which in
  93. case this header was used more than once in the requested scope can be larger
  94. than 0 but is always less than \fBamount\fP.
  95. The \fBorigin\fP field in the "curl_header" struct has one of the origin bits
  96. set, indicating where from the header originates. At the time of this writing,
  97. there are 5 bits with defined use. The undocumented 27 remaining bits are
  98. reserved for future use and must not be assumed to have any particular value.
  99. \fBanchor\fP is a private handle used by libcurl internals. Do not modify.
  100. .SH ORIGINS
  101. .IP CURLH_HEADER
  102. The header arrived as a header from the server.
  103. .IP CURLH_TRAILER
  104. The header arrived as a trailer. A header that arrives after the body.
  105. .IP CURLH_CONNECT
  106. The header arrived in a CONNECT response. A CONNECT request is being done to
  107. setup a transfer "through" an HTTP(S) proxy.
  108. .IP CURLH_1XX
  109. The header arrived in an HTTP 1xx response. A 1xx response is an "intermediate"
  110. response that might happen before the "real" response.
  111. .IP CURLH_PSEUDO
  112. The header is an HTTP/2 or HTTP/3 pseudo header
  113. .SH EXAMPLE
  114. .nf
  115. struct curl_header *type;
  116. CURLHcode h =
  117. curl_easy_header(easy, "Content-Type", 0, CURLH_HEADER, -1, &type);
  118. .fi
  119. .SH AVAILABILITY
  120. Added in 7.83.0. Officially supported since 7.84.0.
  121. .SH RETURN VALUE
  122. This function returns a CURLHcode indicating success or error.
  123. .IP "CURLHE_BADINDEX (1)"
  124. There is no header with the requested index.
  125. .IP "CURLHE_MISSING (2)"
  126. No such header exists.
  127. .IP "CURLHE_NOHEADERS (3)"
  128. No headers at all have been recorded.
  129. .IP "CURLHE_NOREQUEST (4)"
  130. There was no such request number.
  131. .IP "CURLHE_OUT_OF_MEMORY (5)"
  132. Out of resources
  133. .IP "CURLHE_BAD_ARGUMENT (6)"
  134. One or more of the given arguments are bad.
  135. .IP "CURLHE_NOT_BUILT_IN (7)"
  136. HTTP or the header API has been disabled in the build.
  137. .SH "SEE ALSO"
  138. .BR curl_easy_nextheader "(3), " curl_easy_perform "(3), "
  139. .BR CURLOPT_HEADERFUNCTION "(3), " CURLINFO_CONTENT_TYPE "(3) "