curl_easy_nextheader.3 4.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596
  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_nextheader 3 "13 March 2022" "libcurl 7.83.0" "libcurl Manual"
  25. .SH NAME
  26. curl_easy_nextheader - get the next HTTP header
  27. .SH SYNOPSIS
  28. .nf
  29. #include <curl/curl.h>
  30. struct curl_header *curl_easy_nextheader(CURL *easy,
  31. unsigned int origin,
  32. int request,
  33. struct curl_header *prev);
  34. .fi
  35. .SH DESCRIPTION
  36. This function lets an application iterate over all previously received HTTP
  37. headers.
  38. The \fIorigin\fP argument is for specifying which headers to receive, as a
  39. single HTTP transfer might provide headers from several different places and
  40. they may then have different importance to the user and headers using the same
  41. name might be used. The \fIorigin\fP is a bitmask for what header sources you
  42. want. See the \fIcurl_easy_header(3)\fP man page for the origin descriptions.
  43. The \fIrequest\fP argument tells libcurl from which request you want headers
  44. from. A single transfer might consist of a series of HTTP requests and this
  45. argument lets you specify which particular individual request you want the
  46. headers from. 0 being the first request and then the number increases for
  47. further redirects or when multi-state authentication is used. Passing in -1 is
  48. a shortcut to "the last" request in the series, independently of the actual
  49. amount of requests used.
  50. It is suggested that you pass in the same \fBorigin\fP and \fBrequest\fP when
  51. iterating over a range of headers as changing the value mid-loop might give
  52. you unexpected results.
  53. If \fIprev\fP is NULL, this function returns a pointer to the first header
  54. stored within the given scope (origin + request).
  55. If \fIprev\fP is a pointer to a previously returned header struct,
  56. \fIcurl_easy_nextheader(3)\fP returns a pointer the next header stored within
  57. the given scope. This way, an application can iterate over all available
  58. headers.
  59. The memory for the struct this points to, is owned and managed by libcurl and
  60. is associated with the easy handle. Applications must copy the data if they
  61. want it to survive subsequent API calls or the life-time of the easy handle.
  62. .SH EXAMPLE
  63. .nf
  64. struct curl_header *prev = NULL;
  65. struct curl_header *h;
  66. /* extract the normal headers from the first request */
  67. while((h = curl_easy_nextheader(easy, CURLH_HEADER, 0, prev))) {
  68. print "%s: %s\\n", h->name, h->value);
  69. prev = h;
  70. }
  71. /* extract the normal headers + 1xx + trailers from the last request */
  72. unsigned int origin = CURLH_HEADER| CURLH_1XX | CURLH_TRAILER;
  73. while((h = curl_easy_nextheader(easy, origin, -1, prev))) {
  74. print "%s: %s\\n", h->name, h->value);
  75. prev = h;
  76. }
  77. .fi
  78. .SH AVAILABILITY
  79. Added in 7.83.0. Officially supported since 7.84.0.
  80. .SH RETURN VALUE
  81. This function returns the next header, or NULL when there are no more
  82. (matching) headers or an error occurred.
  83. If this function returns NULL when \fIprev\fP was set to NULL, then there are
  84. no headers available within the scope to return.
  85. .SH "SEE ALSO"
  86. .BR curl_easy_header "(3), " curl_easy_perform "(3) "