Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
curl_easy_header(3)	   Library Functions Manual	   curl_easy_header(3)

NAME
       curl_easy_header	- get an HTTP header

SYNOPSIS
       #include	<curl/curl.h>

       CURLHcode curl_easy_header(CURL *easy,
				  const	char *name,
				  size_t index,
				  unsigned int origin,
				  int request,
				  struct curl_header **hout);

DESCRIPTION
       curl_easy_header(3) returns a pointer to	a "curl_header"	struct in hout
       with  data  for	the  HTTP  response  header name. The case insensitive
       null-terminated header name should be specified without colon.

       index 0 means asking for	the first instance of the header. If  the  re-
       turned  header  struct has amount set larger than 1, it means there are
       more instances of the same header name available	to get.	Asking	for  a
       too big index makes CURLHE_BADINDEX get returned.

       The  origin  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 origin is	a bitmask  for
       what header sources you want. See the descriptions below.

       The  request 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.

       libcurl stores and provides the actually	used "correct" headers.	If for
       example	two headers with the same name arrive and the latter overrides
       the former, then	only the latter	is provided. If	the first header  sur-
       vives  the  second, then	only the first one is provided.	An application
       using this API does not have to	bother	about  multiple	 headers  used
       wrongly.

       The  memory  for	the returned struct is associated with the easy	handle
       and subsequent calls to curl_easy_header(3) clobber the struct used  in
       the  previous  calls for	the same easy handle. The application needs to
       copy the	data if	it wants to keep it around. The	memory	used  for  the
       struct gets freed with calling curl_easy_cleanup(3) of the easy handle.

       The first line in an HTTP response is called the	status line. It	is not
       considered  a  header  by  this function. Headers are the "name:	value"
       lines following the status.

       This function can be used before	(all) headers have been	 received  and
       is  fine	to call	from within libcurl callbacks. It returns the state of
       the headers at the time it is called.

The header struct
       struct curl_header {
	  char *name;
	  char *value;
	  size_t amount;
	  size_t index;
	  unsigned int origin;
	  void *anchor;
       };

       The data	name field points to, is the same as the requested  name,  but
       might have a different case.

       The  data  value	 field	points to, comes exactly as delivered over the
       network but with	leading	and trailing whitespace	and newlines  stripped
       off. The	value data is null-terminated. For legacy HTTP/1 "folded head-
       ers",  this  API	 provides  the full single value in an unfolded	manner
       with a single whitespace	between	the lines.

       amount is how many headers using	this name that exist, within the  ori-
       gin and request scope asked for.

       index  is  the zero based entry number of this particular header, which
       in case this header was used more than once in the requested scope  can
       be larger than 0	but is always less than	amount.

       The origin field	in the "curl_header" struct has	one of the origin bits
       set,  indicating	 where from the	header originates. At the time of this
       writing,	there are 5 bits with defined use. The undocumented 27 remain-
       ing bits	are reserved for future	use and	must not be  assumed  to  have
       any particular value.

       anchor is a private handle used by libcurl internals. Do	not modify.

ORIGINS
       CURLH_HEADER
	      The header arrived as a header from the server.

       CURLH_TRAILER
	      The header arrived as a trailer. A header	that arrives after the
	      body.

       CURLH_CONNECT
	      The  header  arrived in a	CONNECT	response. A CONNECT request is
	      being done to setup a transfer "through" an HTTP(S) proxy.

       CURLH_1XX
	      The header arrived in an HTTP 1xx	response. A 1xx	response is an
	      "intermediate" response that might happen	before the "real"  re-
	      sponse.

       CURLH_PSEUDO
	      The header is an HTTP/2 or HTTP/3	pseudo header

PROTOCOLS
       This functionality affects http only

EXAMPLE
       int main(void)
       {
	 struct	curl_header *type;
	 CURL *curl = curl_easy_init();
	 if(curl) {
	   CURLHcode h;
	   curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
	   curl_easy_perform(curl);
	   h = curl_easy_header(curl, "Content-Type", 0, CURLH_HEADER, -1, &type);
	   curl_easy_cleanup(curl);
	 }
       }

AVAILABILITY
       Added in	curl 7.83.0

RETURN VALUE
       This   function	returns	 a  CURLHcode  indicating  success  or	error.
       CURLHE_OK (0) means everything was OK,  non-zero	 means	an  error  oc-
       curred, see libcurl-errors(3).

SEE ALSO
       CURLINFO_CONTENT_TYPE(3),		    CURLOPT_HEADERFUNCTION(3),
       curl_easy_nextheader(3),	curl_easy_perform(3), libcurl-errors(3)

libcurl				  2025-06-03		   curl_easy_header(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=curl_easy_header&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help