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

FreeBSD Manual Pages

  
 
  

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

NAME
       CURLOPT_HEADERFUNCTION -	callback that receives header data

SYNOPSIS
       #include	<curl/curl.h>

       size_t header_callback(char *buffer,
			      size_t size,
			      size_t nitems,
			      void *userdata);

       CURLcode	curl_easy_setopt(CURL *handle, CURLOPT_HEADERFUNCTION,
				 header_callback);

DESCRIPTION
       Pass a pointer to your callback function, which should match the	proto-
       type shown above.

       This  callback  function	 gets invoked by libcurl as soon as it has re-
       ceived header data. The header callback is called once for each	header
       and  only  complete header lines	are passed on to the callback. Parsing
       headers is easy to do using this	callback. buffer points	to the	deliv-
       ered  data,  and	the size of that data is nitems; size is always	1. The
       provided	header line is not null-terminated. Do not modify  the	passed
       in buffer.

       The  pointer named userdata is the one you set with the CURLOPT_HEADER-
       DATA(3) option.

       Your callback should return the number of bytes actually	taken care of.
       If that amount differs from the amount passed to	 your  callback	 func-
       tion,  it  signals  an  error condition to the library. This causes the
       transfer	 to  get  aborted  and	the  libcurl  function	used   returns
       CURLE_WRITE_ERROR.

       You  can	 also  abort  the  transfer by returning CURL_WRITEFUNC_ERROR.
       (7.87.0)

       A complete HTTP header that is passed to	this function  can  be	up  to
       CURL_MAX_HTTP_HEADER  (100K) bytes and includes the final line termina-
       tor.

       If this option is not set, or if	it is set to NULL, but CURLOPT_HEADER-
       DATA(3) is set to anything but NULL, the	function used  to  accept  re-
       sponse  data  is	used instead. That is the function specified with CUR-
       LOPT_WRITEFUNCTION(3), or if it is not specified	or NULL	- the default,
       stream-writing function.

       It is important to note that the	callback is invoked for	the headers of
       all responses received after initiating a request and not just the  fi-
       nal  response. This includes all	responses which	occur during authenti-
       cation negotiation. If you need to operate on only the headers from the
       final response, you need	to collect headers in  the  callback  yourself
       and use HTTP status lines, for example, to delimit response boundaries.

       For  an HTTP transfer, the status line and the blank line preceding the
       response	body are both included as headers and passed to	this function.

       When a server sends a  chunked  encoded	transfer,  it  may  contain  a
       trailer.	 That  trailer	is  identical  to an HTTP header and if	such a
       trailer is received it is passed	to the application using this callback
       as well.	There are several ways to detect it being a trailer and	not an
       ordinary	header:	1) it comes after the response-body. 2)	it comes after
       the final header	line (CR LF) 3)	a Trailer: header  among  the  regular
       response-headers	mention	what header(s) to expect in the	trailer.

       For non-HTTP protocols like FTP,	POP3, IMAP and SMTP this function gets
       called with the server responses	to the commands	that libcurl sends.

       A   more	  convenient   way  to	get  HTTP  headers  might  be  to  use
       curl_easy_header(3).

LIMITATIONS
       libcurl does not	unfold HTTP "folded  headers"  (deprecated  since  RFC
       7230).  A folded	header is a header that	continues on a subsequent line
       and starts with a whitespace. Such folds	are passed to the header call-
       back as separate	ones, although strictly	they are just continuations of
       the previous lines.

DEFAULT
       Nothing.

PROTOCOLS
       This functionality affects ftp, http, imap, pop3	and smtp

EXAMPLE
       static size_t header_callback(char *buffer, size_t size,
				     size_t nitems, void *userdata)
       {
	 /* received header is nitems *	size long in 'buffer' NOT ZERO TERMINATED */
	 /* 'userdata' is set with CURLOPT_HEADERDATA */
	 return	nitems * size;
       }

       int main(void)
       {
	 CURL *curl = curl_easy_init();
	 if(curl) {
	   curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");

	   curl_easy_setopt(curl, CURLOPT_HEADERFUNCTION, header_callback);

	   curl_easy_perform(curl);
	 }
       }

AVAILABILITY
       Added in	curl 7.7.2

RETURN VALUE
       curl_easy_setopt(3) returns a CURLcode indicating success or error.

       CURLE_OK	(0) means everything was OK, non-zero means an error occurred,
       see libcurl-errors(3).

SEE ALSO
       CURLOPT_HEADERDATA(3), CURLOPT_WRITEFUNCTION(3),	curl_easy_header(3)

libcurl				  2025-06-03	     CURLOPT_HEADERFUNCTION(3)

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

home | help