| .\" ************************************************************************** |
| .\" * _ _ ____ _ |
| .\" * Project ___| | | | _ \| | |
| .\" * / __| | | | |_) | | |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| .\" * Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. |
| .\" * |
| .\" * This software is licensed as described in the file COPYING, which |
| .\" * you should have received as part of this distribution. The terms |
| .\" * are also available at https://curl.se/docs/copyright.html. |
| .\" * |
| .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell |
| .\" * copies of the Software, and permit persons to whom the Software is |
| .\" * furnished to do so, under the terms of the COPYING file. |
| .\" * |
| .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY |
| .\" * KIND, either express or implied. |
| .\" * |
| .\" * SPDX-License-Identifier: curl |
| .\" * |
| .\" ************************************************************************** |
| .TH curl_easy_nextheader 3 "13 March 2022" "libcurl" "libcurl" |
| .SH NAME |
| curl_easy_nextheader - get the next HTTP header |
| .SH SYNOPSIS |
| .nf |
| #include <curl/curl.h> |
| |
| struct curl_header *curl_easy_nextheader(CURL *easy, |
| unsigned int origin, |
| int request, |
| struct curl_header *prev); |
| .fi |
| .SH DESCRIPTION |
| This function lets an application iterate over all previously received HTTP |
| headers. |
| |
| The \fIorigin\fP argument is for specifying which headers to receive, as a |
| single HTTP transfer might provide headers from several different places and |
| they may then have different importance to the user and headers using the same |
| name might be used. The \fIorigin\fP is a bitmask for what header sources you |
| want. See the \fIcurl_easy_header(3)\fP man page for the origin descriptions. |
| |
| The \fIrequest\fP argument tells libcurl from which request you want headers |
| from. A single transfer might consist of a series of HTTP requests and this |
| argument lets you specify which particular individual request you want the |
| headers from. 0 being the first request and then the number increases for |
| further redirects or when multi-state authentication is used. Passing in -1 is |
| a shortcut to "the last" request in the series, independently of the actual |
| amount of requests used. |
| |
| It is suggested that you pass in the same \fBorigin\fP and \fBrequest\fP when |
| iterating over a range of headers as changing the value mid-loop might give |
| you unexpected results. |
| |
| If \fIprev\fP is NULL, this function returns a pointer to the first header |
| stored within the given scope (origin + request). |
| |
| If \fIprev\fP is a pointer to a previously returned header struct, |
| \fIcurl_easy_nextheader(3)\fP returns a pointer the next header stored within |
| the given scope. This way, an application can iterate over all available |
| headers. |
| |
| The memory for the struct this points to, is owned and managed by libcurl and |
| is associated with the easy handle. Applications must copy the data if they |
| want it to survive subsequent API calls or the life-time of the easy handle. |
| .SH EXAMPLE |
| .nf |
| int main(void) |
| { |
| struct curl_header *prev = NULL; |
| struct curl_header *h; |
| |
| CURL *curl = curl_easy_init(); |
| if(curl) { |
| curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); |
| curl_easy_perform(curl); |
| |
| /* extract the normal headers from the first request */ |
| while((h = curl_easy_nextheader(curl, CURLH_HEADER, 0, prev))) { |
| printf("%s: %s\\n", h->name, h->value); |
| prev = h; |
| } |
| |
| /* extract the normal headers + 1xx + trailers from the last request */ |
| unsigned int origin = CURLH_HEADER| CURLH_1XX | CURLH_TRAILER; |
| while((h = curl_easy_nextheader(curl, origin, -1, prev))) { |
| printf("%s: %s\\n", h->name, h->value); |
| prev = h; |
| } |
| } |
| } |
| .fi |
| .SH AVAILABILITY |
| Added in 7.83.0. Officially supported since 7.84.0. |
| .SH RETURN VALUE |
| This function returns the next header, or NULL when there are no more |
| (matching) headers or an error occurred. |
| |
| If this function returns NULL when \fIprev\fP was set to NULL, then there are |
| no headers available within the scope to return. |
| .SH "SEE ALSO" |
| .BR curl_easy_header (3), |
| .BR curl_easy_perform (3) |